spexwavepy package

imstackfun module

class spexwavepy.imstackfun.Imagestack(fileFolder, ROI)[source]

Bases: object

A class to represent one image stack.

Parameters:

  • fpath (str) – File folder path.

  • roi (4-element tuple, (int, int, int, int)) – Region of interest.

  • fstep (int) – Step for file reading. (default 1)

  • fnum (int) – Total file number, if <=0, consider all the files in the folder.

  • fstart (int) – Starting file number for dataset loading. (defaul 0)

  • verbose (bool) – Print out information or not. (default True)

  • rawdata (numpy.ndarray) – 3D image stack data. Read-only.

  • data (numpy.ndarray) – 3D image stack data. Data used for future processing. Initially, it copied the raw image stack.

  • normalize (bool) – Do the normalization or not. (default False)

  • flip (string) – To flip the images in the stack or not. ‘x’ is to flip horizontally, ‘y’ is to flip vertically. It is necessary when the test optic is a mirror and a reference beam exists. (default None)

property flip
flipstack()[source]

Flip the images in the stack.

property fnum
property fstart
property fstep
getpixsize(subROI, dim, step, verbose=True, display=True)[source]

To obtain the pixel size from a 1D scan.

Parameters:

  • subROI ([int, int, int, int]) – ROI of the subregion used for template matching. It relates to the cropped image. In other words, the image stack has been cropped using ROI, the subROI is the coordinates of the cropped image from the crooped image stack.

  • dim (str) – ‘x’|’y’|’both’. The data scanned direction.

  • step (float) – The data scanned step size. Unit \(\mu m\).

  • verbose (bool) – To show the information or not. (default True)

  • display (bool) – To display the fitting result or not. (default True)

Returns:

pixsize – The pixel size of the detector. Unit is \(\mu m\).

Return type:

float

norm()[source]

Normalize the raw images.

property normalize
read_data()[source]

Read the raw image data. At the moment, only .png and .tiff files are considered.

rot90deg()[source]

Rotate the raw images in the stack 90 degrees. It is very useful when dealing the x scan data. It rotates counterclockwise.

rotate(angle)[source]

Rotate the raw images in the stack according to the angle. It rotate counterclockwise.

Parameters:

angle (float) – Rotation angle, in [deg].

smooth(meth='Gaussian', pixel=0, verbose=False)[source]

Smoothing the raw images in the image stack.

Parameters:

  • meth (string) – ‘Gaussian|Box’, method used for smoothing. (default ‘Gaussian’) ‘Gaussian’ is for Gaussian smoothing; ‘Box’ is for smoothing using a n*n square.

  • pixel (int) – If meth is ‘Gaussian’, it is the sigma; if meth is ‘Box’, it is the width and height of the square used for smoothing. (default 0)

  • verbose (bool) – To show the information or not. (default False)

smooth_multi(meth='Gaussian', pixel=0, cpu_no=1, verbose=False)[source]

The multiprocessing version of smooth() function.

Parameters:

  • meth (string) – ‘Gaussian|Box’, method used for smoothing. (default ‘Gaussian’) ‘Gaussian’ is for Gaussian smoothing; ‘Box’ is for smoothing using a n*n square.

  • pixel (int) – If meth is ‘Gaussian’, it is the sigma; if meth is ‘Box’, it is the width and height of the square used for smoothing. (default 0)

  • cpu_no (int) – CPU number to be used.

  • verbose (bool) – To show the information or not. (default False)

property verbose

corefun module

spexwavepy.corefun.Hartmann_mesh_show(imag, cen_xmesh, cen_ymesh, size, cmap='jet', lw=2, ec='red')[source]

Show defined mesh grid for Hartmann-like data processing scheme.

Note

Add plt.show() to you code where it is appropriate to enable this function to show the results.

Parameters:

  • imag (2d numpy array) – The input image. The mesh grid will shown on it.

  • cen_xmsh (2D numpy array) – Mesh grid of the x coordinate of the box centre.

  • cen_ymsh (2D numpy array) – Mesh grid of the x coordinate of the box centre.

  • size (int, or [int, int]) – It defines the size of the box used for Hartmann-like tracking mode. If it is a single integer, it will be expanded automatically to (int, int). size[0] is the half width of the chosen box, size[1] is the half height of the chosen box.

  • cmap (string, optional.) – Color map. Default is ‘jet’.

  • lw (int, optional) – Line width of the box, default 2.

  • ec (string, optional) – Edge color of the box, default ‘red’.

