Usage

Start by importing tiepy.

import tiepy-xfel

API

Core Functions

tiepy.speckle.track.fit_gaussian_and_find_peak(correlation_map, window_shape, subset_center, plot=False)

Fit a gaussian function to a window of the correlation map and find the peak coordinates.

This function fits a quadratic function to a window of the correlation map centered around the specified subset_center. It then identifies the peak coordinates within the window.

Parameters:

correlation_map: The correlation map used for fitting and peak detection. [numpy.ndarray]

Should be a 2D numpy array representing the correlation map.

window_shape: A tuple (window_width, window_height) specifying the dimensions of the fitting window. [tuple]

The window is centered around the subset_center and should be smaller than the correlation_map.

subset_center: A tuple (center_x, center_y) specifying the center of the subset for the window. [tuple]

The subset_center should correspond to the center of the region of interest within the correlation_map.

plot: A boolean flag to determine whether to plot the fitting results. [bool, optional]

If True, the function will generate a plot showing the measured and fitted intensity data. Defaults to False.

Returns:

tuple: A tuple (x_peak, y_peak) representing the peak coordinates in the fitted quadratic function. [tuple]

The coordinates are relative to the corrected center of the subset.

Notes:

• The correlation_map should be a 2D numpy array with proper dimensions.

• The window_shape should be smaller than the dimensions of the correlation_map for accurate fitting.

• The subset_center should correspond to the center of the region of interest within the correlation_map.

• The function uses a quadratic fitting method and a Gaussian function for fitting the data.

• The peak coordinates returned are relative to the corrected center of the subset.

• If plot is set to True, the function will generate a 3D plot displaying the measured and fitted intensity data.

tiepy.speckle.track.process_subset_images(reference_image, subset_images, subset_centers, plot=False, method=<function calculate_normalized_correlation>, subpixel=True)

Process a set images (nominally subsets of a larger image) by calculating shifts and correlation maps with respect to a reference image.

This function processes a list of subset images by calculating the subpixel shifts and correlation maps with respect to a given reference image. It utilizes a specified correlation method to perform the calculations.

Parameters:

• reference_image – numpy.ndarray The reference image to which the subset images will be compared. Should be a 2D numpy array representing the grayscale image.

• subset_images – List[numpy.ndarray] A list of subset images to be processed. Each subset image should be a 2D numpy array of the same dtype and dimensions as the reference image.

• subset_centers – List[tuple] A list of tuples (row_center, col_center) specifying the centers of the subset images. Each tuple represents the center position (row, column) of the corresponding subset image.

• plot – bool, optional A boolean flag to determine whether to plot individual graphs for each subset image. If True, plots will be generated for each subset image. Defaults to False.

• method – function, optional The method used to calculate the correlation between the reference image and subset images. This function should take the reference image, subset images, and subset centers as inputs and return a list of correlation maps for each subset. Defaults to calculate_normalized_correlation, a predefined function.

• subpixel – bool, optional A boolean flag to determine whether to compute subpixel shifts. If True, the function will compute subpixel shifts between the reference image and each subset image. Default is False.

Returns:

dict A dictionary containing the processed results for each subset image. The dictionary includes the following keys:

• ’subset_centers’: A list of tuples (row_center, col_center) representing the centers of the subset images.

• ’subpixel_shifts’: A list of tuples (subpixel_shift_x, subpixel_shift_y) indicating the subpixel shifts between the reference image and each subset image. This key will be present only if subpixel is True.

• ’shifts’: A list of tuples (shift_x, shift_y) indicating the shifts between the reference image and each subset image, computed as the peak positions in the correlation maps.

Raises:

AssertionError: If the method is ‘match_template’ and subpixel is set to True. Subpixel resolution is not compatible with the ‘match_template’ method.

Example:

>>> reference_img = np.array([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]])
>>> subset_imgs = [np.array([[0.1, 0.2], [0.4, 0.5]]), np.array([[0.8, 0.9], [0.5, 0.6]])]
>>> centers = [(0, 0), (1, 1)]
>>> results = process_subset_images(reference_img, subset_imgs, centers, plot=True)

Note:

• The reference image and subset images should be grayscale images of the same dtype and proper dimensions.

• The subset_centers should correspond to the centers of the respective subset images.

