7.5.4. algotom.util.correlation
Module of correlation-based methods for finding shifts between images or stacks of images. The methods are designed to be flexible to:
Run on multicore CPU or GPU.
Use small/large RAM or small/large GPU memory.
Work with small/large size of data.
Find shifts locally or globally.
Functions:
|
Normalize an image. |
|
Generate the correlation map (Pearson coefficients) between two images by shifting the second image over the reference image. |
|
Locate the position of the maximum value of a 2d-array with sub-pixel accuracy. |
|
Find the relative translations of the second image against the first image using the correlation map generated by sliding the 2nd image over the 1st one. |
|
To find local shifts (in x and y direction) between two images by selecting a small area/volume of the second image and sliding over a slightly larger area/volume of the reference image. |
|
Find global shift between two images based on finding local shifts. |
|
To find local shifts (in x and y direction) of each pixel between two 3d-images by selecting a small volume of the second image and sliding over a slightly larger volume of the reference image. |
- algotom.util.correlation.normalize_image(mat)[source]
Normalize an image.
- Parameters
mat (array_like) – 2D or 3D array.
- Returns
array_like – 2D or 3D array. Normalized image.
- algotom.util.correlation.generate_correlation_map(ref_mat, mat, gpu=False, block=(16, 16))[source]
Generate the correlation map (Pearson coefficients) between two images by shifting the second image over the reference image.
- Parameters
ref_mat (array_like) – 2D or 3D array. The reference image (e.g. with height0 x width0).
mat (array_like) – 2D or 3D array. The second image (e.g. with height1 x width1). If 3D, the size of the first dimension (i.e. depth) must be the same as the reference image.
gpu (bool, optional) – Use GPU for computing if True.
block (tuple of two integer-values, optional) – Size of a GPU block. E.g. (4,4), (8, 8), …
- Returns
array_like – 2D array with the size of (height0-height1+1) x (width0-width1+1).
- algotom.util.correlation.locate_peak(mat, sub_pixel=True, method='diff', dim=2, size=3, max_peak=True)[source]
Locate the position of the maximum value of a 2d-array with sub-pixel accuracy.
- Parameters
mat (array_like) – 2D array.
sub_pixel (bool, optional) – Enable sub-pixel location.
method ({“diff”, “poly_fit”}) – Method for finding sub-pixel shift. Two options: a differential method (Ref. [1]) or a polynomial method (Ref. [2]).
dim ({1, 2}) – Searching dimension for sub-pixel location.
size (int) – Window size around the integer location of the maximum value used for sub-pixel searching.
max_peak (bool, optional) – Used to locate the minimum value if False.
- Returns
list of two floats – Sub-pixel position (x, y), i.e. (column, row), of the maximum value.
References
- algotom.util.correlation.find_shift_based_correlation_map(ref_mat, mat, margin=10, axis=None, sub_pixel=True, method='diff', dim=2, size=3, gpu=False, block=(16, 16))[source]
Find the relative translations of the second image against the first image using the correlation map generated by sliding the 2nd image over the 1st one. If the inputs are 3d-arrays, the size of the first axis must be the same.
- Parameters
ref_mat (array_like) – 2D or 3D array. Reference image.
mat (array_like) – 2D or 3D array. The second image. If 3D, the size of the first dimension (i.e. depth) must be the same as the reference image.
margin (int, optional) – If the second image and the first image are the same size, the second image will be cropped with the margin amount from the edges before sliding. Basically, this value defines the sliding range.
axis ({0, 1, None}) – To select the axis for sliding. If the inputs are 3d-arrays, 0 and 1 corresponding to axis-1 and axis-2 of a 3d-array.
sub_pixel (bool, optional) – Enable sub-pixel location.
method ({“diff”, “poly_fit”}) – Method for finding sub-pixel shift. Two options: a differential method (Ref. [1]) or a polynomial method (Ref. [2]).
dim ({1, 2}) – Searching dimension for sub-pixel location.
size (int) – Window size around the integer location of the maximum value used for sub-pixel searching.
gpu (bool, optional) – Use GPU for computing if True.
block (tuple of two integer-values, optional) – Size of a GPU block. E.g. (4,4), (8, 8), …
- Returns
list of 2 floats – The shifts in x and y-direction of the second image referred to the middle of the reference image.
References
- algotom.util.correlation.find_local_shifts(ref_mat, mat, 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)[source]
To find local shifts (in x and y direction) between two images by selecting a small area/volume of the second image and sliding over a slightly larger area/volume of the reference image.
- Parameters
ref_mat (array_like) – 2D/3D array, can be a numpy array or hdf object. Reference image.
mat (array_like) – 2D/3D array, can be a numpy array or hdf object. The second image, must be the same size as the reference image.
dim ({1, 2}) – To find the shifts (in x and y) separately or together.
win_size (int) – Size of local areas in the second image.
margin (int) – To define the sliding range of the second image.
method ({“diff”, “poly_fit”}) – Method for finding sub-pixel shift. Two options: a differential method (Ref. [1]) or a polynomial method (Ref. [2]). 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.
- Returns
list of two 2d-arrays – x-shift array and y-shift array. Zeros at the outer area of the size of (margin + win_size // 2).
References
- algotom.util.correlation.find_global_shift_based_local_shifts(ref_mat, mat, win_size, margin, list_ij=None, num_point=None, global_value='mixed', gpu=False, block=32, sub_pixel=True, method='diff', size=3, ncore=None, norm=False, return_list=False)[source]
Find global shift between two images based on finding local shifts.
- Parameters
ref_mat (array_like) – 2D array. Reference image.
mat (array_like) – 2D array. The 2nd image. Must be the same size as the reference image.
win_size (int) – To define the size of the area around the selected pixel of the 2nd image. E.g. 41, 61, ..
margin (int) – To define the searching range (in pixel) for finding shift. E.g. 20, 30,…
list_ij (list of lists of int or None) – 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. Automatically generated if None.
num_point (int or None) – Number of points used for local search if list_ij is None.
global_value ({“median”, “mean”, “mixed”}) – Method for calculating the global value from local values.
gpu (bool, optional) – Use GPU for computing if True. If win_size and image size is large (e.g. > 201 x 2k x 2k), using CPU may be better.
block (int, optional) – Size of a GPU block if using GPU. E.g. 16, 32, 64, …
sub_pixel (bool, optional) – Enable sub-pixel location.
method ({“diff”, “poly_fit”}) – Method for finding sub-pixel shift. Two options: a differential method (Ref. [1]) or a polynomial method (Ref. [2]). The “poly_fit” option is not available if using GPU.
size (int, optional) – 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.
return_list (bool) – Return all local values if True.
- Returns
float or list of float – Shift in x-direction. Return a list of float if return_list is True.
float or list of float – Shift in y-direction. Return a list of float if return_list is True.
References
- algotom.util.correlation.find_local_shifts_umpa(ref_mat, mat, win_size=7, margin=10, method='diff', size=3, gpu=True, block=(16, 16), ncore=None, chunk_size=100, filter_name='hamming', dark_signal=False)[source]
To find local shifts (in x and y direction) of each pixel between two 3d-images by selecting a small volume of the second image and sliding over a slightly larger volume of the reference image. The cost function uses the formula in Ref. [1], known as UMPA.
- Parameters
ref_mat (array_like) – 3D array, can be a numpy array or hdf object. Reference image.
mat (array_like) – 3D array, can be a numpy array or hdf object. The second image, must be the same size as the reference image.
win_size (int) – Size of local areas in the second image.
margin (int) – To define the sliding range of the second image.
method ({“diff”, “poly_fit”}) – Method for finding sub-pixel shift. Two options: a differential method (Ref. [2]) or a polynomial method (Ref. [3]). 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 (bool) – Use GPU for computing if True.
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.
chunk_size (int or None) – Size of each chunk extracted along the height of the image. Use to avoid the out of memory problem.
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
- Returns
list of two 2d-arrays or four 2d-arrays – x-shift image and y-shift image. Zeros at the outer area of the size of (margin + win_size // 2). And/or dark-signal image and transmission-signal image If the ‘dark_signal’ option is True.
References
[1] : https://doi.org/10.1103/PhysRevLett.118.203903