imars3d.backend.corrections package

iMars3D: module for image corrections.

Submodules

imars3d.backend.corrections.denoise module

Image noise reduction (denoise) module.

class imars3d.backend.corrections.denoise.denoise(*args, **params)[source]

Bases: ParameterizedFunction

Denoise the image stack with the median filter.

Parameters:

  • arrays (np.ndarray) – The image stack to denoise.

  • method (str = 'bilateral') – The denoise method to use.

  • median_filter_kernel (int = 3) – The kernel size of the median filter, only valid for ‘median’ method.

  • bilateral_sigma_color (float = 0.02) – The sigma of the color/gray space, only valid for ‘bilateral’ method.

  • bilateral_sigma_spatial (float = 5.) – The sigma of the spatial space, only valid for ‘bilateral’ method.

  • max_workers (int = 0) – The number of cores to use for parallel processing, default is 0, which means using all available cores.

  • tqdm_class (panel.widgets.Tqdm) – Class to be used for rendering tqdm progress

Return type:

The denoised image stack.

imars3d.backend.corrections.denoise.denoise_by_bilateral(arrays: ndarray, sigma_color: float = 0.02, sigma_spatial: float = 5.0, max_workers: int = 0, tqdm_class=None) → ndarray[source]

Denoise the image stack with the bilateral filter.

Parameters:

  • arrays – The image stack to denoise.

  • sigma_color – Standard deviation for grayvalue/color distance (radiometric similarity).

  • sigma_spatial – Standard deviation for range distance.

  • max_workers – The number of cores to use for parallel processing, default is 0, which means using all available cores.

  • tqdm_class (panel.widgets.Tqdm) – Class to be used for rendering tqdm progress

Return type:

The denoised image stack.

imars3d.backend.corrections.denoise.denoise_by_bilateral_2d(array_2d: ndarray, sigma_color: float = 0.02, sigma_spatial: float = 5.0) → ndarray[source]

Denoise an image with the bilateral filter.

Parameters:

  • array_2d – The image to denoise.

  • sigma_color – Standard deviation for grayvalue/color distance (radiometric similarity).

  • sigma_spatial – Standard deviation for range distance.

Return type:

The denoised image.

imars3d.backend.corrections.denoise.denoise_by_median(arrays: ndarray, median_filter_kernel: int = 3, max_workers: int = 0) → ndarray[source]

Denoise the image stack with the median filter.

Parameters:

  • arrays – The image stack to denoise.

  • median_filter_kernel – The kernel size of the median filter.

  • max_workers – The number of cores to use for parallel processing, default is 0, which means using all available cores.

Return type:

The denoised image stack.

imars3d.backend.corrections.denoise.measure_noiseness(image: ndarray) → float[source]

Measure the noiseness of the image.

Reference paper, doi:10.1006/cviu.1996.0060

Parameters:

image – The image to measure the noiseness of.

Return type:

The noiseness of the image.

imars3d.backend.corrections.denoise.measure_sharpness(image: ndarray) → float[source]

Measure the sharpness of the image, using norm of gradient as approximation.

Parameters:

image – The image to measure the sharpness of.

Return type:

The sharpness of the image.

imars3d.backend.corrections.gamma_filter module

iMars3D: gamma filter module.

class imars3d.backend.corrections.gamma_filter.gamma_filter(*args, **params)[source]

Bases: ParameterizedFunction

Gamma filter.

Replace near saturated pixels (due to gamma radiation) with median values. The median filtering is carried out by tomopy.remove_outlier. If selective median filtering is enabled (default), only the pixels greater than the specified threshold are replaced.

Parameters:

  • arrays (np.ndarray) – 3D array of images, the first dimension is the rotation angle omega

  • threshold (int = -1) – threshold for saturation, default is -1, which means using the internally defined threshold (see source code)

  • median_kernel (int = 5) – size of the median filter kernel, default is 5

  • axis (int = 0) – axis along which to chunk the array for parallel median filtering, default is 0.

  • max_workers (int = 0) – number of cores to use for parallel median filtering, default is 0, which means using all available cores.

  • selective_median_filter (bool = True) – whether to use selective median filtering, default is True.

  • diff_tomopy (float = -1) – threshold passed to tomopy for median filter based outlier detection. Negative values will use the internal default value (see source code).

Returns:

corrected 3D array of images, the first dimension is the rotation angle omega

Return type:

np.ndarray

imars3d.backend.corrections.intensity_fluctuation_correction module

iMars3D’s intensity fluctuation correction module.

class imars3d.backend.corrections.intensity_fluctuation_correction.intensity_fluctuation_correction(*args, **params)[source]

Bases: ParameterizedFunction

Correct for intensity fluctuation in the radiograph.

Parameters:

  • ct (np.ndarray) – The image/radiograph stack to correct for beam intensity fluctuation.

  • air_pixels (int = 5) – Number of pixels at each boundary to calculate the scaling factor. When a negative number is given, the auto air region detection will be used instead of tomopy.

  • sigma (int = 3) – The standard deviation of the Gaussian filter, only valid when using the auto air region detection via canny edge detection from skimage.

  • max_workers (int = 0) – The number of cores to use for parallel processing, default is 0, which means using all available cores.

  • tqdm_class (panel.widgets.Tqdm) – Class to be used for rendering tqdm progress

