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_phase_based_cosine_transform(mat[, ...])

Unwrap a phase image using the cosine transform as described in Ref.

unwrap_phase_based_fft(mat[, win_for, win_back])

Unwrap a phase image using the Fourier transform as described in Ref.

unwrap_phase_iterative_fft(mat[, iteration, ...])

Unwrap a phase image using an iterative FFT-based method as described in Ref.

get_quality_map(mat, size)

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

get_weight_mask(mat[, snr])

Generate a binary weight-mask based on a provided quality map.

reconstruct_surface_from_gradient_FC_method(...)

Reconstruct a surface from the gradients in x and y-direction using the Frankot-Chellappa method (Ref.

reconstruct_surface_from_gradient_SCS_method(...)

Reconstruct a surface from the gradients in x and y-direction using the Simchony-Chellappa-Shao method (Ref.

find_shift_between_image_stacks(ref_stack, ...)

Find shifts between each pair of two image-stacks.

find_shift_between_sample_images(ref_stack, ...)

Find shifts between sample-images in a stack against the first sample-image.

align_image_stacks(ref_stack, sam_stack, ...)

Align each pair of two image-stacks using provided reference-sample shifts with an option to correct the shifts between sample-images.

retrieve_phase_based_speckle_tracking(...[, ...])

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_transmission_dark_field_signal(...[, ...])

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

[1] : https://doi.org/10.1364/OE.26.028396

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

[1] : https://doi.org/10.1364/JOSAA.11.000107

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

[1] : https://doi.org/10.1109/36.297989

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

[1] : https://doi.org/10.1364/AO.56.007079

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

[1] : https://doi.org/10.1109/34.3909

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

[1] : https://doi.org/10.1109/34.55103

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

[6] : https://doi.org/10.1109/34.55103

[7] : https://doi.org/10.1109/34.3909