spexwavepy.corefun.Imagematch(im1, im2, meth='cv2.TM_CCOEFF_NORMED', subpixelmeth='default', res=True)[source]

Find the shifts between two images (im1 and im2) with subpixel accuracy.

Parameters:

  • im1 (numpy.ndarray) – Reference image.

  • im2 (numpy.ndarray) – Image to be tracked. It must be smaller than im1.

  • meth (str) – Method for cv2.matchTemplate (default ‘cv2.TM_CCOEFF_NORMED’). Other methods need to be implemented.

  • subpixelmeth (str) – The algorithm used with subpixel accuracy (default ‘default’). When it is None, no subpixel method used. Now only ‘default’|’gausspeak’|’parapeak’ is available.

  • res (bool) – Whether or not return the coefficient matrix (default True).

Returns:

delayX, delayY, res_mat – Shifts in two dimensions, matching coefficient matrix if res is True.

Return type:

numpy.array

spexwavepy.corefun.NormImage(image_raw)[source]

Image Normalization. This function is used to mitigate the low frequent structures appeared in the raw images.

Parameters:

image_raw (numpy.ndarray) – The input image data

Returns:

The normalized image

Return type:

numpy.ndarray

spexwavepy.corefun.crop_one(data, ROI, ShowImage=False)[source]

Crop the input image according to the ROI.

Parameters:

  • data (numpy.ndarray) – The input image data

  • ROI ([int, int, int, int]) – ROI is [y_begin, y_end, x_begin, x_end]

  • ShowImage (bool, optional) – To show image or not, default is False

Returns:

The cropped image data

Return type:

numpy.ndarray

spexwavepy.corefun.read_one(filename, ShowImage=False)[source]

Read one image At the moment, only .png and .tiff files are considered.

Parameters:

  • filename (str) – File name

  • ShowImage (bool, optional) – To show image or not, default is False

Returns:

One image data

Return type:

numpy.ndarray

spexwavepy.corefun.subpix_default(res, meth='cv2.TM_CCOEFF_NORMED')[source]

The default subpix registration method.

This subpixel registrition method can be found from [FLCT] and [QiaoWavelet].

[FLCT]

Fisher, G. H., & Welsch, B.T. “FLCT: a fast, efficient method for performing local correlation tracking.” Subsurface and Atmospheric Influences on Solar Activity. Vol. 383. 2008.

[QiaoWavelet]

Qiao, Zhi, et al. “Wavelet-transform-based speckle vector tracking method for X-ray phase imaging.” Optics Express 28.22 (2020): 33053-33067.

Parameters:

  • res (numpy.ndarray) – The cross correlation results, 2D array

  • meth (str) – Method for cv2.matchTemplate (default ‘cv2.TM_CCOEFF_NORMED’). Do not modify it, other methods haven’t been implemented.

Returns:

Deltax, Deltay – 1D array of subpixel registration results.

Return type:

numpy.array

spexwavepy.corefun.subpix_gausspeak(res, meth='cv2.TM_CCOEFF_NORMED')[source]

Gaussian peak fitting for subpixel registration.

Parameters:

  • res (numpy.ndarray) – The cross correlation results, 2D array

  • meth (str) – Method for cv2.matchTemplate (default is ‘cv2.TM_CCOEFF_NORMED’). Do not modify it, other methods haven’t been implemented.

Returns:

Deltax, Deltay – 1D array of subpixel registration results.

Return type:

numpy.array

spexwavepy.corefun.subpix_parapeak(res, meth='cv2.TM_CCOEFF_NORMED')[source]

Parabola peak fitting for subpixel registration.

Parameters:

  • res (numpy.ndarray) – The cross correlation results, 2D array

  • meth (str) – Method for cv2.matchTemplate (default is ‘cv2.TM_CCOEFF_NORMED’). Do not modify it, other methods haven’t been implemented.

Returns:

Deltax, Deltay – 1D array of subpixel registration results.

Return type:

numpy.array

trackfun module

class spexwavepy.trackfun.Tracking(imstack1, imstack2=None, imstack3=None, imstack4=None)[source]

Bases: object

A container for different speckle tracking algorithms.

