motion_correction package

Subpackages

Submodules

motion_correction.algorithms module

class motion_correction.algorithms.Morphic(sigma_diff: float = 20, radius=15)[source]

Bases: _CorrectionAlgorithm

Aligns two images using MORPHIC image registration. Uses GPU if available :param sigma_diff: (float) The standard deviation for difference calculation (default: 20) :param radius: (int) The radius for the cross-correlation computation (default: 15).

align(fixed_img, moving_img)[source]

Aligns two images using MORPHIC image registration.

Parameters:

  • fixed_img – (ndarray) The reference image.

  • moving_img – (ndarray) The image to be aligned.

  • sigma_diff – (float) The standard deviation for difference calculation (default: 20).

  • radius – (int) The radius for the cross-correlation computation (default: 15).

Return aligned:

(ndarray) The aligned version of the moving image.

Return transform:

(ndarray) A 3x3 transformation matrix.

align_morphic_cpu(fixed_img, moving_img)[source]
align_morphic_gpu(fixed_img, moving_img)[source]
class motion_correction.algorithms.OpticalILK[source]

Bases: _CorrectionAlgorithm

align(fixed_img, moving_img)[source]

Aligns two images using the Iterative Lucas-Kanade (ILK) optical flow algorithm.

Parameters:

  • fixed_img – (ndarray) The reference image.

  • moving_img – (ndarray) The image to be aligned.

  • sigma_diff – (float) The standard deviation for difference calculation (default: 20).

  • radius – (int) The radius for the cross-correlation computation (default: 15).

Return aligned:

(ndarray) The aligned version of the moving image.

Return transform:

(ndarray) A 3x3 transformation matrix.

class motion_correction.algorithms.OpticalPoly[source]

Bases: _CorrectionAlgorithm

Aligns two images using polynomial expansion-based optical flow.

align(fixed_img, moving_img)[source]
Parameters:

  • fixed_img – (ndarray) The reference image.

  • moving_img – (ndarray) The image to be aligned.

  • sigma_diff – (float) The standard deviation for difference calculation (default: 20).

  • radius – (int) The radius for the cross-correlation computation (default: 15).

Return aligned:

(ndarray) The aligned version of the moving image.

Return transform:

(ndarray) A 3x3 transformation matrix.

Note: This function estimates the optical flow between two images using polynomial expansion and applies the estimated flow to align the moving image with the fixed image.

class motion_correction.algorithms.OpticalTVL1[source]

Bases: _CorrectionAlgorithm

Aligns two images using the TV-L1 optical flow algorithm.

align(fixed_img, moving_img)[source]
Parameters:

  • fixed_img – (ndarray) The reference image.

  • moving_img – (ndarray) The image to be aligned.

  • sigma_diff – (float) The standard deviation for difference calculation (default: 20).

  • radius – (int) The radius for the cross-correlation computation (default: 15).

Return aligned:

(ndarray) The aligned version of the moving image.

Return transform:

(ndarray) A 3x3 transformation matrix.

Note: This function estimates the optical flow between two images using the TV-L1 algorithm and applies the estimated flow to align the moving image with the fixed image.

class motion_correction.algorithms.Phase[source]

Bases: _CorrectionAlgorithm

Aligns two images using phase correlation-based alignment.

align(fixed_img, moving_img)[source]

Aligns two images using phase correlation-based alignment.

Parameters:

  • fixed_img – (ndarray) The reference image.

  • moving_img – (ndarray) The image to be aligned.

  • sigma_diff – (float) The standard deviation for difference calculation (default: 20).

  • radius – (int) The radius for the cross-correlation computation (default: 15).

Return aligned:

(ndarray) The aligned version of the moving image.

Return transform:

(ndarray) A 3x3 transformation matrix.

Note: This function computes the translation between two images using phase correlation and applies the translation to align the moving image with the fixed image.

motion_correction.motion_correction module

Main module.

class motion_correction.motion_correction.CorrectionResults[source]

Bases: TypedDict

combined_transforms: ndarray[Any, dtype[float32]]
corrected_intensity_data_stack: ndarray[Any, dtype[uint16]]
global_corrected_intensity_data_stack: ndarray[Any, dtype[uint16]]
global_transforms: ndarray[Any, dtype[float32]]
local_transforms: ndarray[Any, dtype[float32]]
metrics: Metrics
class motion_correction.motion_correction.Metric[source]

Bases: TypedDict

corrected: ndarray[Any, dtype[float32]]
global_corrected: ndarray[Any, dtype[float32]]
original: ndarray[Any, dtype[float32]]
class motion_correction.motion_correction.Metrics[source]

Bases: TypedDict