Return type:

The corrected image/radiograph stack.

imars3d.backend.corrections.intensity_fluctuation_correction.intensity_fluctuation_correction_skimage(image: ndarray, sigma: int = 3) → ndarray[source]

IFC via skimage.

Correct for intensity fluctuation in the radiograph using skimage to auto detect the air region (adapted from iMars3dv1.filter.ifc).

Parameters:

  • image (np.ndarray) – The image/radiograph (2D) to correct for beam intensity fluctuation.

  • sigma (int) – The standard deviation of the Gaussian filter for the canny edge detection.

Return type:

The corrected image/radiograph (2D).

Notes

This method here is assuming the beam is decaying uniformly over time whereas the tomopy version is assuming different region decays slightly different, hence the linear interpolation between left and right air pixels. In most cases, a uniform decay is a good approximation as neutron beam tends to be very stable.

class imars3d.backend.corrections.intensity_fluctuation_correction.normalize_roi(*args, **params)[source]

Bases: ParameterizedFunction

Normalize raw projection data using an average of a selected window on projection images.

Parameters:

  • ct (np.ndarray) – The image/radiograph stack.

  • roi (int = 5) – [top-left, top-right, bottom-left, bottom-right] pixel coordinates.

  • max_workers (int = 0) – The number of cores to use for parallel processing, default is 0, which means using all available cores.

Return type:

The normalized image/radiograph stack.

imars3d.backend.corrections.ring_removal module

iMars3D’s ring artifact correction module.

class imars3d.backend.corrections.ring_removal.bm3d_ring_removal(*args, **params)[source]

Bases: ParameterizedFunction

Remove ring artifact from sinograms using BM3D method.

This method requires BM3D suite, which can be installed by pip install bm3d_streak_removal.

ref: 10.1107/S1600577521001910

Parameters:

  • arrays (np.ndarray) – Input radiograph stack.

  • extreme_streak_iterations (int) – Number of iterations for extreme streak attenuation.

  • extreme_detect_lambda (float) – Consider streaks which are stronger than lambda * local_std as extreme.

  • extreme_detect_size (int) – Half window size for extreme streak detection – total (2*s + 1).

  • extreme_replace_size (int) – Half window size for extreme streak replacement – total (2*s + 1).

  • max_bin_iter_horizontal (int) – The number of total horizontal scales (counting the full scale).

  • bin_vertical (int) – The factor of vertical binning, e.g. bin_vertical=32 would perform denoising in 1/32th of the original vertical size.

  • filter_strength (float) – Strength of BM4D denoising (>0), where 1 is the standard application, >1 is stronger, and <1 is weaker.

  • use_slices (bool) – If True, the sinograms will be split horizontally across each binning iteration into overlapping.

  • slice_sizes (list) – A list of horizontal sizes for use of the slicing if use_slices=True. By default, slice size is either 39 pixels or 1/5th of the total width of the current iteration, whichever is larger.

  • slice_step_sizes (list) – List of number of pixels between slices obtained with use_slices=True, one for each binning iteration. By default 1/4th of the corresponding slice size.

  • denoise_indices (list) – Indices of sinograms to denoise; by default, denoises the full stack provided.

Return type:

Radiograph stack with ring artifact removed.

Notes

1. The parallel processing is handled at the bm3d level, and it is an intrinsic slow correction algorithm running on CPU. 2. The underlying BM3D library uses stdout to print progress instead of a progress bar.

class imars3d.backend.corrections.ring_removal.remove_ring_artifact(*args, **params)[source]

Bases: ParameterizedFunction

Remove ring artifact from radiograph stack using Ketcham method.

ref: 10.1117/12.680939

Parameters:

  • arrays (np.ndarray) – Input radiograph stack.

  • kernel_size (int = 5) – The size of the kernel (moving window) during local smoothing with median filter.

  • sub_division (int = 10) – Sub-dividing the sinogram into subsections (along rotation angle axis).

  • correction_range (tuple = (0.9, 1.1)) – Multiplicative correction factor is capped within given range.

  • max_workers (int = 0) – Number of cores to use for parallel processing.

  • tqdm_class (panel.widgets.Tqdm) – Class to be used for rendering tqdm progress

Return type:

Radiograph stack with ring artifact removed.

class imars3d.backend.corrections.ring_removal.remove_ring_artifact_Ketcham(*args, **params)[source]

Bases: ParameterizedFunction

Ketcham’s ring artifact removal method.

Use the Ketcham method (doi:10.1117/12.680939) to remove ring artifact from given sinogram.

Parameters:

  • sinogram (np.ndarray) – Input sinogram.

  • kernel_size (int = 5) – The size of the kernel (moving window) during local smoothing via median filter.

  • sub_division (int = 10) – Sub-dividing the sinogram into subsections (along rotation angle axis).

  • correction_range (tuple = (0.9, 1.1)) – Multiplicative correction factor is capped within given range.

Return type:

Sinogram with ring artifact removed.

Note

  1. The ring artifact refers to the halo type artifacts present in the final reconstruction results, which is often caused by local detector/pixel gain error during measurement.

  2. This method can only be used on a single sinogram.

  3. This method is assuming the ring artifact is of multiplicative nature, i.e. measured = signal * error.