spacr.point_spread

Calibrated point-spread kernels and reproducible CPU image processing.

Calculated kernels are sampled Gaussian approximations with explicitly supplied FWHM and pixel/voxel spacing, not estimates of a microscope’s optical PSF. Measured kernels retain their supplied centre pixel as the optical origin. Processing uses half-sample symmetric boundaries, independently per channel. Richardson–Lucy uses the transpose of that same boundary operator, including its sensitivity normalization for asymmetric kernels. More iterations may amplify noise; this is not a claim of recovered biological structure.

The original image is never modified. Results are float32 in the input’s intensity units, with no percentile stretch, integer rounding or clipping to 0..1. Kernels, sampling and settings are included in a JSON-safe receipt.

References: https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.fftconvolve.html and https://scikit-image.org/docs/stable/api/skimage.restoration.html#skimage.restoration.richardson_lucy

Exceptions

ProcessingCancelled

A caller cancelled processing; no partial image should be applied.

Classes

PSF	An immutable, normalized kernel whose bytes identify the actual PSF.
PSFResult	Processed float32 image and a JSON-safe processing receipt.

Functions

apply_psf(image, kernel, *, operation, image_sampling_um)	Convolve or Richardson–Lucy deconvolve each channel with a known PSF.
gaussian_psf(*, fwhm_um, sampling_um[, ndim, truncate])	Calculate a sampled Gaussian approximation from declared physical widths.
load_psf(path, *, sampling_um[, cancel])	Read a calibrated measured kernel from NPY or a single TIFF series.
measured_psf(data, *, sampling_um[, source_name])	Normalize a measured 2-D/3-D kernel, preserving its centre as origin.

Module Contents

exception spacr.point_spread.ProcessingCancelled

Bases: RuntimeError

A caller cancelled processing; no partial image should be applied.

Initialize self. See help(type(self)) for accurate signature.

class spacr.point_spread.PSF

An immutable, normalized kernel whose bytes identify the actual PSF.

Parameters:

• shape – odd spatial dimensions, YX or ZYX.

• sampling_um – pixel/voxel spacing in the same axis order, in µm.

• values – C-ordered little-endian float32 normalized kernel bytes.

• source – measured or gaussian approximation.

• details_json – JSON object holding acquisition/file or calculation provenance. Use measured_psf(), gaussian_psf() or load_psf() to construct a kernel from ordinary arrays/files.

array()

Return a read-only float32 view of the normalized kernel.

provenance()

Return a fresh JSON-safe record of the kernel and its identity.

class spacr.point_spread.PSFResult

Bases: NamedTuple

Processed float32 image and a JSON-safe processing receipt.

Parameters:

• image – processed image with the input’s spatial shape, as float32.

• provenance – JSON-safe kernel and processing settings for this result.

spacr.point_spread.apply_psf(image, kernel, *, operation, image_sampling_um, iterations=20, channel_axis=None, cancel=None, progress: Callable | None = None)

Convolve or Richardson–Lucy deconvolve each channel with a known PSF.

Parameters:

• image – finite nonnegative real YX/ZYX data, optionally with one explicitly identified channel axis. Input pixels are never changed.

• kernel – calibrated immutable PSF.

• operation – convolve (blur) or deconvolve (Richardson–Lucy).

• image_sampling_um – image spacing matching kernel spacing in spatial axis order. Mismatches raise; no implicit kernel resampling is done.

• iterations – deconvolution iterations, integer 1..200, default20.

• channel_axis – None for a spatial image, otherwise the channel axis; channels are processed independently and returned in their original order.

• cancel – callable or Event; checked between channels, convolutions and iterations. Cancellation raises ProcessingCancelled.

• progress – optional worker-thread callback(channel, completed, total), with zero-based channel and one-based completed iteration.

Returns:

PSFResult, float32 image in original intensity units and provenance. Half-sample symmetric boundaries do not wrap opposite edges. Richardson–Lucy assumes nonnegative Poisson-like intensities; it is unregularized and can amplify noise. Output is not clipped to the input range. Dimensionality/channel identity are preserved.

spacr.point_spread.gaussian_psf(*, fwhm_um, sampling_um, ndim=2, truncate=4.0)

Calculate a sampled Gaussian approximation from declared physical widths.

Parameters:

• fwhm_um – full width at half maximum per spatial axis, or one value.

• sampling_um – pixel/voxel spacing per axis in µm, or one value.

• ndim – two (YX) or three (ZYX) spatial dimensions.

• truncate – radius in standard deviations, between two and eight.

Returns:

normalized PSF. Sigma is FWHM/sqrt(8*ln(2)); radius is ceil(truncate*sigma/sampling). No optical parameters are inferred.

spacr.point_spread.load_psf(path, *, sampling_um, cancel=None)

Read a calibrated measured kernel from NPY or a single TIFF series.

Parameters:

• path – .npy, .tif or .tiff file, at most 64 MiB. Pickled/object arrays, RGB/channel axes, multiple TIFF series and even axes are rejected. TIFF YX/ZYX (or a plane stack) is supported.

• sampling_um – explicitly supplied measured kernel spacing in µm; TIFF metadata is not silently assumed to describe the target image.

• cancel – optional callable or threading.Event checked around reads.

Returns:

immutable PSF, including SHA-256 of the exact file bytes decoded. Subsequent edits to the source file do not change this PSF.

spacr.point_spread.measured_psf(data, *, sampling_um, source_name='array')

Normalize a measured 2-D/3-D kernel, preserving its centre as origin.

Parameters:

• data – real nonnegative kernel with positive signal and odd axes. Background must already be removed; negative values are rejected.

• sampling_um – calibrated YX or ZYX spacing in µm, or one isotropic spacing. Sampling must match the image when processing it.

• source_name – acquisition identifier retained in provenance.

Returns:

immutable normalized PSF; input data stay unchanged.