7.2.6. algotom.prep.phase
Module for phase contrast imaging:
Unwrap phase images.
Generate a quality map, weight mask.
Reconstruct surface from gradient images.
- Methods for speckle-based phase-contrast imaging.
Find shifts between two stacks of images.
Find shifts between sample-images.
Align between two stacks of images.
Retrieve phase image.
Generate transmission-signal and dark-signal images.
Functions:
|
Unwrap a phase image using the cosine transform as described in Ref. |
|
Unwrap a phase image using the Fourier transform as described in Ref. |
|
Unwrap a phase image using an iterative FFT-based method as described in Ref. |
|
Generate a quality map using the phase derivative variance (PDV) as described in Ref. |
|
Generate a binary weight-mask based on a provided quality map. |
Reconstruct a surface from the gradients in x and y-direction using the Frankot-Chellappa method (Ref. |
|
Reconstruct a surface from the gradients in x and y-direction using the Simchony-Chellappa-Shao method (Ref. |
|
|
Find shifts between each pair of two image-stacks. |
|
Find shifts between sample-images in a stack against the first sample-image. |
|
Align each pair of two image-stacks using provided reference-sample shifts with an option to correct the shifts between sample-images. |
|
Retrieve the phase image from two stacks of speckle-images and sample-images where the shift of each pixel is determined using a correlation-based technique (Ref. |
|
Get the transmission-signal image and dark-signal image from two stacks of speckle-images and sample-images for correlation-based methods. |
- algotom.prep.phase.get_quality_map(mat, size)[source]
Generate a quality map using the phase derivative variance (PDV) as described in Ref. [1].
- Parameters
mat (array_like) – 2D array.
size (int) – Window size. e.g. size=5.
- Returns
array_like – 2D array.
References
- [1]Dennis Ghiglia and Mark Pritt, “Two-dimensional Phase Unwrapping:
Theory, Algorithms, and Software”, Wiley, New York,1998.
- algotom.prep.phase.get_weight_mask(mat, snr=1.5)[source]
Generate a binary weight-mask based on a provided quality map. Threshold value is calculated based on Algorithm 4 in Ref. [1].
- Parameters
mat (array_like) – 2D array. e.g. a quality map.
snr (float) – Ratio used to calculate the threshold value. Greater is less sensitive.
- Returns
array_like – 2D binary array.
References
- algotom.prep.phase.unwrap_phase_based_cosine_transform(mat, window=None)[source]
Unwrap a phase image using the cosine transform as described in Ref. [1].
- Parameters
mat (array_like) – 2D array. Wrapped phase-image in the range of [-Pi; Pi].
window (array_like) – 2D array. Window is used for the cosine transform. Generated if None.
- Returns
array_like – 2D array. Unwrapped phase-image.
References
- algotom.prep.phase.unwrap_phase_based_fft(mat, win_for=None, win_back=None)[source]
Unwrap a phase image using the Fourier transform as described in Ref. [1].
- Parameters
mat (array_like) – 2D array. Wrapped phase-image in the range of [-Pi; Pi].
win_for (array_like) – 2D array. FFT-window for the forward transform. Generated if None.
win_back (array_like) – 2D array. FFT-window for the backward transform. Making sure there are no zero-values. Generated if None.
- Returns
array_like – 2D array. Unwrapped phase-image.
References
- algotom.prep.phase.unwrap_phase_iterative_fft(mat, iteration=4, win_for=None, win_back=None, weight_map=None)[source]
Unwrap a phase image using an iterative FFT-based method as described in Ref. [1].
- Parameters
mat (array_like) – 2D array. Wrapped phase-image in the range of [-Pi; Pi].
iteration (int) – Number of iteration.
win_for (array_like) – 2D array. FFT-window for the forward transform. Generated if None.
win_back (array_like) – 2D array. FFT-window for the backward transform. Making sure there are no zero-values. Generated if None.
weight_map (array_like) – 2D array. Using a weight map if provided.
- Returns
array_like – 2D array. Unwrapped phase-image.
References
- algotom.prep.phase.reconstruct_surface_from_gradient_FC_method(grad_x, grad_y, correct_negative=True, window=None)[source]
Reconstruct a surface from the gradients in x and y-direction using the Frankot-Chellappa method (Ref. [1]). Note that the DC-component (average value of an image) of the reconstructed image is unidentified because the DC-component of the FFT-window is zero.
- Parameters
grad_x (array_like) – 2D array. Gradient in x-direction.
grad_y (array_like) – 2D array. Gradient in y-direction.
correct_negative (bool, optional) – Correct negative offset if True.
window (list of array_like) – list of three 2D-arrays. Spatial frequencies in x, y, and the window for the Fourier transform. Generated if None.
- Returns
array_like – 2D array. Reconstructed surface.
References
- algotom.prep.phase.reconstruct_surface_from_gradient_SCS_method(grad_x, grad_y, correct_negative=True, window=None, pad=0, pad_mode='linear_ramp')[source]
Reconstruct a surface from the gradients in x and y-direction using the Simchony-Chellappa-Shao method (Ref. [1]). Note that the DC-component (average value of an image) of the reconstructed image is unidentified because the DC-component of the FFT-window is zero.
- Parameters
grad_x (array_like) – 2D array. Gradient in x-direction.
grad_y (array_like) – 2D array. Gradient in y-direction.
correct_negative (bool, optional) – Correct negative offset if True.
window (list of array_like) – List of three 2D-arrays. Spatial frequencies in x, y, and the window for the Fourier transform. Generated if None.
pad (int) – Padding width.
pad_mode (str) – Padding method. Full list can be found at numpy_pad documentation.
- Returns
array_like – 2D array. Reconstructed surface.
References
- algotom.prep.phase.find_shift_between_image_stacks(ref_stack, sam_stack, win_size, margin, list_ij, global_value='mixed', gpu=False, block=32, sub_pixel=True, method='diff', size=3, ncore=None, norm=False)[source]
Find shifts between each pair of two image-stacks. Can be used to align reference-images and sample-images in speckle-based imaging technique. The method finds the shift between two images by finding local shifts between small areas of the images given by a list of points.
- Parameters
ref_stack (array_like) – 3D array. Reference images.
sam_stack (array_like) – 3D array. Sample images.
win_size (int) – To define the size of the area around a selected pixel of the sample image.
margin (int) – To define the size of the area of the reference image for searching, i.e. size = 2 * margin + win_size.
list_ij (list of lists of int) – List of indices of points used for local search. Accept the value of [i_index, j_index] for a single point or [[i_index0, i_index1,…], [j_index0, j_index1,…]] for multiple points.
global_value ({“median”, “mean”, “mixed”}) – Method for calculating the global value from local values.
gpu (bool, optional) – Use GPU for computing if True.
block (int) – Size of a GPU block. E.g. 16, 32, 64, …
sub_pixel (bool, optional) – Enable sub-pixel location.
method ({“diff”, “poly_fit”}) – Method for finding 1d sub-pixel position. Two options: a differential method or a polynomial method.
size (int) – Window size around the integer location of the maximum value used for sub-pixel searching.
ncore (int or None) – Number of cpu-cores used for computing. Automatically selected if None.
norm (bool, optional) – Normalize the input images if True.
- Returns
array_like – List of [[x_shift0, y_shift0], [x_shift1, y_shift1],…]. The shift of each image in the second stacks against each image in the first stack.
- algotom.prep.phase.find_shift_between_sample_images(ref_stack, sam_stack, sr_shifts, win_size, margin, list_ij, global_value='median', gpu=False, block=32, sub_pixel=True, method='diff', size=3, ncore=None, norm=False)[source]
Find shifts between sample-images in a stack against the first sample-image. It is used to align sample-images of the same rotation-angle from multiple tomographic datasets. Reference-images are used for normalization before finding the shifts.
- Parameters
ref_stack (array_like) – 3D array. Reference images.
sam_stack (array_like) – 3D array. Sample images.
sr_shifts (array_like) – List of shifts between each pair of reference-images and sample-images.
win_size (int) – To define the size of the area around a selected pixel of the sample image.
margin (int) – To define the size of the area of the reference image for searching, i.e. size = 2 * margin + win_size.
list_ij (list of lists of int) – List of indices of points used for local search. Accept the value of [i_index, j_index] for a single point or [[i_index0, i_index1,…], [j_index0, j_index1,…]] for multiple points.
global_value ({“median”, “mean”, “mixed”}) – Method for calculating the global value from local values.
gpu (bool, optional) – Use GPU for computing if True.
block (int) – Size of a GPU block. E.g. 16, 32, 64, …
sub_pixel (bool, optional) – Enable sub-pixel location.
method ({“diff”, “poly_fit”}) – Method for finding 1d sub-pixel position. Two options: a differential method or a polynomial method.
size (int) – Window size around the integer location of the maximum value used for sub-pixel searching.
ncore (int or None) – Number of cpu-cores used for computing. Automatically selected if None.
norm (bool, optional) – Normalize the input images if True.
- Returns
array_like – List of [[0.0, 0.0], [x_shift1, y_shift1],…]. For convenient usage, the shift of the first image in the stack with itself, [0.0, 0.0], is added to the result.
- algotom.prep.phase.align_image_stacks(ref_stack, sam_stack, sr_shifts, sam_shifts=None, mode='reflect')[source]
Align each pair of two image-stacks using provided reference-sample shifts with an option to correct the shifts between sample-images.
- Parameters
ref_stack (array_like) – 3D array. Reference images.
sam_stack (array_like) – 3D array. Sample images.
sr_shifts (array_like) – List of shifts between each pair of reference-images and sample-images. Each value is the shift of the second image against the first image.
sam_shifts (array_like, optional) – List of shifts between each sample-image and the first sample-image.
mode ({‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’}, optional) – Method to fill up empty areas caused by shifting the images.
- Returns
ref_stack (array_like) – 3D array. Aligned reference-images.
sam_stack (array_like) – 3D array. Aligned sample-images.
- algotom.prep.phase.get_transmission_dark_field_signal(ref_stack, sam_stack, x_shifts, y_shifts, win_size, margin=None, ncore=None)[source]
Get the transmission-signal image and dark-signal image from two stacks of speckle-images and sample-images for correlation-based methods.
- Parameters
ref_stack (array_like) – 3D array. Reference images (speckle images).
sam_stack (array_like) – 3D array. Sample images.
x_shifts (array_like) – x-shift image.
y_shifts (array_like) – y-shift image.
win_size (int) – Window size used for calculating signals.
margin (int or None) – Margin value used for calculating signals.
ncore (int or None) – Number of cpu-cores used for computing. Automatically selected if None.
- Returns
trans (array_like) – Transmission-signal image
dark (array_like) – Dark-signal image
- algotom.prep.phase.retrieve_phase_based_speckle_tracking(ref_stack, sam_stack, find_shift='correl', filter_name='hamming', dark_signal=False, dim=1, win_size=7, margin=10, method='diff', size=3, gpu=False, block=(16, 16), ncore=None, norm=True, norm_global=False, chunk_size=100, surf_method='SCS', correct_negative=True, window=None, pad=100, pad_mode='linear_ramp', return_shift=False)[source]
Retrieve the phase image from two stacks of speckle-images and sample-images where the shift of each pixel is determined using a correlation-based technique (Ref. [1-2]) or a cost-function-based method (Ref. [3]). Results can be an image, a list of 3 images, or a list of 5 images.
- Parameters
ref_stack (array_like) – 3D array. Reference images (speckle images).
sam_stack (array_like) – 3D array. Sample images.
find_shift ({“correl”, “umpa”}) – To select the back-end method for finding shifts. Using a correlation-based method (Ref. [1-2]) or a cost-based method (Ref. [3]).
filter_name ({None, “hann”, “bartlett”, “blackman”, “hamming”, “nuttall”, “parzen”, “triang”}) – To select a smoothing filter.
dark_signal (bool) – Return both dark-signal image and transmission-signal image if True
dim ({1, 2}) – To find the shifts (in x and y) separately (1D) or together (2D).
win_size (int) – Size of local areas in the sample image for finding shifts.
margin (int) – To define the searching range of the sample images in finding the shifts compared to the reference images.
method ({“diff”, “poly_fit”}) – Method for finding sub-pixel shift. Two options: a differential method (Ref. [4]) or a polynomial method (Ref. [5]). The “poly_fit” option is not available if using GPU.
size (int) – Window size around the integer location of the maximum value used for sub-pixel location. Adjustable if using the polynomial method.
gpu ({False, True, “hybrid”}) – Use GPU for computing if True or in “hybrid” mode.
block (tuple of two integer-values, optional) – Size of a GPU block. E.g. (8, 8), (16, 16), (32, 32), …
ncore (int or None) – Number of cpu-cores used for computing. Automatically selected if None.
norm (bool, optional) – Normalizing the inputs if True.
norm_global (bool, optional) – Normalize by using the full size of the inputs if True.
chunk_size (int or None) – Size of each chunk extracted along the height of the image.
surf_method ({“SCS”, “FC”}) – Select method for surface reconstruction: “SCS” (Ref. [6]) or “FC” (Ref. [7])
correct_negative (bool, optional) – Correct negative offset if True.
window (list of array_like) – List of three 2D-arrays. Spatial frequencies in x, y, and the window in the Fourier space for the surface reconstruction method. Generated if None.
pad (int) – Padding-width used for the “SCS” method.
pad_mode (str) – Padding-method used for the “SCS” method. Full list can be found at numpy_pad documentation.
return_shift (bool, optional) – Return a list of 3 arrays: x-shifts, y-shifts, and phase image if True. The shifts can be used to determine transmission-signal and dark-signal image.
- Returns
phase (array_like) – Phase image. If dark_signal is False and return_shifts is False.
phase, trans, dark (list of array_like) – Phase image, transmission image, and dark-signal image. If dark_signal is True and return_shifts is False.
x_shifts, y_shifts, phase (list of array_like) – x-shift image and y-shift image. If dark_signal is False and return_shifts is True.
x_shifts, y_shifts, phase, trans, dark (list of array_like) – x-shift image, y-shift image, phase image, transmission image, and dark-signal image. If dark_signal is True and return_shifts is True.
References
[1] : https://doi.org/10.1038/srep08762
[2] : https://doi.org/10.1103/PhysRevApplied.5.044014
[3] : https://doi.org/10.1103/PhysRevLett.118.203903
[4] : https://doi.org/10.48550/arXiv.0712.4289
[5] : https://doi.org/10.1088/0957-0233/17/6/045