Parameters:

  • imstack1 (Imagestack class) – The first image stack. For XSS technique, it is scanned in x | y direction.

  • imstack2 (Imagestack class) – The second image stack. For XSS technique, it is scanned in x | y direction. Not always necessary. (default None)

  • imstack3 (Imagestack class) – The third image stack. For XSS technique, it is scanned in y direction. /Not always necessary. (default None)

  • imstack4 (Imagestack class) – The fourth image stack. For XSS technique, it is scanned in y direction. Not always necessary. (default None)

  • dimension (str) – ‘1D’ or ‘2D’. To do 1D or 2D data processing. (default ‘2D’)

  • scandim (str) – ‘x’|’y’|’xy’|’random’. Scan direction for the image stack. (default ‘x’)

  • mempos (str) – ‘downstream’ or ‘upstream’. Use this to define the position of the diffusor in respect to the focus of the optics. ‘downstream’ means the diffuser is placed downstream of the focus. See User guide: Local curvature reconstruction for more details of it. (default ‘downstream’)

  • scanstep (float) – scan step size, unit in \(\mu m\). (default None)

  • pixsize (float) – detector pixel size, unit in \(\mu m\). (default None)

  • dist (float) – distance from diffuser to detector plane, if it’s the downstream mode, mempos is ‘downstream’ (default), unit in mm. If the diffuser is placed in the upstream, mempos is ‘upstream’, usually it is set to be the distance between the centre of the optic to the detector. (default None)

  • subpixelmeth (str) – ‘default’, ‘gausspeak’ or ‘parapeak’. (default ‘default’). Method used for subpixel registration.

  • delayX (numpy.ndarray) – The tracked 1D/2D shifts in X direction.

  • delayY (numpy.ndarray) – The tracked 1D/2D shifts in Y direction.

  • resX (numpy.ndarray) – The tracking 1D/2D coeffcient in X direction.

  • resY (numpy.ndarray) – The tracking 1D/2D coeffcient in Y direction.

  • sloX (numpy.ndarray) – The reconstructed slope error in X direction.

  • sloY (numpy.ndarray) – The reconstructed slope error in Y direction.

  • curvX (numpy.ndarray) – The reconstructed local curvature in X direction.

  • curvY (numpy.ndarray) – The reconstructed local curvature in Y direction.

Hartmann_XST(cen_xmesh, cen_ymesh, pad, size, normalize=False, display=False, verbose=True)[source]

Hartmann-like data processing procedure. Two image stacks are needed. The fisrt image stack consists one sample image. The second image stack consists another reference image.

Note

For simplicity, unlike other mode of data processing, we only provide Tracking.delayX and Tracking.delayY for this method. Recovering the appropriate physical quantities from the speckle shifts is left to the discretion of the users.

