7.2.6. algotom.prep.phase
Module for phase contrast imaging:
Unwrap phase images.
Generate a quality map, weight mask.
 Methods for specklebased phasecontrast imaging.
Find shifts between two stacks of images.
Find shifts between sampleimages.
Align between two stacks of images.
Retrieve phase image.
Generate transmissionsignal and darksignal 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 FFTbased method as described in Ref. 

Generate a quality map using the phase derivative variance (PDV) as described in Ref. 

Generate a binary weightmask based on a provided quality map. 
Reconstruct a surface from the gradients in x and ydirection using the FrankotChellappa method (Ref. 

Reconstruct a surface from the gradients in x and ydirection using the SimchonyChellappaShao method (Ref. 


Find shifts between each pair of two imagestacks. 

Find shifts between sampleimages in a stack against the first sampleimage. 

Align each pair of two imagestacks using provided referencesample shifts with an option to correct the shifts between sampleimages. 

Retrieve the phase image from two stacks of speckleimages and sampleimages where the shift of each pixel is determined using a correlationbased technique (Ref. 

Get the transmissionsignal image and darksignal image from two stacks of speckleimages and sampleimages for correlationbased 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, “Twodimensional Phase Unwrapping:
Theory, Algorithms, and Software”, Wiley, New York,1998.
 algotom.prep.phase.get_weight_mask(mat, snr=1.5)[source]
Generate a binary weightmask 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 phaseimage 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 phaseimage.
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 phaseimage in the range of [Pi; Pi].
win_for (array_like) – 2D array. FFTwindow for the forward transform. Generated if None.
win_back (array_like) – 2D array. FFTwindow for the backward transform. Making sure there are no zerovalues. Generated if None.
 Returns
array_like – 2D array. Unwrapped phaseimage.
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 FFTbased method as described in Ref. [1].
 Parameters
mat (array_like) – 2D array. Wrapped phaseimage in the range of [Pi; Pi].
iteration (int) – Number of iteration.
win_for (array_like) – 2D array. FFTwindow for the forward transform. Generated if None.
win_back (array_like) – 2D array. FFTwindow for the backward transform. Making sure there are no zerovalues. Generated if None.
weight_map (array_like) – 2D array. Using a weight map if provided.
 Returns
array_like – 2D array. Unwrapped phaseimage.
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 ydirection using the FrankotChellappa method (Ref. [1]). Note that the DCcomponent (average value of an image) of the reconstructed image is unidentified because the DCcomponent of the FFTwindow is zero.
 Parameters
grad_x (array_like) – 2D array. Gradient in xdirection.
grad_y (array_like) – 2D array. Gradient in ydirection.
correct_negative (bool, optional) – Correct negative offset if True.
window (list of array_like) – list of three 2Darrays. 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 ydirection using the SimchonyChellappaShao method (Ref. [1]). Note that the DCcomponent (average value of an image) of the reconstructed image is unidentified because the DCcomponent of the FFTwindow is zero.
 Parameters
grad_x (array_like) – 2D array. Gradient in xdirection.
grad_y (array_like) – 2D array. Gradient in ydirection.
correct_negative (bool, optional) – Correct negative offset if True.
window (list of array_like) – List of three 2Darrays. 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 imagestacks. Can be used to align referenceimages and sampleimages in specklebased 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 subpixel location.
method ({“diff”, “poly_fit”}) – Method for finding 1d subpixel position. Two options: a differential method or a polynomial method.
size (int) – Window size around the integer location of the maximum value used for subpixel searching.
ncore (int or None) – Number of cpucores 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 sampleimages in a stack against the first sampleimage. It is used to align sampleimages of the same rotationangle from multiple tomographic datasets. Referenceimages 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 referenceimages and sampleimages.
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 subpixel location.
method ({“diff”, “poly_fit”}) – Method for finding 1d subpixel position. Two options: a differential method or a polynomial method.
size (int) – Window size around the integer location of the maximum value used for subpixel searching.
ncore (int or None) – Number of cpucores 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 imagestacks using provided referencesample shifts with an option to correct the shifts between sampleimages.
 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 referenceimages and sampleimages. Each value is the shift of the second image against the first image.
sam_shifts (array_like, optional) – List of shifts between each sampleimage and the first sampleimage.
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 referenceimages.
sam_stack (array_like) – 3D array. Aligned sampleimages.
 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 transmissionsignal image and darksignal image from two stacks of speckleimages and sampleimages for correlationbased methods.
 Parameters
ref_stack (array_like) – 3D array. Reference images (speckle images).
sam_stack (array_like) – 3D array. Sample images.
x_shifts (array_like) – xshift image.
y_shifts (array_like) – yshift 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 cpucores used for computing. Automatically selected if None.
 Returns
trans (array_like) – Transmissionsignal image
dark (array_like) – Darksignal 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=None, 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 speckleimages and sampleimages where the shift of each pixel is determined using a correlationbased technique (Ref. [12]) or a costfunctionbased 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 backend method for finding shifts. Using a correlationbased method (Ref. [12]) or a costbased method (Ref. [3]).
filter_name ({None, “hann”, “bartlett”, “blackman”, “hamming”, “nuttall”, “parzen”, “triang”}) – To select a smoothing filter.
dark_signal (bool) – Return both darksignal image and transmissionsignal 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 subpixel 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 subpixel 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 integervalues, optional) – Size of a GPU block. E.g. (8, 8), (16, 16), (32, 32), …
ncore (int or None) – Number of cpucores 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 2Darrays. Spatial frequencies in x, y, and the window in the Fourier space for the surface reconstruction method. Generated if None.
pad (int) – Paddingwidth used for the “SCS” method.
pad_mode (str) – Paddingmethod used for the “SCS” method. Full list can be found at numpy_pad documentation.
return_shift (bool, optional) – Return a list of 3 arrays: xshifts, yshifts, and phase image if True. The shifts can be used to determine transmissionsignal and darksignal 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 darksignal image. If dark_signal is True and return_shifts is False.
x_shifts, y_shifts, phase (list of array_like) – xshift image and yshift image. If dark_signal is False and return_shifts is True.
x_shifts, y_shifts, phase, trans, dark (list of array_like) – xshift image, yshift image, phase image, transmission image, and darksignal 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/09570233/17/6/045