smlmlp.detect_spatial_maxima module

smlmlp.detect_spatial_maxima(snrs, /, snr_thresh, channels_spatial_kernels, *, f0=0, channels_pixels_nm=1.0, cuda=False, parallel=False)[source]

Detect local spatial maxima in thresholded SNR images.

This function detects local maxima in SNR stacks using a channel-specific spatial footprint derived from the provided kernels. Detected maxima are refined to subpixel coordinates through a local center-of-mass estimate, then converted to physical units using the channel pixel sizes.

Parameters:

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

  • snr_thresh (float) – Detection threshold applied to the SNR values.

  • channels_spatial_kernels (sequence of ndarray) – Spatial kernels used to define the local-maxima footprint for each channel.

  • f0 (int, optional) – Frame offset added to the detected frame indices before converting them back to the 1-based convention.

  • 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 GPU acceleration.

  • parallel (bool, optional) – Whether to enable CPU parallelization.

Returns:

A tuple (fr, x, y, ch, info) where:

  • fr is the concatenated array of detected frame indices,

  • x is the concatenated array of detected x coordinates in nanometers,

  • y is the concatenated array of detected y coordinates in nanometers,

  • ch is the concatenated array of detected channel indices,

  • info is a dictionary containing reusable intermediate results.

The dictionary contains the following keys:

'footprints'

Boolean detection footprints derived from the spatial kernels.

'channels_pixels_nm'

Normalized per-channel pixel sizes used for coordinate conversion.

Return type:

tuple

Notes

The footprint is obtained by thresholding each spatial kernel using the Sparrow-limit-based factor:

\[\exp\left(-\frac{(0.47 / 0.21)^2}{2}\right)\]

On CPU, local maxima are first detected on the integer grid and then refined with a 5x5 center-of-mass estimate. On GPU, both operations are combined in a single kernel.

Examples

>>> import numpy as np
>>> snr = np.random.rand(5, 16, 16).astype(np.float32)
>>> kernel = np.ones((3, 3), dtype=np.float32)
>>> fr, x, y, ch, info = detect_spatial_maxima(
...     [snr],
...     0.9,
...     [kernel],
... )
>>> fr.ndim == x.ndim == y.ndim == ch.ndim == 1
True
>>> "footprints" in info
True

>>> snrs = [
...     np.random.rand(4, 16, 16).astype(np.float32),
...     np.random.rand(4, 16, 16).astype(np.float32),
... ]
>>> kernels = [
...     np.ones((3, 3), dtype=np.float32),
...     np.ones((5, 5), dtype=np.float32),
... ]
>>> fr, x, y, ch, info = detect_spatial_maxima(
...     snrs,
...     1.2,
...     kernels,
...     channels_pixels_nm=[(100.0, 100.0), (110.0, 110.0)],
... )
>>> len(info["footprints"])
2