Configure efficient pipelines

Here we focus on several important aspects which can be helpful while configuring a process list. In order to construct more efficient pipelines one needs to be familiar with Method pattern and method order, Re-slicing, and Sections.

Method pattern and method order

An HTTomo pipeline consists of multiple methods ordered sequentially and is executed in the given serial order (meaning that there is no branching in HTTomo pipelines). Behind the scenes HTTomo will take care of providing the input data for each method, and passing the output data of each method to the next method.

Different methods require data to be provided in different orientations (ie, the direction of slicing an array). In order to satisfy those requirements, the notion of a method having a pattern was introduced in HTTomo, i.e., every method has a pattern associated with it. So far HTTomo supports three types of patterns: projection, sinogram, and all.

Note

Transitioning between methods that change the pattern from projection to sinogram or vice versa will trigger a costly Re-slicing operation. Methods with pattern all inherit the pattern of the previous method.

In order to minimise the amount of reslice operations it is best to group methods together based on the pattern. For example, putting methods that work with projections in one group, and methods that work with sinograms in another group. It may not always be possible to group the methods in such way, especially with longer pipelines. However, it’s useful to keep this in mind if one seeks the most computationally efficient pipeline.

The pattern of any supported method can be found in Library files.

Note

Currently, HTTomo loaders use the projection pattern by default, therefore it’s best for efficiency purposes that the first method after the loader has the projection pattern. It is also recommended to place Centre of Rotation (CoR) methods right after the loader.

Library files

Here is the list of library files for backends where patterns and other fixed arguments for methods are specified. When HTTomo operates with a certain method it always refers to its library file in order get the specific requirements for that method.

TomoPy’s library file

sim:
  project:
    add_drift:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    add_focal_spot_blur:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    add_gaussian:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    add_poisson:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    add_rings:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    add_salt_pepper:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    add_zingers:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    project:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    project2:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    project3:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
misc:
  corr:
    adjust_range:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    circ_mask:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    gaussian_filter:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    median_filter:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    median_filter3d:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: True
    median_filter_nonfinite:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_nan:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_neg:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_outlier:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_outlier1d:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_outlier3d:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: True
    remove_ring:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    sobel_filter:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
  morph:
    downsample:
      pattern: all
      output_dims_change: True
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    pad:
      pattern: all
      output_dims_change: True
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    sino_360_to_180:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    trim_sinogram:
      pattern: sinogram
      output_dims_change: True
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    upsample:
      pattern: all
      output_dims_change: True
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
prep:
  alignment:
    add_jitter:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    add_noise:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    align_joint:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    align_seq:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    blur_edges:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    distortion_correction_proj:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    distortion_correction_sino:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    scale:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    shift_images:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
  normalize:
    minus_log:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    normalize:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    normalize_roi:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    normalize_bg:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    normalize_nf:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
  phase:
    retrieve_phase:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
  stripe:
    remove_all_stripe:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_stripe_fw:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_stripe_ti:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_stripe_sf:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_stripe_based_sorting:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_stripe_based_filtering:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_stripe_based_fitting:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_large_stripe:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_dead_stripe:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    remove_stripe_based_interpolation:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    stripes_detect3d:
      pattern: sinogram
      implementation: cpu
      output_dims_change: False
      memory_gpu: None
      save_result_default: False
      padding: True
    stripes_mask3d:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: True
recon:
  algorithm:
    recon:
      pattern: sinogram
      output_dims_change: True
      implementation: cpu
      memory_gpu: None
      save_result_default: True
      padding: False
  rotation:
    find_center:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    find_center_pc:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: True
      padding: False
    find_center_vo:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
  wrappers:
    astra:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    ufo_fbp:
      pattern: sinogram
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    ufo_dfi:
      pattern: sinogram
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
    lprec:
      pattern: sinogram
      output_dims_change: True
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False

Httomolibgpu’s library file

misc:
  corr:
    median_filter:
      pattern: all
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: True
      memory_gpu:
        multiplier: 2.1
        method: direct
    remove_outlier:
      pattern: all
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: True
      memory_gpu:
        multiplier: 2.1
        method: direct
  morph:
    sino_360_to_180:
      pattern: sinogram
      output_dims_change: True
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: None
        method: module
    data_resampler:
      pattern: all
      output_dims_change: True
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: None
        method: module
  rescale:
    rescale_to_int:
      pattern: all
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: None
        method: module
prep:
  normalize:
    normalize:
      pattern: projection
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: None
        method: module
  phase:
    paganin_filter_tomopy:
      pattern: projection
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: None
        method: module
    paganin_filter_savu:
      pattern: projection
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: None
        method: module
  alignment:
    distortion_correction_proj_discorpy:
      pattern: projection
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: 1.2
        method: direct
  stripe:
    remove_stripe_based_sorting:
      pattern: sinogram
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: 1.17
        method: direct
    remove_stripe_ti:
      pattern: sinogram
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: None
        method: module
    remove_all_stripe:
      pattern: sinogram
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: None
        method: module
recon:
  algorithm:
    FBP:
      pattern: sinogram
      output_dims_change: True
      implementation: gpu_cupy
      save_result_default: True
      padding: False
      memory_gpu:
        multiplier: None
        method: module
    SIRT:
      pattern: sinogram
      output_dims_change: True
      implementation: gpu_cupy
      save_result_default: True
      padding: False
      memory_gpu:
        multiplier: None
        method: module
    CGLS:
      pattern: sinogram
      output_dims_change: True
      implementation: gpu_cupy
      save_result_default: True
      padding: False
      memory_gpu:
        multiplier: None
        method: module
  rotation:
    find_center_vo:
      pattern: projection
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: 0
        method: direct
    find_center_360:
      pattern: projection
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: 0
        method: direct
    find_center_pc:
      pattern: projection
      output_dims_change: False
      implementation: gpu_cupy
      save_result_default: False
      padding: False
      memory_gpu:
        multiplier: 0
        method: direct

Httomolib’s library file

misc:
  morph:
    data_reducer:
      pattern: all
      output_dims_change: True
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
  images:
    save_to_images:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
  segm:
    binary_thresholding:
      pattern: all
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False
prep:
  phase:
    paganin_filter:
      pattern: projection
      output_dims_change: False
      implementation: cpu
      memory_gpu: None
      save_result_default: False
      padding: False

Grouping CPU/GPU methods

There are different implementations of methods in Supported libraries, and can be classified into three categories:

• cpu methods. These are traditional CPU implementations in Python or other compiled languages. The exposed TomoPy functions are mostly pure CPU.

• gpu methods. These are methods that use GPU devices and require an input array in CPU memory (e.g. Numpy ndarray).

• gpu_cupy methods. These are a special group of methods, mostly from the HTTomolibgpu library, that are executed on GPU devices using the CuPy API. The main difference between gpu_cupy methods and gpu methods is that gpu_cupy methods require CuPy arrays as input instead of Numpy arrays. The CuPy arrays are then kept in GPU memory across any consecutive gpu_cupy methods until they are requested back on the CPU. This approach allows more flexibility with the sequences of GPU methods, as they can be chained together for more efficient processing.

Note

If GPUs are available to the user, it is recommended to use gpu_cupy or gpu methods in process lists. The methods themselves are usually optimised for performance and HTTomo will take care of chaining the methods together to avoid unnecessary CPU-GPU data transfers.

The implementation of any supported method can be found in Library files.

Minimise writing to disk

HTTomo does not require Saving intermediate files by default. If the result of a method is not needed as a separate file, then there is no reason for it to be written to disk. This is because saving intermediate files can significantly slow down the execution time.