Operations¶
Operations List¶
Arithmetic¶
Add, subtract, multiply, or divide all grey values of an image with the given values.
Intended to be used on: Any
When: If you want to offset or rescale an image.
- param mult_val:
The multiplication value.
- param div_val:
The division value.
- param add_val:
The addition value.
- param sub_val:
The subtraction value.
- param cores:
The number of cores that will be used to process the data.
Circular Mask¶
Masks a circular area around the center of the image, by setting it to a specified value.
Intended to be used on: Reconstructed slices
When: To remove reconstruction artifacts on the outer edge of the image.
Caution: Ensure that the radius does not mask data from the sample.
- param data:
Input data as a 3D numpy.ndarray
- param circular_mask_ratio:
The ratio to the full image. The ratio must be 0 < ratio < 1
- param circular_mask_value:
The value that all pixels in the mask will be set to.
Clip Values¶
Clips grey values of the image based on the parameters. Can be used to remove outliers and noise (e.g. negative values) from reconstructed images.
Intended to be used on: Projections and reconstructed slices
When: To remove a range of pixel values from the data.
Caution: Make sure the value range does not clip information from the sample.
- param data:
Input data as a 3D numpy.ndarray.
- param clip_min:
The minimum value to be clipped from the data. If None is provided then no lower threshold is used.
- param clip_max:
The maximum value to be clipped from the data. If None is provided then no upper threshold is used.
- param clip_min_new_value:
The value to use when replacing values less than clip_min. If None is provided then the value of clip_min is used.
- param clip_max_new_value:
The value to use when replacing values greater than clip_max. If None is provided then the value of clip_max is used.
Crop Coordinates¶
Crop a region of interest from the image.
Intended to be used on: A stack of projections, or reconstructed slices
When: To select part of the image that is to be processed further; this reduces memory usage and can greatly improve the speed of reconstruction.
Caution: Make sure the region of cropping does not crop parts of the sample during the rotation of the sample in the dataset.
- param region_of_interest:
Crop original images using these coordinates. The selection is a rectangle and expected order is - Left Top Right Bottom.
Divide¶
Divides a stack of images by a value. That value can be the pixel size, and can be specified in either microns or cms, to obtain attenuation values.
Intended to be used on: Reconstructed slices
When: To calculate attenuation values by dividing by the pixel size in microns
Caution: Check preview values before applying divide
Flat-fielding¶
Uses the flat (open beam) and dark images to normalise a stack of images (radiograms, projections), and to correct for a beam profile, scintillator imperfections and/or detector inhomogeneities. This operation produces images of transmission values.
In practice, several open beam and dark images are averaged in the flat-fielding process.
Intended to be used on: Projections
When: As one of the first pre-processing steps
Caution: Make sure the correct stacks are selected for flat and dark.
Caution: Check that the flat and dark images don’t have any very bright pixels, or this will introduce additional noise in the sample. Remove outliers before flat-fielding.
- param flat_before:
Flat (open beam) image to use in normalization, collected before the sample was imaged
- param flat_after:
Flat (open beam) image to use in normalization, collected after the sample was imaged
- param dark_before:
Dark image to use in normalization, collected before the sample was imaged
- param dark_after:
Dark image to use in normalization, collected after the sample was imaged
- param selected_flat_fielding:
Select which of the flat fielding methods to use, just Before stacks, just After stacks or combined.
- param use_dark:
Whether to use dark frame subtraction
- param cores:
The number of cores that will be used to process the data.
- param chunksize:
The number of chunks that each worker will receive.
Gaussian¶
Applies Gaussian filter to the data.
Intended to be used on: Projections or reconstructed slices
When: As a pre-processing or post-reconstruction step to reduce noise.
- param data:
Input data as a 3D numpy.ndarray
- param size:
Size of the kernel
- param mode:
The mode with which to handle the edges. One of [reflect, constant, nearest, mirror, wrap]. Modes are described in the SciPy documentation.
- param order:
The order of the filter along each axis is given as a sequence of integers, or as a single number. An order of 0 corresponds to convolution with a Gaussian kernel. An order of 1, 2, or 3 corresponds to convolution with the first, second or third derivatives of a Gaussian. Higher order derivatives are not implemented
- param cores:
The number of cores that will be used to process the data.
- param chunksize:
The number of chunks that each worker will receive.
Median¶
Applies Median filter to the data.
Intended to be used on: Projections or reconstructed slices
When: As a pre-processing or post-reconstruction step to reduce noise.
Note: NaN values are preserved through the filter. They are treated as negative infinity while calculating neighbouring pixels.
- param data:
Input data as an Images object.
- param size:
Size of the kernel
- param mode:
The mode with which to handle the edges. One of [reflect, constant, nearest, mirror, wrap]. Modes are described in the SciPy documentation.
- param cores:
The number of cores that will be used to process the data.
- param chunksize:
The number of chunks that each worker will receive.
- param force_cpu:
Whether or not to use the CPU.
Monitor Normalisation¶
Normalises the image data using the average count of a beam monitor from the experiment log file. This scaling operation is an alternative to ROI normalisation and allows to account for beam fluctuations and different exposure times of projections.
Intended to be used on: Projections
When: As a pre-processing step to normalise the grey value ranges of the data.
NaN Removal¶
Replaces the NaNs with a specified value or the median of neighbouring pixels.
Intended to be used on: Projections
When: To remove NaNs before reconstruction.
Note that the median method cannot remove continuous blocks of NaNs.
- param data:
The input data.
- param mode_value:
Values to replace NaNs with. One of [“Constant”, “Median”]
- param replace_value:
In constant mode, the value to replace NaNs with.
- param cores:
The number of cores that will be used to process the data.
- param chunksize:
The number of chunks that each worker will receive.
Remove Outliers¶
Removes pixel values that are found to be outliers as defined by the given parameters.
Intended to be used on: Projections
When: As a pre-processing step to reduce very bright or dead pixels in the data.
Caution: This should usually be one of the first steps applied to the data, flat and dark images, to remove pixels with very large values that will cause issues for flat-fielding.
- param diff:
Pixel value difference above which to crop bright pixels
- param radius:
Size of the median filter to apply
- param mode:
Whether to remove bright or dark outliers One of [OUTLIERS_BRIGHT, OUTLIERS_DARK]
- param cores:
The number of cores that will be used to process the data.
Rebin¶
Rebin the image to reduce the resolution.
This filter temporarily increases memory usage, while the image is being rebinned. The memory usage will be lowered after the filter has finished executing.
Intended to be used on: Any data
When: If you want to reduce the data size and to smoothen the image.
- param rebin_param:
int, float or tuple int - Percentage of current size. float - Fraction of current size. tuple - Size of the output image (x, y).
- param mode:
Interpolation to use for re-sizing (‘nearest’, ‘lanczos’, ‘bilinear’, ‘bicubic’ or ‘cubic’).
- param cores:
The number of cores that will be used to process the data.
- param chunksize:
The number of chunks that each worker will receive.
Remove all stripes¶
Stripe and ring artifact removal. Remove all types of stripe artifacts by combining algorithm 6, 5, and 3 in Vo et al., Optics Express 28396 (2018).
Source: https://github.com/algotom/algotom
Intended to be used on: Sinograms
When: If stripes artifacts are present that have not been removed with outliers + flat-fielding the projections
Caution: Horizontal stripes caused by changes in image intensity (pixel values) should be fixed by ROI Normalisation instead!
Remove dead stripes¶
Stripe and ring artifact removal. Algorithm 6 in Vo et al., Optics Express 28396 (2018). Remove unresponsive or fluctuating stripes by: locating stripes, correction by interpolation.
Source: https://github.com/algotom/algotom
Intended to be used on: Sinograms
When: If stripes artifacts are present that have not been removed with outliers + flat-fielding the projections
Caution: Horizontal stripes caused by changes in image intensity (pixel values) should be fixed by ROI Normalisation instead!
Remove large stripes¶
Stripe and ring artifact removal: Algorithm 5 in Vo et al., Optics Express 28396 (2018). Remove large stripes by: locating stripes, normalizing them to remove full stripes, using the sorting technique to remove partial stripes.
Source: https://github.com/algotom/algotom
Intended to be used on: Sinograms When: If stripes artifacts are present that have not been removed with outliers + flat-fielding the projections
Caution: Horizontal stripes caused by changes in image intensity (pixel values) should be fixed by ROI Normalisation instead!
Stripe Removal¶
Stripe and ring artifact removal operations wrapped from TomoPy.
Source: https://tomopy.readthedocs.io/en/latest/api/tomopy.prep.stripe.html
Intended to be used on: Sinograms
When: If stripes artifacts are present that have not been removed with outliers + flat-fielding the projections
Caution: Horizontal stripes caused by changes in image intensity (pixel values) should be fixed by ROI Normalisation instead!
- param wf:
Specify parameters for the wavelet-fourier filter. Acceptable keywords are: level (default None, type int, optional parameter) Number of discrete wavelet transform levels. wname (default ‘db5’, type str, optional parameter) Type of the wavelet filter. ‘haar’, ‘db5’, ‘sym5’. sigma (default 2, type float, optional parameter) Damping parameter in Fourier space. pad (default True, type bool, optional parameter) If True, extend the size of the sinogram by padding with zeros.
- param ti:
Specify parameters for the Titarenko filter. Acceptable keywords are: nblock (default:0, int, optional) Number of blocks. alpha (default: 1.5, int, optional) Damping factor.
- param sf:
Specify parameters for the smoothing-filter. Acceptable keywords are: size (default: 5, int, optional) Size of the smoothing filter.
Remove stripes with filtering¶
Stripe and ring artifact removal. Combination of algorithm 2 and algorithm 3 in Vo et al., Optics Express 28396 (2018). Removing stripes using the filtering and sorting technique.
Source: https://github.com/algotom/algotom
Intended to be used on: Sinograms
When: If stripes artifacts are present that have not been removed with outliers + flat-fielding the projections
Caution: Horizontal stripes caused by changes in image intensity (pixel values) should be fixed by ROI Normalisation instead!
Remove stripes with sorting and fitting¶
Stripe and ring artifact removal. Combination of algorithm 3 and 1 in Vo et al., Optics Express 28396 (2018). Remove stripes using the sorting and fitting technique.
Source: https://github.com/algotom/algotom
Intended to be used on: Sinograms
When: If stripes artifacts are present that have not been removed with outliers + flat-fielding the projections
Caution: Horizontal stripes caused by changes in image intensity (pixel values) should be fixed by ROI Normalisation instead!
Rescale¶
Rescales the image data to a new [0, maximum output] range.
Intended to be used on: Any
When: Automatically used when saving as unsigned integer image formats, to avoid clipping negative values
Ring Removal¶
Remove ring artifacts from images in the reconstructed domain.
Intended to be used on: Reconstructed slices
When: To remove ring-artifacts that have not been removed, or have been introduced by pre-processing
- param center_mode:
Whether to use the center of the image or a user-defined value
- param center_x:
(float, optional) abscissa location of center of rotation
- param center_y:
(float, optional) ordinate location of center of rotation
- param thresh:
(float, optional) maximum value of an offset due to a ring artifact
- param thresh_max:
(float, optional) max value for portion of image to filter
- param thresh_min:
(float, optional) min value for portion of image to filer
- param theta_min:
(int, optional) minimum angle in degrees to be considered ring artifact
- param rwidth:
(int, optional) Maximum width of the rings to be filtered in pixels
ROI Normalisation¶
Normalises the image data by using the average value in a no-sample (air) region of interest (ROI) of the image. This scaling operation allows to account for beam fluctuations and different exposure times of projections.
Intended to be used on: Projections
When: Always, to ensure that any fluctuations in beam intensity are normalised.
Note: Beam fluctuations are visible by horizontal lines in the sinograms, as some projections are brighter/darker than the neighbours. This can be fixed with this operation.
- param region_of_interest:
The order is - Left Top Right Bottom. The air region for which grey values are summed up and used for normalisation/scaling.
- param normalisation_mode:
Controls what the ROI counts are normalised to. ‘Preserve Max’ : Normalisation is scaled such that the maximum pixel value of the stack is equal before and after the operation. ‘Stack Average’ : The mean value of the air region across all projections is preserved. ‘Flat Field’ : The mean value of the air regions in the projections is made equal to the mean value of the air region in the flat field image.
- param flat_field:
Flat field to use if ‘Flat Field’ mode is enabled.
- param cores:
The number of cores that will be used to process the data.
- param chunksize:
The number of chunks that each worker will receive.
Rotate Stack¶
Rotates the image data by an arbitrary degree counter-clockwise.
Intended to be used on: Projections
When: 90 or 270 degree rotation for rotation axis to be vertical for some camera types.
Caution: Rotations of images others than multiples of 90 degrees could introduce additional artifacts in the reconstructed volume. Such rotations are usually not required as small tilts can be taken into account at the reconstruction stage.
- param data:
stack of sample images
- param angle:
The rotation to be performed, in degrees
- param cores:
cores for parallel execution
- param chunksize:
chunk for each worker