mse: Metric
ncc: Metric
nrm: Metric
spm: Metric
ssi: Metric
motion_correction.motion_correction.apply_correction_flim(flim_data_stack: ndarray[Any, dtype[uint8]], transform_matrix: ndarray[Any, dtype[float64]], exclude: list[int] | None = None, delete: bool = False)[source]

Applies a transformation matrix to a flim data stack

Parameters:

  • flim_data_stack – A numpy array defining the FLIM data stack to be corrected (loaded from pqreader module).

  • transform_matrix – Array of dimension (2, width, height, frames) defining the x and y displacements to be applied to each pixel of each frame

  • exclude – Optional, list of frames to exclude from final output

  • delete – Optional, delete input data stack to save memory

Return corrected_flim_data_stack:

A numpy array of same shape as flim_data_stack

motion_correction.motion_correction.calculate_correction(intensity_data_stack: ndarray[Any, dtype[uint8]], reference_frame: int = 0, local_algorithm: _CorrectionAlgorithm | None = None, global_algorithm: _CorrectionAlgorithm | None = None) → CorrectionResults[source]

Calculates motion correction for given intensity data stack based on chosen algorithms

Parameters:

  • intensity_data_stack – A numpy array defining the intensity frames to use for correction (output of get_intensity_stack)

  • reference_frame – The reference frame to use

  • local_algorithm – Optional, CorrectionAlgorithm to use, imported from motion_correction.algorithms

  • global_algorithm – Optional, CorrectionAlgorithm to use, imported from motion_correction.algorithms

Return CorrectionResults:
dictionary with keys:

  • global_corrected_intensity_data_stack: original intensity data stack with global corrections applied

  • corrected_intensity_data_stack: original intensity data stack with : original intensity data stack with global and local corrections applied

  • metrics: dict with fields for each metric (ncc, mse, nrm, ssi), with each entry looking like

    • {…

    ‘ncc’: {

    ‘original’: numpy array of length num_frames, metric values for original frames ‘global_corrected’ : numpy array of length num_frames, metric values for globally corrected frames ‘corrected: numpy array of length num_frames, metric values for corrected frames

    }, …

    }

  • combined_transforms: Array of dimension (2, width, height, frames) defining the combined local and global vertical and horizontal displacements to be applied to each pixel of each frame

  • local_transforms: Array of dimension (2, width, height, frames) defining the local transformation

  • global_transforms: Array of dimension (2, width, height, frames) defining the global transformation

motion_correction.motion_correction.get_aggregated_intensity_image(flim_data_stack: ndarray[Any, dtype[uint8]], channel: int) → ndarray[Any, dtype[uint8]][source]

Converts an intensity stack to a single intensity image representing the sum of all frames in the stack

Parameters:

  • intensity_data_stack – A numpy array defining the intensity frames

  • channel – Channel to use

Return intensity_frame:

A single frame, shape (width,height)

motion_correction.motion_correction.get_intensity_stack(flim_data_stack: ndarray[Any, dtype[uint8]], channel: int) → ndarray[Any, dtype[uint8]][source]

Converts a FLIM data stack (output of pqreader) to a stack of intensity frames for a single channel

Parameters:

  • flim_data_stack – A numpy array defining the FLIM data stack to be corrected (loaded from pqreader module).

  • channel – Channel to use for intensity

Return intensity_stack:

Array of dimension (width,height,n_frames)

motion_correction.pqreader module

This module contains functions to load and decode files from PicoQuant hardware.

motion_correction.pqreader.load_ptfile(filename, is_raw=False, gcs=False, progress_cb=None, destination_file=None) → tuple[ndarray[Any, dtype[_ScalarType_co]], dict][source]

Load a .pt3 or .ptu into a numpy array

Parameters:

  • filename – Name of file to load

  • gcs – Whether file is from google cloud storage (changes the header)

  • progress_cb – Callback function which is called with progress as a value between 0 and 1

  • destination_file – file where resultant numpy array is saved

Return flim_data_stack:

numpyarray of size (num_pixel_Y, num_pixel_X, channels, num_of_frames, num_tcspc_channel)

Return meta:

metadata dictionary

motion_correction.pqreader.plot_sequence_images(image_array)[source]

Display images sequence as an animation in jupyter notebook

Args:

image_array(numpy.ndarray): image_array.shape equal to (num_images, height, width, num_channels)

motion_correction.pqwriter module

motion_correction.pqwriter.write_pt3(meta, flim_data_stack, filename)[source]

Write a FLIM data stack to a .pt3 file

Parameters:

  • meta – Must be the same meta dictionary from pqreader.load_ptfile function

  • flim_data_stack – A numpy array, usually after applying motion correction algorightms

  • filename – Output filename

Module contents