• The method parameter allows for custom correlation methods to be used, with a default method provided.

• If plot is set to True, individual plots will be generated for each subset image, displaying the subset image, reference image, and magnitude of the correlation map.

• Subpixel shifts will be calculated only if subpixel is True.

tiepy.speckle.track.process_single_image(reference_image, sample_image, window_size, step_size, padding=0, method=<function calculate_normalized_correlation>, subpixel=False, plot=False, extra_metadata={})

Process a single image by extracting subsets, computing correlation, and subpixel shifts.

Parameters:

• reference_image – numpy.ndarray The reference image to which the subset images will be compared.

• sample_image – numpy.ndarray The input 2D image array to be processed.

• window_size – int The window size for cropping subsets. The window will be a square of size window_size x window_size.

• step_size – int The step size for moving the window in both the x and y directions.

• padding – int, optional The padding distance from the image boundaries. The window will not be drawn within this distance from the edges of the image. Default is 0.

• method – callable, optional The method to be used for computing the correlation between the reference and subset images. It should be a callable function that accepts two numpy.ndarray arguments and returns a 2D correlation map. Defaults to calculate_normalized_correlation.

• subpixel – bool, optional A boolean flag to determine whether to compute subpixel shifts. If True, the function will compute subpixel shifts between the reference image and each subset image. Default is False.

• plot – bool, optional A boolean flag to determine whether to plot individual graphs for each subset image. Default is False.

• extra_metadata – dict, optional Additional metadata to include in the results dictionary. This should be provided as a dictionary containing key-value pairs representing the metadata. Default is an empty dictionary.

Returns:

dict A dictionary containing the processed results for each subset image. The dictionary includes the following keys:

• ’coords_x’: numpy.ndarray

  A 1D array containing the horizontal (x) coordinates of the centers of the subset images.

• ’coords_y’: numpy.ndarray

  A 1D array containing the vertical (y) coordinates of the centers of the subset images.

• ’shifts_x’: numpy.ndarray

  A 1D array containing the horizontal (x) shifts between the reference image and each subset image, computed as the peak positions in the correlation maps.

• ’shifts_y’: numpy.ndarray

  A 1D array containing the vertical (y) shifts between the reference image and each subset image, computed as the peak positions in the correlation maps.

• ’subpixel_shifts_x’: numpy.ndarray (optional)

  A 1D array containing the horizontal (x) subpixel shifts between the reference image and each subset image. This key will be present in the dictionary only if the ‘subpixel’ parameter is set to True.

• ’subpixel_shifts_y’: numpy.ndarray (optional)

  A 1D array containing the vertical (y) subpixel shifts between the reference image and each subset image. This key will be present in the dictionary only if the ‘subpixel’ parameter is set to True.

• Additional Metadata (optional):

  This dictionary can include any additional metadata specified by the ‘extra_metadata’ parameter.

Example:

>>> import numpy as np
>>> reference_image = np.random.rand(100, 100)  # Example 2D reference image of size 100x100
>>> sample_image = np.random.rand(300, 300)  # Example 2D sample image of size 300x300
>>> window_size = 50
>>> step_size = 10
>>> padding = 20
>>> results = process_single_image(reference_image, sample_image, window_size, step_size, padding, plot=True)

Note:

• The ‘reference_image’ and ‘sample_image’ should be 2D numpy arrays with proper dimensions.

• The ‘window_size’ and ‘step_size’ should be positive integers.

• The ‘padding’ should be a non-negative integer.

• The ‘method’ parameter determines the correlation method used and should be a callable function.

Tracking Methods

tiepy.speckle.track.match_template(reference_image, subset_images, method=3)

Perform template matching using OpenCV’s cv2.matchTemplate function on multiple subset images.

Parameters:

• reference_image – numpy.ndarray The reference image to be matched against the subset images. It should be a 2D array (grayscale image).

• subset_images – list of numpy.ndarray A list containing the subset images to which the reference template will be matched. Each subset image should be a 2D array (grayscale image).

• method – int, optional The method to be used for matching. Refer to cv2.matchTemplate documentation for method options. Defaults to 3 (cv2.TM_CCOEFF_NORMED).

Returns:

list of tuple A list containing the locations (x, y) of the best match in each subset image. Each location corresponds to the top-left corner of the matched region.

Raises:

AssertionError –

