smlmlp.blink_spatial_psf module

smlmlp.blink_spatial_psf(channels, /, crop_pix=41, *, channels_pixels_nm=100.0, cuda=False, parallel=False)

Estimate a global PSF for each channel from spatial autocorrelations.

This function computes, for each channel, a mean spatial autocorrelation, derives a PSF image from it, fits a 2D Gaussian model, and builds a 2D spline representation of the normalized PSF.

The returned info dictionary gathers the main intermediate results for each channel, including the autocorrelation, PSF, Gaussian fit, spline reconstruction, and fitted parameters.

Parameters:

• channels (sequence of ndarray) – Sequence of image stacks, one per channel. Each channel is expected to have shape (n_frames, height, width).

• crop_pix (int, optional) – Size of the square crop used around the autocorrelation center. The effective crop shape is (crop_pix, crop_pix).

• channels_pixels_nm (float or sequence, optional) – Pixel size in nanometers for each channel. This value is normalized through smlmlp.Config so that one pixel size pair is available for each channel.

• cuda (bool, optional) – Whether to use CUDA-enabled array operations when supported.

• parallel (bool, optional) – Whether to enable parallel execution in the backend functions.

Returns:

A tuple (psf_sigma, info) where:

• psf_sigma is a list containing one effective PSF width per channel, computed as sqrt(sigx * sigy),

• info is a dictionary containing the main intermediate results.

The dictionary contains the following keys:

'ac'

Mean cropped autocorrelation image for each channel.

'psf'

Normalized PSF image for each channel.

'fit'

Normalized Gaussian fit image for each channel.

'spline'

Spline-interpolated PSF image for each channel.

'sigx'

Fitted Gaussian sigma along x, in nanometers.

'sigy'

Fitted Gaussian sigma along y, in nanometers.

'theta'

Fitted Gaussian rotation angle, in degrees.

'tx'

Spline knot positions along x.

'ty'

Spline knot positions along y.

'coeffs'

Spline coefficients.

Return type:

tuple

Notes

The PSF image is computed from the autocorrelation using:

\[\mathrm{PSF} = \mathcal{F}^{-1}\left(\sqrt{|\mathcal{F}(AC)|}\right)\]

followed by centering, real-part extraction, and normalization.

The Gaussian fit is performed away from the central row and column intersection defined by the initial mask (Y != 0) & (X != 0).

Examples

Estimate the PSF for one channel:

>>> import numpy as np
>>> channel = np.random.rand(20, 64, 64).astype(np.float32)
>>> psf_sigma, info = blink_spatial_psf([channel], crop_pix=41)
>>> len(psf_sigma)
1
>>> sorted(info.keys())
['ac', 'coeffs', 'fit', 'psf', 'sigx', 'sigy', 'spline', 'theta', 'tx', 'ty']

Estimate the PSF for multiple channels with different pixel sizes:

>>> channels = [
...     np.random.rand(20, 64, 64).astype(np.float32),
...     np.random.rand(20, 64, 64).astype(np.float32),
... ]
>>> psf_sigma, info = blink_spatial_psf(
...     channels,
...     crop_pix=31,
...     channels_pixels_nm=[(100.0, 100.0), (110.0, 110.0)],
... )
>>> len(info["psf"])
2
>>> len(info["sigx"])
2