# 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.

### 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

- param value
The division value.

- param unit
The unit of the divisor.

### 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

### 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

### 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 ImageStack 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 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.

### 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]

### 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
The mode with which to handle the edges. One of (‘constant’, ‘edge’, ‘symmetric’, ‘reflect’, ‘wrap’).

### 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!

- param snr
The ratio used to segment between useful information and noise. Greater is less sensitive.

- param la_size
The window size of the median filter to remove large stripes.

- param sm_size
The window size of the median filter to remove small-to-medium stripes.

- param dim
Whether to perform the median on 1D or 2D view of the data.

### 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!

- param snr
The ratio value.

- param size
The window size of the median filter to remove dead stripes.

### 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!

- param snr
The ratio value.

- param size
The window size of the median filter to remove large stripes.

### 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

- param sigma
The sigma of the Gaussian window used to separate the low-pass and high-pass components of the intensity profile of each column.

- param size
The window size of the median filter to remove large stripes.

- param window_dim
Whether to perform the median on 1D or 2D view of the data.

- param filtering_dim
Whether to use a 1D or 2D low-pass filter. This uses different Sarepy methods. filtering and sorting technique.

### 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

- param order
The polynomial fit order. Check algotom docs for more information.

- param sigma
The sigma of the Gaussian window in the x-direction. sorting and fitting technique.

### 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

- param min_input
The Minimum value of the data that will be used. Anything below this will be clipped to 0.

- param max_input
Maximum value of the data that will be used. Anything above it will be clipped to 0.

- param max_output
Maximum value of the OUTPUT images. They will be rescaled to range [0, MAX OUTPUT].

### 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. ‘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.

### 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.