API Reference

Enhancement

Settings

Configuration dataclasses for the VSPI fluorescence enhancement algorithm.

class ptychozoon.settings.SaveFileExtensions(value)[source]

Bases: StrEnum

Supported output file format extensions for saving VSPI results.

H5

HDF5 file format (.h5).

Type:: str

TIFF

TIFF image stack format (.tiff).

Type:: str

H5 = '.h5'

TIFF = '.tiff'

class ptychozoon.settings.InterpolationTypes(value)[source]

Bases: StrEnum

Interpolation strategies for mapping probe positions to object pixels.

FOURIER

Fourier-shift interpolation. Requires a GPU (CuPy) array module. Produces the most accurate sub-pixel results.

Type:: str

BARYCENTRIC

Bilinear (barycentric) interpolation. Works on both CPU and GPU but is considerably slower than the Fourier method.

Type:: str

FOURIER = 'fourier'

BARYCENTRIC = 'barycentric'

class ptychozoon.settings.SolverTypes(value)[source]

Bases: StrEnum

Iterative linear solver to use for the VSPI deconvolution.

LSMR

Least-Squares Minimum Residual solver (scipy.sparse.linalg.lsmr()). Supports optional Tikhonov regularisation via a damping factor.

Type:: str

LSMR = 'lsmr'

class ptychozoon.settings.LSMRSettings(damping_factor=0.0, gradient_smoothness=0.0, max_iter=10, atol=1e-06, btol=1e-06, checkpoint_interval=None)[source]

Bases: object

Hyper-parameters for the LSMR iterative solver.

damping_factor

Tikhonov regularisation parameter. A value of 0.0 (default) means no regularisation is applied.

Type:: float

gradient_smoothness

Gradient-smoothness regularisation weight (λ). Penalises pixel-to-pixel variation via finite-difference operators along both image axes. A value of 0.0 (default) disables this regulariser.

Type:: float

max_iter

Maximum number of LSMR iterations to run in total.

Type:: int

atol

Tolerance on the norm of the relative residual ‖b − A x‖ / ‖b‖. Iteration stops when the residual drops below this value.

Type:: float

btol

Tolerance on the norm of A^T (b − A x). Controls convergence of the adjoint residual.

Type:: float

checkpoint_interval

If set, the algorithm yields an intermediate result every this many LSMR iterations (e.g. 5 → yields at iterations 5, 10, 15, …). If None, only the final result is yielded.

Type:: int or None

damping_factor: float = 0.0: Damping factor for regularized least-squares

gradient_smoothness: float = 0.0: Gradient-smoothness regularisation weight (λ). Penalises pixel-to-pixel variation in the solution via finite-difference operators applied along both image axes. A value of 0.0 (default) disables this regulariser.

max_iter: int = 10

atol: float = 1e-06

btol: float = 1e-06

checkpoint_interval: int | None = None: Yield the solution every this many iterations. If None, only yield the final result.

class ptychozoon.settings.GPUSettings(enabled=True, index=0)[source]

Bases: object

Settings for GPU (CuPy) accelerated computation.

enabled

Whether to use GPU acceleration. Requires CuPy and a CUDA-capable device. When False, NumPy / SciPy are used instead.

Type:: bool

index

Zero-based CUDA device index to use when enabled is True.

Type:: int

enabled: bool = True

index: int = 0

class ptychozoon.settings.DeconvolutionEnhancementSettings(solver=SolverTypes.LSMR, lsmr=<factory>, gpu=<factory>, _interpolation=InterpolationTypes.FOURIER)[source]

Bases: object

Top-level configuration for the VSPI fluorescence enhancement algorithm.

solver

Iterative linear solver to use for the deconvolution.

Type:: SolverTypes

lsmr

Hyper-parameters for the LSMR solver.

Type:: LSMRSettings

interpolation

Interpolation strategy for mapping probe positions to object pixels.

Type:: InterpolationTypes

gpu

GPU acceleration settings.

Type:: GPUSettings

solver: SolverTypes = 'lsmr'

lsmr: LSMRSettings

gpu: GPUSettings

Viewer

Saving Results

Functions for saving VSPI fluorescence enhancement results.

ptychozoon.save.save_vspi_results(folder, name, vspi_results, filetype, save_every_n_frames=1)[source]

Save VSPI results to disk.

Each element’s 2D maps across all checkpoint iterations are stacked into a 3D array of shape (n_frames, height, width) before saving. When saving to HDF5, an additional "epochs" dataset is written containing the iteration number corresponding to each frame.

Parameters:

folder (str) – Parent output directory.
name (str) – Name suffix for this result set.
vspi_results (List[Tuple[FluorescenceDataset, int]]) – List of (FluorescenceDataset, iteration_number) tuples as returned by VSPIFluorescenceEnhancingAlgorithm.enhance.
filetype (SaveFileExtensions) – Output format — SaveFileExtensions.TIFF or SaveFileExtensions.H5.
save_every_n_frames (int) – Stride for subsampling results before saving. For example, 2 saves every other result. Defaults to 1 (save all results).

ptychozoon.save.load_vspi_results_h5(h5_path)[source]

