Utilities#

Image processing and helper utilities for motion correction workflows.

Image Processing#

Image processing utilities for motion correction. Provides normalization and filtering functions extracted from CompensateRecording.

pyflowreg.util.image_processing.normalize(arr, ref=None, channel_normalization='together', eps=1e-08)[source]#

Normalize array to [0,1] range.

Parameters:

  • arr – Array to normalize, shape (H,W,C) or (T,H,W,C)

  • ref – Optional reference for normalization ranges (MATLAB compatibility)

  • channel_normalization – ‘separate’ for per-channel, ‘together’ for global

  • eps – Small value to avoid division by zero

Return type:

ndarray

Returns:

Normalized array in [0,1] range

pyflowreg.util.image_processing.apply_gaussian_filter(arr, sigma, mode='reflect', truncate=4.0)[source]#

Apply Gaussian filtering matching MATLAB’s imgaussfilt3 for multichannel data.

Parameters:

  • arr – Input array, shape (H,W,C) or (T,H,W,C)

  • sigma – Standard deviation for Gaussian kernel - array shape (3,): [sy, sx, st] for all channels - array shape (n_channels, 3): per-channel sigmas

  • mode – Boundary handling mode

  • truncate – Truncate filter at this many standard deviations

Return type:

ndarray

Returns:

Filtered array

pyflowreg.util.image_processing.gaussian_filter_1d_half_kernel(buffer, sigma_t, mode='reflect', truncate=4.0)[source]#

Fast 1D Gaussian filter using half kernel for temporal dimension. Optimized for real-time filtering with circular buffer.

Parameters:

  • buffer – deque of 2D filtered frames [oldest…newest]

  • sigma_t – Temporal standard deviation

  • mode – Boundary handling mode (unused, kept for API consistency)

  • truncate – Truncate filter at this many standard deviations

Return type:

ndarray

Returns:

Temporally filtered current frame (last in buffer)

Pyramid Resizing#

Efficient aliasing-free pyramid resizing using fused Gaussian-cubic interpolation.

pyflowreg.util.resize_util.resize_image_skimage(image, size)[source]#

Resize an image to the specified size using the given interpolation method.

Parameters: - image: Input image to be resized. - size: Tuple (width, height) specifying the new size. - interpolation: Interpolation method to use for resizing.

Returns: - Resized image.

pyflowreg.util.resize_util.resize_image_cv2(image, size)[source]#

Resize an image to the specified size using the given interpolation method.

Parameters: - image: Input image to be resized. - size: Tuple (width, height) specifying the new size. - interpolation: Interpolation method to use for resizing.

Returns: - Resized image.

pyflowreg.util.resize_util.resize_image_cv2_aa_gauss(image, size)[source]#
pyflowreg.util.resize_util.imresize_cv2_aa_gauss_sep(img, size)[source]#
pyflowreg.util.resize_util.imresize_numba(img, size)[source]#
pyflowreg.util.resize_util.resize_image_cv2_aa_blur(image, size)[source]#
pyflowreg.util.resize_util.imresize_fused_gauss_cubic(img, size, sigma_coeff=0.6, per_axis=False)[source]#

Cross-Correlation Pre-Alignment#

pyflowreg.util.xcorr_prealignment.estimate_rigid_xcorr_2d(ref_img, mov_img, target_hw=(256, 256), up=1, normalization='phase', disambiguate=True, weight=None)[source]#

Estimate rigid displacement between 2D images using phase cross-correlation.

Parameters:

  • ref_img (np.ndarray) – Reference image, shape (H, W) or (H, W, C)

  • mov_img (np.ndarray) – Moving image, shape (H, W) or (H, W, C)

  • target_hw (tuple or int) – Target size for downsampling before correlation

  • up (int) – Upsampling factor for subpixel accuracy (1 = no upsampling)

  • normalization (str) – Normalization method for phase_cross_correlation

  • disambiguate (bool) – Whether to disambiguate sign of shift

  • weight (np.ndarray or None) – Channel weights for multi-channel images

Returns:

np.ndarray – Displacement vector [dx, dy] (negated for backward warp convention)

Visualization#

pyflowreg.util.visualization.color_map_numpy_2ch(img_in, scaling_left=None, scaling_right=None, reference_left=None, reference_right=None, inverted=False, return_float=False)[source]#