Parameters:

  • cen_xmsh (numpy.ndarray) – Mesh grid of the x coordinate of the box centre. A 2D array.

  • cen_ymsh (numpy.ndarray) – Mesh grid of the y coordinate of the box centre. A 2D array.

  • pad (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking. If it is a single integer, it will be expanded automatically to (int, int).

  • size (int, or [int, int]) – It defines the size of the box used for Hartmann-like tracking mode. If it is a single integer, it will be expanded automatically to (int, int). size[0] is the half width of the chosen box, size[1] is the half height of the chosen box.

  • normalize (bool) – To normalize the stitched image or not. (default False)

  • display (bool) – To display or not. (default False)

  • verbose (bool) – To show the information or not. (default True)

XSS_self(edge_x, edge_y, edge_z, nstep, hw_xy=None, pad_xy=None, normalize=False, display=False, verbose=True)[source]

Speckle tracking for self-reference XSS technique. Only one image stack, the one with test optic, is needed.

Parameters:

  • edge_x (int, or [int, int]) – Area needs to be cut in x dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’x’ (scan in x direction), it is useless.

  • edge_y (int, or [int, int]) – Area needs to be cut in y dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’y’ (scan in y direction), it is useless.

  • edge_z (int, or [int, int]) – Area needs to be cut in scan number dimension. If it is a single integer, it will be expanded automatically to (int, int).

  • nstep (int) – The space between two chosen columns or rows.

  • hw_xy (int) – The width/height of the image subregion. If Tracking.scandim is ‘x’, it is the height of the subregion; if Tracking.scandim is ‘y’, it is the width of the subregion. Needed when do 2D data processing. (default None)

  • pad_xy (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking. If it is a single integer, it will be expanded automatically to (int, int). Needed when do 2D data processing. (default None)

  • normalize (bool) – To normalize the stitched image or not. (default False)

  • display (bool) – To display or not. (default False)

  • verbose (bool) – To show the information or not. (default True)

XSS_self_multi(edge_x, edge_y, edge_z, nstep, hw_xy, pad_xy, cpu_no, normalize=False, verbose=True)[source]

Speckle tracking for self-reference XSS technique. Only one image stack, the one with test optic, is needed.

Warning

BE CAREFUL to check the available and safe cpu numbers before run this function!!

Parameters:

  • edge_x (int, or [int, int]) – Area needs to be cut in x dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’x’ (scan in x direction), it is useless.

  • edge_y (int, or [int, int]) – Area needs to be cut in y dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’y’ (scan in y direction), it is useless.

  • edge_z (int, or [int, int]) – Area needs to be cut in scan number dimension. If it is a single integer, it will be expanded automatically to (int, int).

  • nstep (int) – The space between two chosen columns or rows.

  • hw_xy (int) – The width/height of the image subregion. If Tracking.scandim is ‘x’, it is the height of the subregion; if Tracking.scandim is ‘y’, it is the width of the subregion. Needed when do 2D data processing.

  • pad_xy (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking. If it is a single integer, it will be expanded automatically to (int, int). Needed when do 2D data processing.

  • cpu_no (int) – The number of CPUs that is available.

  • normalize (bool) – To normalize the stitched image or not. (default False)

  • verbose (bool) – To show the information or not. (default True)

XSS_withrefer(edge_x, edge_y, edge_z, hw_xy=None, pad_xy=None, normalize=False, display=False, verbose=True)[source]

Speckle tracking for XSS technique with reference beam. Two image stacks are needed to define the Tracking class. The fisrt image stack is the one with test optic. The second image stack is the reference image stack.

Parameters:

  • edge_x (int, or [int, int]) – Area needs to be cut in x dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’x’ (scan in x direction), it is useless.

  • edge_y (int, or [int, int]) – Area needs to be cut in y dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’y’ (scan in y direction), it is useless.

  • edge_z (int, or [int, int]) – Area needs to be cut in scan number dimension. If it is a single integer, it will be expanded automatically to (int, int).

  • hw_xy (int) – The width/height of the image subregion. If Tracking.scandim is ‘x’, it is the height of the subregion; if Tracking.scandim is ‘y’, it is the width of the subregion. Needed when do 2D data processing. (default None)

  • pad_xy (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking. If it is a single integer, it will be expanded automatically to (int, int). Needed when do 2D data processing. (default None)

  • normalize (bool) – To normalize the stitched image or not. (default False)

  • display (bool) – To display or not. (default False)

  • verbose (bool) – To show the information or not. (default True)

XSS_withrefer_multi(edge_x, edge_y, edge_z, hw_xy, pad_xy, cpu_no, normalize=False, verbose=True)[source]

Speckle tracking for XSS technique with reference beam. The fisrt image stack is the one with test optic. The second image stack is the reference image stack.

Warning

BE CAREFUL to check the available and safe cpu numbers before run this function!!

Parameters:

  • edge_x (int, or [int, int]) – Area needs to be cut in x dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’x’ (scan in x direction), it is useless.

  • edge_y (int, or [int, int]) – Area needs to be cut in y dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’y’ (scan in y direction), it is useless.

  • edge_z (int, or [int, int]) – Area needs to be cut in scan number dimension. If it is a single integer, it will be expanded automatically to (int, int).

  • hw_xy (int) – The width/height of the image subregion. If Tracking.scandim is ‘x’, it is the height of the subregion; if Tracking.scandim is ‘y’, it is the width of the subregion. Needed when do 2D data processing. (default None)

  • pad_xy (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking. If it is a single integer, it will be expanded automatically to (int, int). Needed when do 2D data processing. (default None)

  • cpu_no (int) – The number of CPUs that is available.

  • normalize (bool) – To normalize the stitched image or not. (default False)

  • verbose (bool) – To show the information or not. (default True)

XST_self(edge_x, edge_y, pad_x, pad_y, hw_xy, window=None, normalize=False, display=False, verbose=True)[source]

Speckle tracking for self-reference XST technique. Two image stacks are needed. Both are with test optic. One image stack consists only one image when the diffuser is at one position, another image stack consists another image when the diffuser is at another position.

This technique has been described in [XST_selfpaper]:

[XST_selfpaper]

Hu, L., Wang, H., Fox, O., & Sawhney, K. (2022). Fast wavefront sensing for X-ray optics with an alternating speckle tracking technique. Opt. Exp., 30(18), 33259-33273. https://doi.org/10.1364/OE.460163

Parameters:

  • edge_x (int, or [int, int]) – Area needs to be cut in x dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’x’ (scan in x direction), it is useless.

  • edge_y (int, or [int, int]) – Area needs to be cut in y dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’y’ (scan in y direction), it is useless.

  • pad_x (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking in x direction. If Tracking.dimension is ‘1D’ and Tracking.scandim is is ‘y’, it is useless. If it is a single integer, it will be expanded automatically to (int, int).

  • pad_y (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking in y direction. If Tracking.dimension is ‘1D’ and Tracking.scandim is is ‘x’, it is useless. If it is a single integer, it will be expanded automatically to (int, int).

  • hw_xy (int) – The height (when Tracking.scandim is ‘y’) or the width (when Tracking.scandim is ‘x’) of the subregion to be chosen from the template for cross-correlation.

  • window (int) – The width (when Tracking.scandim is ‘y’) or the height (when Tracking.scandim is ‘x’) of the subregion to be chosen from the template for cross-correlation. Only used when Tracking.dimension is ‘2D’. (default None)

  • normalize (bool) – To normalize the stitched image or not. (default False)

  • display (bool) – To display or not. (default False)

  • verbose (bool) – To show the information or not. (default True)

XST_self_multi(edge_x, edge_y, pad_x, pad_y, hw_xy, window, cpu_no, normalize=False, verbose=True)[source]

Speckle tracking for self-reference XST technique. Two image stacks are needed. Both are with test optic. One image stack consists one image when the diffuser is at one position, another image stack consists another image when the diffuser is at another position.

This technique has been described in [XST_selfpaper2]:

[XST_selfpaper2]

Hu, L., Wang, H., Fox, O., & Sawhney, K. (2022). Fast wavefront sensing for X-ray optics with an alternating speckle tracking technique. Opt. Exp., 30(18), 33259-33273. https://doi.org/10.1364/OE.460163

Warning

BE CAREFUL to check the available and safe cpu numbers before run this function!!

Parameters:

  • edge_x (int, or [int, int]) – Area needs to be cut in x dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’x’ (scan in x direction), it is useless.

  • edge_y (int, or [int, int]) – Area needs to be cut in y dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’y’ (scan in y direction), it is useless.

  • pad_x (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking in x direction. If Tracking.dimension is ‘1D’ and Tracking.scandim is is ‘y’, it is useless. If it is a single integer, it will be expanded automatically to (int, int).

  • pad_y (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking in y direction. If Tracking.dimension is ‘1D’ and Tracking.scandim is is ‘x’, it is useless. If it is a single integer, it will be expanded automatically to (int, int).

  • hw_xy (int) – The height (when Tracking.scandim is ‘y’) or the width (when Tracking.scandim is ‘x’) of the subregion to be chosen from the template for cross-correlation.

  • window (int) – The width (when Tracking.scandim is ‘y’) or the height (when Tracking.scandim is ‘x’) of the subregion to be chosen from the template for cross-correlation. Only used when Tracking.dimension is ‘2D’. (default None)

  • cpu_no (int) – The number of CPUs that is available.

  • normalize (bool) – To normalize the stitched image or not. (default False)

  • verbose (bool) – To show the information or not. (default True)

XST_withrefer(edge_x, edge_y, pad_x, pad_y, hw_xy, window=None, normalize=False, display=False, verbose=True)[source]

Speckle tracking for conventional XST technique, with reference beam. Two image stacks are needed. The fisrt image stack consists one image when the diffuser is in the beam, another image stack consists one reference image without the tested optic.

Parameters:

  • edge_x (int, or [int, int]) – Area needs to be cut in x dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’x’ (scan in x direction), it is useless.

  • edge_y (int, or [int, int]) – Area needs to be cut in y dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’y’ (scan in y direction), it is useless.

  • pad_x (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking in x direction. If Tracking.dimension is ‘1D’ and Tracking.scandim is is ‘y’, it is useless. If it is a single integer, it will be expanded automatically to (int, int).

  • pad_y (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking in y direction. If Tracking.dimension is ‘1D’ and Tracking.scandim is is ‘x’, it is useless. If it is a single integer, it will be expanded automatically to (int, int).

  • hw_xy (int) – The height (when Tracking.scandim is ‘y’) or the width (when Tracking.scandim is ‘x’) of the subregion to be chosen from the template for cross-correlation.

  • window (int) – The width (when Tracking.scandim is ‘y’) or the height (when Tracking.scandim is ‘x’) of the subregion to be chosen from the template for cross-correlation. Only used when Tracking.dimension is ‘2D’. (default None)

  • normalize (bool) – To normalize the stitched image or not. (default False)

  • display (bool) – To display or not. (default False)

  • verbose (bool) – To show the information or not. (default True)

XST_withrefer_multi(edge_x, edge_y, pad_x, pad_y, hw_xy, window, cpu_no, normalize=False, verbose=True)[source]

Speckle tracking for conventional XST technique, with reference beam. Two image stacks are needed. The fisrt image stack consists one image when the diffuser is in the beam, another image stack consists one reference image without the tested optic.

Warning

BE CAREFUL to check the available and safe cpu numbers before run this function!!

Parameters:

  • edge_x (int, or [int, int]) – Area needs to be cut in x dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’x’ (scan in x direction), it is useless.

  • edge_y (int, or [int, int]) – Area needs to be cut in y dimension. If it is a single integer, it will be expanded automatically to (int, int). If Tracking.scandim=’y’ (scan in y direction), it is useless.

  • pad_x (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking in x direction. If Tracking.dimension is ‘1D’ and Tracking.scandim is is ‘y’, it is useless. If it is a single integer, it will be expanded automatically to (int, int).

  • pad_y (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking in y direction. If Tracking.dimension is ‘1D’ and Tracking.scandim is is ‘x’, it is useless. If it is a single integer, it will be expanded automatically to (int, int).

  • hw_xy (int) – The height (when Tracking.scandim is ‘y’) or the width (when Tracking.scandim is ‘x’) of the subregion to be chosen from the template for cross-correlation.

  • window (int) – The width (when Tracking.scandim is ‘y’) or the height (when Tracking.scandim is ‘x’) of the subregion to be chosen from the template for cross-correlation. Only used when Tracking.dimension is ‘2D’.

  • cpu_no (int) – The number of CPUs that is available.

  • normalize (bool) – To normalize the stitched image or not. (default False)

  • verbose (bool) – To show the information or not. (default True)

XSVT_withrefer(edge_xy, edge_z, hw_xy=None, pad_xy=None, normalize=False, display=False, verbose=True)[source]

Speckle tracking for XSVT technique with reference beam. The fisrt image stack is the one with test optic. The second image stack is the reference image stack.

Parameters:

  • edge_xy (int, or [int, int]) – Area needs to be cut in x and y dimensions. If it is a single integer, it will be expanded automatically to (int, int).

  • edge_z (int, or [int, int]) – Area needs to be cut in scan number dimension. If it is a single integer, it will be expanded automatically to (int, int).

  • hw_xy (int) – The width and height of the image subregion. Needed when do 2D data processing. (default None)

  • pad_xy (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking. If it is a single integer, it will be expanded automatically to (int, int). Needed when do 2D data processing. (default None)

  • normalize (bool) – To normalize the stitched image or not. (default False)

  • display (bool) – To display or not. (default False)

  • verbose (bool) – To show the information or not. (default True)

XSVT_withrefer_multi(edge_xy, edge_z, hw_xy, pad_xy, cpu_no, normalize=False, verbose=True)[source]

Speckle tracking for XSVT technique with reference beam. The fisrt image stack is the one with test optic. The second image stack is the reference image stack.

Warning

BE CAREFUL to check the available and safe cpu numbers before run this function!!

Parameters:

  • edge_xy (int, or [int, int]) – Area needs to be cut in x and y dimensions. If it is a single integer, it will be expanded automatically to (int, int).

  • edge_z (int, or [int, int]) – Area needs to be cut in scan number dimension. If it is a single integer, it will be expanded automatically to (int, int).

  • hw_xy (int) – The width and height of the image subregion. Needed when do 2D data processing.

  • pad_xy (int, or [int, int]) – It defines the extra part the reference image needed to do the tracking. If it is a single integer, it will be expanded automatically to (int, int). Needed when do 2D data processing.

  • cpu_no (int) – The number of CPUs that is available.

  • normalize (bool) – To normalize the stitched image or not. (default False)

  • verbose (bool) – To show the information or not. (default True)

collimate(edge_x, edge_y)[source]

This function uses the first image from both imstack1 and imstack2 to align the speckle patterns in the image stacks. It is called before any further tracking method.

Parameters:

  • edge_x (int, or [int, int]) – Area needs to be cut in x dimension. If it is a single integer, it will be expanded automatically to the list [int, int].

  • edge_y (int, or [int, int]) – Area needs to be cut in y dimension. If it is a single integer, it will be expanded automatically to the list [int, int].

property dimension
property dist
property mempos
property pixsize
property scandim
property scanstep
stability(edge_x, edge_y, verbose=True)[source]

Check the stability using speckle pattern.

Parameters:

  • edge_x (int, or [int, int]) – Cutting area of the reference image in x direction. If it is a single integer, it will be expanded automatically to the list [int, int].

  • edge_y (int, or [int, int]) – Cutting area of the reference image in y direction. If it is a single integer, it will be expanded automatically to the list [int, int].

  • verbose (bool) – To show the information or not. (default True)

Returns:

ixs, iys, res – Shifts in two dimensions and the correlation coefficient.

Return type:

numpy.array

stability_multi(edge_x, edge_y, cpu_no, verbose=True)[source]

Multiprocessing version of stability function.

Warning

BE CAREFUL to check the available and safe cpu numbers before run this function!!

Parameters:

  • edge_x (int, or [int, int]) – Cutting area of the reference image in x direction. If it is a single integer, it will be expanded automatically to the list [int, int].

  • edge_y (int, or [int, int]) – Cutting area of the reference image in y direction. If it is a single integer, it will be expanded automatically to the list [int, int].

  • cpu_no (int) – Number of CPU to be used.

  • verbose (bool) – To show the information or not. (default True)

Returns:

ixs, iys, res – Shifts in two dimensions and the coefficient.

Return type:

numpy.array

property subpixelmeth

postfun module

spexwavepy.postfun.EllipseSlope(x, p, q, theta)[source]

This function calculate the slope error at coordinate x. The resulting slope error always starts with 0.

Parameters:

  • x (numpy.array) – Ellipse x coordinate, x starts from 0. [m]

  • p (float) – Ellipse p, [m]

  • q (float) – Ellipse q, [m]

  • theta (float) – Ellipse theta, [rad]

Returns:

Slo – Ellipse slope error at x coordinate, starts from 0. [rad]

Return type:

numpy.array

spexwavepy.postfun.Integration2D_FC(slope_x, slope_y, neg_corr=True)[source]

Reconstruct a surface from the gradients in x and y-direction using the Frankot-Chellappa method. 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. Assuming the space of the mesh grid is 1 \(\mu m\).

Frankot-Chellappa method can be found from [FCIntegration].

[FCIntegration]

Frankot, R, & Chellappa, R. A method for enforcing integrability in shape from shading algorithms IEEE Transactions on pattern analysis and machine intelligence, 1998, 10(4), 439-451. https://doi.org/10.1109/34.3909

Parameters:

  • slope_x (numpy.ndarray) – 2D array. Wavefront slope in x-direction, in \(\mu rad\).

  • slope_y (numpy.ndarray) – 2D array. Wavefront slope in y-direction, in \(\mu rad\).

  • neg_corr (bool, optional) – Correct negative offset if True.

Returns:

2D array. Reconstructed surface. In [pm].

Return type:

numpy.ndarray

spexwavepy.postfun.Integration2D_SCS(slope_x, slope_y, neg_corr=True, pad=0, pad_mode='linear_ramp')[source]

Reconstruct a surface from the gradients in x and y-direction using the Simchony-Chellappa-Shao method. 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. Assuming the space of the mesh grid is 1 \(\mu m\).

The SCS method can be found from [SCSIntegration].

[SCSIntegration]

Simchony T, Chellappa R, Shao, M. Direct analytical methods for solving Poisson equations in computer vision problems IEEE transactions on pattern analysis and machine intelligence 1990, 12(5), 435-446. https://doi.org/10.1109/34.55103

Parameters:

  • slope_x (numpy.ndarray) – 2D array. Wavefront slope in x-direction, in \(\mu rad\).

  • slope_y (numpy.ndarray) – 2D array. Wavefront slope in y-direction, in \(\mu rad\).

  • neg_corr (bool, optional) – Correct negative offset if True.

  • pad (int) – Padding width.

  • pad_mode (str) – Padding method. Full list can be found at numpy.pad documentation.

Returns:

2D array. Reconstructed surface. In [pm].

Return type:

numpy.ndarray

spexwavepy.postfun.curv_XST(delay, scanstep, dist, pixsize, mempos)[source]

Get wavefront local curvature (curvature error) from tracked shift. Used for self-reference XST technique. The corresponding wavefront is on the detector plane.

This function corresponds to Eq. (2) of [HuXSTOEpaper].

[HuXSTOEpaper]

Hu, L., Wang, H., Fox, O., & Sawhney, K. (2022). Fast wavefront sensing for X-ray optics with an alternating speckle tracking technique. Opt. Exp., 30(18), 33259-33273. https://doi.org/10.1364/OE.460163

Parameters:

  • delay (numpy.ndarray) – Tracked shift in the scanned direction. \(iy_{AST}\) in the paper, it must be positive.

  • scanstep (float) – Step size of piezo [\(\mu m\)], \(s\) in the paper.

  • dist (float) – Distance from diffusor to detector plane, if it’s the downstream mode [mm]. If the diffuser is placed in the upstream, usually it is set to be the distance between the centre of the optic to the detector. \(D\) in the paper.

  • pixsize (float) – Detector pixel size [\(\mu m\)], \(p\) in the paper.

  • mempos (str) – ‘downstream’ or ‘upstream’. Use this to define the position of the diffusor in respect to the focus of the optics. ‘downstream’ means the diffuser is placed downstream of the focus. See Local curvature reconstruction for more details of it.

Returns:

curvature – Local curvature [m^-1]

Return type:

numpy.ndarray

spexwavepy.postfun.curv_scan(delay, scanstep, dist, pixsize, nstep, mempos)[source]

Get wavefront local curvature (curvature error) from tracked shift. Used when scanned. The corresponding wavefront is on the detector plane.

This function corresponds to Eq. (3) in [WangXSSOEpaper].

[WangXSSOEpaper]

Wang H, Sutter J, Sawhney K. Advanced in situ metrology for x-ray beam shaping with super precision. Opt Express 2015, 23(2): 1605-1614. https://doi.org/10.1364/OE.23.001605

Parameters:

  • delay (numpy.ndarray) – Tracked shift in the scanned direction. \(\epsilon\) in the paper, it must be positive.

  • scanstep (float) – Step size of piezo [\(\mu m\)], \(\mu\) in the paper.

  • dist (float) – Distance from diffusor to detector plane, if it’s the downstream mode [\(mm\)]. If the diffuser is placed in the upstream, usually it is set to be the distance between the centre of the optic to the detector. \(d\) in the paper.

  • pixsize (float) – Detector pixel size [\(\mu m\)], \(p\) in the paper

  • nstep (int) – ntep, \((j-i)\) in the paper

  • mempos (str) – ‘downstream’ or ‘upstream’. Use this to define the position of the diffusor in respect to the focus of the optics. ‘downstream’ means the diffuser is placed downstream of the focus. See Local curvature reconstruction for more details of it.

Returns:

curvature – Local curvature [m^-1]

Return type:

numpy.ndarray

spexwavepy.postfun.slope_pixel(delay, pixsize, dist)[source]

Get wavefront slope (slope error) from tracked shift. Used when not scanned.

Parameters:

  • delay (numpy.ndarray) – Tracked shift in the scanned direction.

  • pixsize (float) – detector pixel size. Unit in :math: mu m.

  • dist (float) – distance from diffusor to detector plane, if it’s the downstream mode, unit in mm. If the diffuser is placed in the upstream, usually it is set to be the distance between the centre of the optic to the detector.

Returns:

wavefront slope (slope error). Unit in \(\mu rad\).

Return type:

numpy.ndarray

spexwavepy.postfun.slope_scan(delay, scanstep, dist)[source]

Get wavefront slope (slope error) from tracked shift. Used for scan-based technique with reference beam.

Parameters:

  • delay (numpy.ndarray) – Tracked shift in the scanned direction.

  • scanstep (float) – scan step size. Unit in :math: mu m.

  • dist (float) – distance from diffusor to detector plane, if it’s the downstream mode, unit in mm. If the diffuser is placed in the upstream, usually it is set to be the distance between the centre of the optic to the detector.

Returns:

wavefront slope (slope error). Unit in \(\mu rad\).

Return type:

numpy.ndarray