Load VSPI results from an HDF5 file saved by save_vspi_results().

Parameters:: h5_path (str) – Path to the .h5 file.
Returns:: List of (FluorescenceDataset, iteration_number) tuples, one per saved frame, in the same format as returned by VSPIFluorescenceEnhancingAlgorithm.enhance.
Return type:: List[Tuple[FluorescenceDataset, int]]

Patch Operations

ptychozoon.patches.extract_patches_fourier_shift(image, positions, shape, pad=1)

Extract patches from a 2D array. If a patch’s footprint goes outside the image, the image is padded with zeros to account for the missing pixels.

Parameters:

image (ndarray) – The whole image.
positions (ndarray) – An array of shape (N, 2) giving the center positions of the patches in pixels. The origin of the given positions are assumed to be the TOP LEFT corner of the image.
shape (tuple of int) – A tuple giving the patch shape in pixels.
pad (Optional[int]) – If given, patches with larger size than the intended size by this amount are cropped out from the patches before shifting.

Returns:

An array of shape (N, H, W) containing the extracted patches.

Return type:

ndarray

ptychozoon.patches.fourier_shift(images, shifts, strictly_preserve_zeros=False)

Apply Fourier shift to a batch of images.

Parameters:

images (ndarray) – An array of shape (N, H, W) containing the images to shift.
shifts (ndarray) – An array of shape (N, 2) giving the shifts in pixels.
strictly_preserve_zeros (bool) – If True, a mask of strictly zero pixels will be generated and shifted by the same amount. Pixels that have a non-zero value in the shifted mask will be set to zero in the shifted image. This preserves the zero pixels in the original image, preventing FFT from introducing small non-zero values due to machine precision.

Returns:

Shifted images of the same shape as images.

Return type:

ndarray

ptychozoon.patches.batch_slice(image, sy, sx, patch_size)

Slice patches from an image at given window positions. The patch size is assumed to be the same for all patches.

Parameters:

image (ndarray) – A (H, W) array of the image.
sy (ndarray) – A (N,) array of integers giving the starting y-coordinates of the patches.
sx (ndarray) – A (N,) array of integers giving the starting x-coordinates of the patches.
patch_size (tuple of int) – A tuple giving the patch shape in pixels.

Returns:

An array of shape (N, h, w) containing the extracted patches.

Return type:

ndarray

ptychozoon.patches.place_patches_fourier_shift(image, positions, patches, op='add', adjoint_mode=True, pad=1)

Place patches into a 2D array. If a patch’s footprint goes outside the image, the image is padded with zeros to account for the missing pixels.

Parameters:

image (ndarray) – The whole image.
positions (ndarray) – An array of shape (N, 2) giving the center positions of the patches in pixels. The origin of the given positions are assumed to be the TOP LEFT corner of the image.
patches (ndarray) – A (N, H, W) or (H, W) array of image patches.
op (Literal["add", "set"]) – The operation to perform. "add" adds the patches to the image, "set" replaces the existing values with the patch values.
adjoint_mode (bool) – If True, this function performs the exact adjoint operation of extract_patches_fourier_shift(). It runs the adjoint of every extraction step in reverse order: zero-pads the patches, shifts them back, and places them into the image. Use this when backpropagating gradients. Note that the zero-padding can introduce ripple artifacts around patch borders, so set this to False when placing non-gradient patches; in that case the patches are cropped after shifting to remove Fourier wrap-around.
pad (Optional[int]) – If given, patches are padded (or cropped) by this amount before shifting. When adjoint_mode is True the patches are zero-padded; otherwise they are cropped after shifting to remove wrap-around.

Returns:

An array with the same shape as image with patches added or set.

Return type:

ndarray

ptychozoon.patches.batch_put(image, patches, sy, sx, op='add')

Place patches into an array at given window positions. The patch size is assumed to be the same for all patches.

Parameters:

image (ndarray) – A (H, W) array acting as the buffer to place the patches into.
patches (ndarray) – A (N, h, w) array of the patches to place.
sy (ndarray) – A (N,) array of integers giving the starting y-coordinates of the patches.
sx (ndarray) – A (N,) array of integers giving the starting x-coordinates of the patches.
op (Literal["add", "set"]) – The operation to perform. "add" adds the patches to the image, "set" replaces the existing values with the patch values.

Returns:

An array of shape (H, W) containing the image with patches added or set.

Return type:

ndarray

ptychozoon.patches.get_scipy_module(array)[source]

Return the appropriate SciPy module for the given array type.

Selects cupyx.scipy when array is a CuPy array, and scipy for NumPy arrays, enabling array-module-agnostic code.

Parameters:: array (ndarray) – Array whose module determines the SciPy variant returned.
Returns:: cupyx.scipy for CuPy arrays, scipy for NumPy arrays.
Return type:: module

class ptychozoon.patches.BilinearArrayPatchInterpolator(array, center_y_px, center_x_px, shape)[source]

Bases: object

Bilinear interpolation for extracting and accumulating array patches.

get_patch()[source]

Interpolate array support to extract patch.

accumulate_patch(patch)[source]

Add patch update to array support.