algotom.util.utility
¶
Module of utility methods: 1- Methods for parallel computing, geometric transformation, masking. 2- Methods for customizing stripe/ring removal methods
2.1 - sort_forward 2.2 - sort_backward 2.3 - separate_frequency_component 2.4 - generate_fitted_image 2.5 - detect_stripe 2.6 - calculate_regularization_coefficient 2.7 - make_2d_butterworth_window 2.8 - make_2d_damping_window 2.9 - apply_wavelet_decomposition 2.10 - apply_wavelet_reconstruction 2.11 - apply_filter_to_wavelet_component 2.12 - interpolate_inside_stripe 2.13 - transform_slice_forward 2.14 - transform_slice_backward
- 3- Customized smoothing filters:
3.1 - apply_gaussian_filter (in the Fourier space) 3.2 - apply_regularization_filter
- 4- Methods for grid scans:
4.1 - detect_sample 4.2 - fix_non_sample_areas 4.3 - locate_slice 4.4 - locate_slice_chunk
Functions:
- algotom.util.utility.apply_1d_regularizer(list_data, sijmat)[source]¶
Supplementary method for the method of “apply_regularization_filter”. To apply a regularizer to an 1D-array.
- algotom.util.utility.apply_filter_to_wavelet_component(data, level=None, order=1, method='gaussian_filter', para=[(1, 11)])[source]¶
Apply a filter to a component of the wavelet decomposition of an image.
- Parameters
data (list or tuple) – The first element is an 2D-array, next elements are tuples of three 2D-arrays. i.e [mat_n, (cH_level_n, cV_level_n, cD_level_n), …, (cH_level_1, cV_level_1, cD_level_1)].
level (int, list of int, or None) – Decomposition level to be applied the filter.
order ({0, 1, 2}) – Specify which component in a tuple, (cH_level_n, cV_level_n, cD_level_n) to be filtered.
method (str) – Name of the filter in the namespace.
para (list or tuple) – Parameters of the filter.
- Returns
list or tuple – The first element is an 2D-array, next elements are tuples of three 2D-arrays. i.e [mat_n, (cH_level_n, cV_level_n, cD_level_n), …, (cH_level_1, cV_level_1, cD_level_1)].
- algotom.util.utility.apply_gaussian_filter(mat, sigmax, sigmay, pad=None, mode=None)[source]¶
Filtering an image in the Fourier domain using a 2D Gaussian window. Smaller is stronger.
- Parameters
mat (array_like) – 2D array.
sigmax (int) – Sigma in the x-direction.
sigmay (int) – Sigma in the y-direction.
pad (int or None) – Padding for the Fourier transform.
mode (str, list of str, or tuple of str) – Padding method. One of options : ‘reflect’, ‘edge’, ‘constant’. Full list is at: https://numpy.org/doc/stable/reference/generated/numpy.pad.html
- Returns
array_like – 2D array. Filtered image.
- algotom.util.utility.apply_method_to_multiple_sinograms(data, method, para, ncore=None)[source]¶
Apply a processing method (in “filtering”, “removal”, and “reconstruction” module) to multiple sinograms or multiple slices in parallel.
- Parameters
data (array_like or hdf object) – 3D array data where sinograms/slices are extracted along axis 1, e.g [:, i, :].
method (str) – Name of a method. e.g. “remove_stripe_based_sorting”.
para (list) – Parameters of the method. e.g. [21, 1]
ncore (int or None) – Number of cores used for computing. Automatically selected if None.
- Returns
array_like – Same axis-definition as the input.
- algotom.util.utility.apply_regularization_filter(mat, alpha, axis=1, ncore=None)[source]¶
Apply a regularization filter using the method in Ref. [1]. Note that it’s computationally costly.
- Parameters
mat (array_like) – 2D array
alpha (float) – Regularization parameter, e.g. 0.001. Smaller is stronger.
axis (int) – Axis along which to apply the filter.
ncore (int or None) – Number of cores used for computing. Automatically selected if None.
- Returns
array_like – 2D array. Smoothed image.
References
- algotom.util.utility.apply_wavelet_decomposition(mat, wavelet_name, level=None)[source]¶
Apply 2D wavelet decomposition.
- Parameters
mat (array_like) – 2D array.
wavelet_name (str) – Name of a wavelet. E.g. “db5”
level (int, optional) – Decomposition level. It is constrained to return an array with a minimum size of larger than 16 pixels.
- Returns
list – The first element is an 2D-array, next elements are tuples of three 2D-arrays. i.e [mat_n, (cH_level_n, cV_level_n, cD_level_n), …, (cH_level_1, cV_level_1, cD_level_1)]
- algotom.util.utility.apply_wavelet_reconstruction(data, wavelet_name, ignore_level=None)[source]¶
Apply 2D wavelet reconstruction.
- Parameters
data (list or tuple) – The first element is an 2D-array, next elements are tuples of three 2D-arrays. i.e [mat_n, (cH_level_n, cV_level_n, cD_level_n), …, (cH_level_1, cV_level_1, cD_level_1)].
wavelet_name (str) – Name of a wavelet. E.g. “db5”
ignore_level (int, optional) – Decomposition level to be ignored for reconstruction.
- Returns
array_like – 2D array. Note that the sizes of the array are always even numbers.
- algotom.util.utility.calculate_regularization_coefficient(width, alpha)[source]¶
Calculate coefficients used for the regularization-based method. Eq. (7) in Ref. [1].
- Parameters
width (int) – Width of a square array.
alpha (float) – Regularization parameter.
- Returns
float – Square array.
References
- algotom.util.utility.check_level(level, n_level)[source]¶
Supplementary method for the method of “apply_filter_to_wavelet_component”. To check if the provided level is in the right format.
- algotom.util.utility.detect_sample(sinogram, sino_type='180')[source]¶
To check if there is a sample in a sinogram using the “double-wedge” property of the Fourier transform of the sinogram (Ref. [1]).
- Parameters
sinogram (array_like) – 2D array. Sinogram image
sino_type ({“180”, “360”}) – Sinogram type : 180-degree or 360-degree.
- Returns
bool – True if there is a sample.
References
- algotom.util.utility.detect_stripe(list_data, snr)[source]¶
Locate stripe positions using Algorithm 4 in Ref. [1]
- Parameters
list_data (array_like) – 1D array. Normalized data.
snr (float) – Ratio (>1.0) used to detect stripe locations. Greater is less sensitive.
- Returns
array_like – 1D binary mask.
References
- algotom.util.utility.fix_non_sample_areas(overlap_metadata)[source]¶
Used to fix overlap values of grid-cells without sample by copying from its neighbours
- Parameters
overlap_metadata (array_like) – A matrix of overlap values of each grid-cell where each element is a list of [overlap, side].
- Returns
metadata (array_like)
- algotom.util.utility.generate_fitted_image(mat, order, axis=0, num_chunk=1)[source]¶
Apply a polynomial fitting along an axis of an image. e.g. axis=0 is to apply the fitting to each column.
- Parameters
mat (array_like) – 2D array.
order (int) – Order of the polynomial used to fit.
axis (int) – Axis along which to apply the filter.
num_chunk (int) – Number of chunks of rows or columns to apply the fitting.
- Returns
mat_fit (array_like)
- algotom.util.utility.interpolate_inside_stripe(mat, list_mask, kind='linear')[source]¶
Interpolate gray-scales inside vertical stripes of an image. Stripe locations given by a binary 1D-mask.
- Parameters
mat (array_like) – 2D array.
list_mask (array_like) – 1D array. Must equal the width of an image.
kind ({‘linear’, ‘cubic’, ‘quintic’}, optional) – The kind of spline interpolation to use. Default is ‘linear’.
- Returns
array_like
- algotom.util.utility.locate_slice(slice_idx, height, overlap_metadata)[source]¶
Locate slice indices in grid-rows given a slice index of the reconstruction data as a whole.
- Parameters
slice_idx (int) – Slice index of full reconstruction data.
height (int) – Height of a projection image of each grid-cell.
overlap_metadata (array_like) – A matrix of overlap values of each grid-row where each element is a list of [overlap, side]. Used to stitch the grid-data along the row-direction.
- Returns
list of int and float – If the slice is not in the overlapping area between two grid-rows, the result is a list of [grid_row_index, slice_index, weight_factor]. If the slice is in the overlapping area between two grid-rows, the result is a list of [[grid_row_index_0, slice_index_0, weight_factor_0], [grid_row_index_1, slice_index_1, weight_factor_1]]
- algotom.util.utility.locate_slice_chunk(slice_start, slice_stop, height, overlap_metadata)[source]¶
Locate slice indices in grid-rows given slice indices of the reconstruction data as a whole.
- Parameters
slice_start (int) – Starting index of full reconstruction data.
slice_stop (int) – Stopping index of full reconstruction data.
height (int) – Height of a projection image of each grid-cell.
overlap_metadata (array_like) – A matrix of overlap values of each grid-row where each element is a list of [overlap, side]. Used to stitch the grid-data along the row-direction.
- Returns
list of list of int and float – List of results for each slice index. If a slice is not in the overlapping area between two grid-rows, the result is a list of [grid_row_index, slice_index, weight_factor]. If a slice is in the overlapping area between two grid-rows, the result is a list of [[grid_row_index_0, slice_index_0, weight_factor_0], [grid_row_index_1, slice_index_1, weight_factor_1]].
- algotom.util.utility.make_2d_butterworth_window(width, height, u, v, n)[source]¶
Create a 2d window from the 1D Butterworth window.
- Parameters
height (int) – Height of the window.
width (int) – Width of the window.
u (int) – Cutoff frequency.
n (int) – Filter order.
v (int) – Number of rows (= 2*v) around the height middle are the 1D Butterworth windows.
- Returns
array_like – 2D array.
- algotom.util.utility.make_2d_damping_window(width, height, size, window_name='gaussian')[source]¶
Make 2D damping window from a list of 1D window for a Fourier-space filter, i.e. a high-pass filter.
- Parameters
height (int) – Height of the window.
width (int) – Width of the window.
size (int) – Sigma of a Gaussian window or cutoff frequency of a Butterworth window.
window_name (str, optional) – Two options: “gaussian” or “butter”.
- Returns
array_like – 2D array of the window.
- algotom.util.utility.make_2d_gaussian_window(height, width, sigmax, sigmay)[source]¶
Create a 2D Gaussian window.
- Parameters
height (int) – Height of the image.
width (int) – Width of the image.
sigmax (int) – Sigma in the x-direction.
sigmay (int) – Sigma in the y-direction.
- Returns
array_like – 2D array.
- algotom.util.utility.make_circle_mask(width, ratio)[source]¶
Create a circle mask.
- Parameters
width (int) – Width of a square array.
ratio (float) – Ratio between the diameter of the mask and the width of the array.
- Returns
array_like – Square array.
- algotom.util.utility.mapping(mat, xmat, ymat, order=1, mode='reflect')[source]¶
Apply a geometric transformation to a 2D array
- Parameters
mat (array_like) – 2D array.
xmat (array_like) – 2D array of the x-coordinates.
ymat (array_like) – 2D array of the y-coordinates.
order (int, optional) – The order of the spline interpolation, default is 1. The order has to be in the range 0-5.
mode ({‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’}, optional) – The mode parameter determines how the input array is extended beyond its boundaries. Default is ‘reflect’.
- Returns
array_like – 2D array.
- algotom.util.utility.polar_from_rectangular(width_pol, height_pol, width_reg, height_reg)[source]¶
Generate polar coordinates from grid coordinates.
- Parameters
width_pol (int) – Width of an image in the polar coordinate system.
height_pol (int) – Height of an image in the polar coordinate system.
width_reg (int) – Width of an image in the Cartesian coordinate system.
height_reg (int) – Height of an image in the Cartesian coordinate system.
- Returns
r_mat (array_like) – 2D array. Broadcast of the r-coordinates.
theta_mat (array_like) – 2D array. Broadcast of the theta-coordinates.
- algotom.util.utility.rectangular_from_polar(width_reg, height_reg, width_pol, height_pol)[source]¶
Generate coordinates of a rectangular grid from polar coordinates.
- Parameters
width_reg (int) – Width of an image in the Cartesian coordinate system.
height_reg (int) – Height of an image in the Cartesian coordinate system.
width_pol (int) – Width of an image in the polar coordinate system.
height_pol (int) – Height of an image in the polar coordinate system.
- Returns
x_mat (array_like) – 2D array. Broadcast of the x-coordinates.
y_mat (array_like) – 2D array. Broadcast of the y-coordinates.
- algotom.util.utility.separate_frequency_component(mat, axis=0, window={'name': 'gaussian', 'sigma': 5})[source]¶
Separate low and high frequency components of an image along an axis. e.g axis=0 is to apply the separation to each column.
- Parameters
mat (array_like) – 2D array.
axis (int) – Axis along which to apply the filter.
window (array_like or dict) – 1D array or a dictionary which given the name of a window in the scipy.signal.window list and its parameters (without window-length).
- Returns
mat_low (array_like) – 2D array. Low-frequency image.
mat_high (array_like) – 2D array. High-frequency image.
- algotom.util.utility.sort_backward(mat, mat_index, axis=0)[source]¶
Sort grayscales of an image using an index array provided. e.g axis=0 is to sort each column.
- Parameters
mat (array_like) – 2D array.
mat_index (array_like) – 2D array. Index array used for sorting.
axis (int) – Axis along which to sort.
- Returns
mat_sort (array_like) – 2D array. Sorted image.
- algotom.util.utility.sort_forward(mat, axis=0)[source]¶
Sort grayscales of an image along an axis. e.g. axis=0 is to sort along each column.
- Parameters
mat (array_like) – 2D array.
axis (int) – Axis along which to sort.
- Returns
mat_sort (array_like) – 2D array. Sorted image.
mat_index (array_like) – 2D array. Index array used for sorting backward.
- algotom.util.utility.transform_1d_window_to_2d(win_1d)[source]¶
Transform a 1d-window to 2d-window. Useful for designing a Fourier filter.
- Parameters
win_1d (array_like) – 1D array.
- Returns
win_2d (array_like) – Square array, a 2D version of the 1d-window.
- algotom.util.utility.transform_slice_backward(mat, coord_mat=None)[source]¶
Transform a reconstructed image in polar coordinates back to rectangular coordinates.
- Parameters
mat (array_like) – Square array. Reconstructed image in polar coordinates.
coord_mat (tuple of array_like, optional) – (Square array of r-coordinates , square array of theta-coordinates) or generated if None.
- Returns
array_like – Transformed image.
- algotom.util.utility.transform_slice_forward(mat, coord_mat=None)[source]¶
Transform a reconstructed image into polar coordinates.
- Parameters
mat (array_like) – Square array. Reconstructed image.
coord_mat (tuple of array_like, optional) – (Square array of x-coordinates , square array of y-coordinates) or generated if None.
- Returns
array_like – Transformed image.