Convert a 2-channel image to a 3-channel color visualization.

Parameters:

  • img_in – Input 2-channel image (H, W, 2) or stacked 2-channel images

  • scaling_left – Tuple of (scale, offset) for left channel. Default (1, 0)

  • scaling_right – Tuple of (scale, offset) for right channel. Default (1, 0)

  • reference_left – Reference array for left channel normalization

  • reference_right – Reference array for right channel normalization

  • inverted – If True, swap red and blue channels

  • return_float – If True, return float array in [0,1], else uint8 in [0,255]

Return type:

ndarray

Returns:

3-channel color image

pyflowreg.util.visualization.get_visualization(ch1, ch2, scaling_left=None, scaling_right=None, reference_left=None, reference_right=None, inverted=False)[source]#

MATLAB-compatible visualization function for 2-channel images.

This function reproduces the exact behavior of the MATLAB get_visualization function, including the typo in the original where reference_left min is used in ch2 normalization.

Parameters:

  • ch1 – First channel data

  • ch2 – Second channel data

  • scaling_left – Tuple of (scale, offset) for left channel. Default (1, 0)

  • scaling_right – Tuple of (scale, offset) for right channel. Default (1, 0)

  • reference_left – Reference array for left channel normalization

  • reference_right – Reference array for right channel normalization

  • inverted – If True, swap red and blue channels

Return type:

ndarray

Returns:

3-channel float image in range [0, 1]

pyflowreg.util.visualization.multispectral_mapping(img)[source]#

Map multispectral image to RGB visualization.

Parameters:

img – Input image with shape (H, W, C) where C is number of channels/bands

Return type:

ndarray

Returns:

RGB image with shape (H, W, 3) normalized to [0, 1]

pyflowreg.util.visualization.quiver_visualization(img, w, scale=1.0, downsample=0.03, show_streamlines=True, backend='matplotlib', return_array=True, quiver_color=(255, 255, 255), streamline_color=(0, 0, 0))[source]#

Create quiver visualization of displacement field overlaid on image. Automatically detects number of channels and applies appropriate mapping.

Parameters:

  • img – Input image (H, W) or (H, W, C)

  • w – Displacement field with shape (H, W, 2)

  • scale – Scale factor for quiver arrows

  • downsample – Downsampling factor for quiver display (default 0.03)

  • show_streamlines – Whether to show streamlines

  • backend – Visualization backend - “matplotlib” or “opencv”

  • return_array – If True, return numpy array; if False, display plot

  • quiver_color – RGB color for quiver arrows (default white)

  • streamline_color – RGB color for streamlines (default black)

Return type:

ndarray

Returns:

Visualization image as numpy array if return_array=True

Raises:

  • ImportError – If matplotlib is not available when using matplotlib backend

  • ValueError – If invalid backend is specified

pyflowreg.util.visualization.flow_to_color(flow, max_flow=None)[source]#

Download Helpers#

Download utilities for pyflowreg demo data.

Provides centralized download functionality for all demo datasets.

pyflowreg.util.download.download_data(url, filename, output_folder)[source]#

Download a file from a URL to a specified folder.

Parameters:

  • url (str) – The URL to download from.

  • filename (str) – The name to save the file as.

  • output_folder (Union[str, Path]) – The folder to save the file in.

Return type:

Path

Returns:

Path – The path to the downloaded file.

Raises:

urllib.error.URLError – If the download fails.

pyflowreg.util.download.download_demo_data(demo_name, output_folder=None)[source]#

Download demo data by name using predefined URLs.

Parameters:

  • demo_name (str) – The name of the demo data file to download. Must be one of the keys in DEMO_DATA_URLS.

  • output_folder (Optional[Union[str, Path]]) – The folder to save the file in. If None, uses ‘data’ folder relative to project root.

Return type:

Path

Returns:

Path – The path to the downloaded file.

Raises:

Examples

>>> # Download jupiter demo data
>>> jupiter_path = download_demo_data("jupiter.tiff")

>>> # Download synthetic evaluation data
>>> synth_path = download_demo_data("synth_frames.h5")

Superresolution Helpers#

pyflowreg.util.superresolution_helpers.warp_image_highres(image, flow, scale=4)[source]#