• If the ‘method’ parameter is not of integer type or outside the range [0, 5].

Note:

• The ‘reference_image’ and each ‘subset_image’ should be grayscale images of the same dtype and have proper dimensions.

• The ‘method’ parameter determines the matching method to be used. It should be an integer index in the range [0, 5].

• The output list of tuples represents the locations of the best matches in the subset images.

tiepy.speckle.track.calculate_correlation(reference_image, subset_images, subset_centers)

Calculate correlation maps between a reference image and a list of subset images.

This function calculates the correlation maps between a reference image and a list of subset images. The correlation maps represent the similarity between the reference image and each subset image.

Parameters:

reference_image: The reference image to which the subset images will be compared. [numpy.ndarray]

Should be a 2D numpy array representing the grayscale image.

subset_images: A list of subset images to be compared with the reference image. [List[numpy.ndarray]]

Each subset image should be a 2D numpy array of the same dtype and dimensions as the reference image.

subset_centers: A list of tuples (row_center, col_center) specifying the centers of the subset images. [List[tuple]]

Each tuple represents the center position (row, column) of the corresponding subset image.

Returns:

List[numpy.ndarray]: A list of 2D numpy arrays representing the correlation maps for each subset image.

Each correlation map represents the similarity between the reference image and the respective subset image.

Example:

>>> reference_img = np.array([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]])
>>> subset_imgs = [np.array([[0.1, 0.2], [0.4, 0.5]]), np.array([[0.8, 0.9], [0.5, 0.6]])]
>>> centers = [(0, 0), (1, 1)]
>>> correlation_maps = calculate_correlation(reference_img, subset_imgs, centers)

tiepy.speckle.track.calculate_normalized_correlation(reference_image, subset_images, normalize=True)

Calculate normalized correlation maps between a reference image and a list of subset images.

This function calculates the normalized correlation maps between a reference image and a list of subset images. The correlation maps represent the similarity between the reference image and each subset image after normalization.

Parameters:

reference_image: The reference image to which the subset images will be compared. [numpy.ndarray]

Should be a 2D numpy array representing the grayscale image.

subset_images: A list of subset images to be compared with the reference image. [List[numpy.ndarray]]

Each subset image should be a 2D numpy array of the same dtype and dimensions as the reference image.

normalize: A boolean flag to determine whether to normalize the reference and subset images. [bool, optional]

If True, the images will be normalized before calculating the correlation. Defaults to True.

Returns:

List[numpy.ndarray]: A list of 2D numpy arrays representing the normalized correlation maps for each subset image.

Each correlation map represents the similarity between the reference image and the respective subset image.

Example:

>>> reference_img = np.array([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]])
>>> subset_imgs = [np.array([[0.1, 0.2], [0.4, 0.5]]), np.array([[0.8, 0.9], [0.5, 0.6]])]
>>> normalized_correlation_maps = calculate_normalized_correlation(reference_img, subset_imgs, normalize=True)

Phase Retrieval

tiepy.speckle.phase_retrieval.kottler(dX, dY)

Perform Kottler phase retrieval on a given complex-valued object.

This function applies the Kottler method for phase retrieval on a complex-valued object represented by the real and imaginary parts dX and dY, respectively. The Kottler method uses the Fast Fourier Transform (FFT) to estimate the phase of the object.

Parameters:

dX (numpy.ndarray): 2D array representing the real part of the complex object.

Shape should be (Nx, Ny), where Nx and Ny are the dimensions of the object.

dY (numpy.ndarray): 2D array representing the imaginary part of the complex object.

Shape should be (Nx, Ny), matching the dimensions of dX.

Returns:

numpy.ndarray: 2D array containing the estimated phase of the complex object.

Notes:

• The input arrays dX and dY should have the same shape and dtype.

• The output array phi3 will contain the estimated phase of the complex object.

tiepy.speckle.phase_retrieval.paganin_algorithm(ii, z, wav, delta, beta)

Paganin Algorithm for phase retrieval.

Parameters:

• ii – numpy.ndarray 4D array of shape (Nx, Ny, K, N), representing the set of K by N projection images. Nx and Ny are the dimensions of each image, K is the number of projection angles, and N is the number of iterations.

• z – float Propagation distance. The distance between the object and the detector.

• wav – float X-ray wavelength.

• delta – float Refractive index decrement.

• beta – float X-ray attenuation coefficient.

Returns:

numpy.ndarray 4D array of shape (Nx, Ny, K, N), containing the estimated phase for each projection image.

Raises:

AssertionError: If the input ‘ii’ does not have dtype ‘float64’.

Notes:

• The input ii should have dtype ‘float64’.

• The output phase represents the estimated phase shift caused by the object.

Reference:

D. Paganin, “Simultaneous phase and amplitude extraction from a single defocused image of a homogeneous object,” Journal of Microscopy, vol. 206, no. 1, pp. 33-40, 2002.

Utilities

IO

tiepy.speckle.io.print_h5_keys(filename)

Print the keys present in an HDF5 file.

Parameters:

filename – str The name of the HDF5 file from which keys will be retrieved and printed.

Returns:

None

Example:

>>> print_h5_keys('data.h5')
Keys in the HDF5 file:
dataset1
dataset2
dataset3

tiepy.speckle.io.load_tiff_as_npy(filename)

Load a TIFF file as a NumPy array.

Parameters:

filename (str): The path to the TIFF file.

Returns:

numpy.ndarray: The loaded image as a NumPy array.

tiepy.speckle.io.get_keys(filename)

Get the keys present in an HDF5 file.

Parameters:

filename – str The name of the HDF5 file from which keys will be retrieved.

Returns:

list A list containing the keys present in the HDF5 file.

Example:

>>> keys = get_keys('data.h5')
>>> print(keys)
['dataset1', 'dataset2', 'dataset3']

tiepy.speckle.io.create_virtual_h5(directory, output_filename)

Create a virtual HDF5 file from multiple individual HDF5 files in a directory.

Parameters:

• directory – str The directory containing the HDF5 files to be combined.

• output_filename – str The name of the virtual HDF5 file to be created.

Returns:

None

Example:

>>> create_virtual_h5('data_directory', 'virtual_data.h5')
Virtual dataset created in virtual_data.h5

tiepy.speckle.io.save_dict_to_h5(dictionary, filename)

Save a dictionary to an HDF5 file.

Parameters:

• dictionary – dict The dictionary containing the data to be saved. The keys represent the dataset names, and the values represent the data to be stored.

• filename – str The name of the HDF5 file where the dictionary will be saved. If the file already exists, it will be overwritten.

Returns:

None

Example:

>>> data = {'dataset1': [1, 2, 3], 'dataset2': (10, 20, 30), 'dataset3': 42}
>>> save_dict_to_h5(data, 'data.h5')
# Creates an HDF5 file 'data.h5' containing three datasets: 'dataset1', 'dataset2', and 'dataset3'.

tiepy.speckle.io.load_dict_from_h5(filename)

Load a dictionary from an HDF5 file.

Parameters:

filename – str The name of the HDF5 file from which the dictionary will be loaded.

Returns:

dict A dictionary containing the data loaded from the HDF5 file. The keys represent the dataset names, and the values represent the corresponding data arrays.

Example:

>>> loaded_data = load_dict_from_h5('data.h5')
>>> print(loaded_data)
{'dataset1': array([1, 2, 3]), 'dataset2': array([10, 20, 30]), 'dataset3': array(42)}

tiepy.speckle.io.load_key_from_virtual_h5(virtual_file, key)

Test Samples

tiepy.speckle.objects.generate_speckle_pattern(shape, intensity_range, speckle_size=1)

Generate a speckle pattern (gaussian filtered random noise) array.

Parameters:

• shape – A tuple (rows, columns) specifying the shape of the array. [tuple]

• intensity_range – A tuple (min_intensity, max_intensity) specifying the range of intensity values. [tuple]

• speckle_size – width of gaussian filter

Returns:

A 2D numpy array containing the speckle pattern. [numpy.ndarray]

tiepy.speckle.objects.generate_gaussian_2d(shape, center, sigma)

Generate a 2D Gaussian array.

Parameters:

• shape – A tuple (rows, columns) specifying the shape of the array. [tuple]

• center – A tuple (row_center, col_center) specifying the center of the Gaussian. [tuple]

• sigma – A float representing the standard deviation of the Gaussian. [float]

Returns:

A 2D numpy array containing the Gaussian. [numpy.ndarray]