smlmlp.globdet_channels module

smlmlp.globdet_channels(channels, /, globdet_mode='mean', channels_x_shifts_nm=None, channels_y_shifts_nm=None, channels_rotations_deg=None, channels_x_shears=None, channels_y_shears=None, globdet_groups=None, global_channels=None, *, channels_pixels_nm=1.0, channels_gains=0.25, cuda=False, parallel=False)[source]

Create a global channel for detection.

This function geometrically transforms each input channel stack into the global detection frame, then merges all transformed channels into a single channel stack using either a mean or standard deviation projection across channels.

Parameters:

  • channels (sequence of ndarray) – Input channel stacks.

  • globdet_mode ({"mean", "std"}, optional) – Aggregation used to merge transformed channels.

  • channels_x_shifts_nm (sequence of float or None, optional) – Per-channel translations in nanometers. If None, zeros are used.

  • channels_y_shifts_nm (sequence of float or None, optional) – Per-channel translations in nanometers. If None, zeros are used.

  • channels_rotations_deg (sequence of float or None, optional) – Per-channel rotations, in degrees. If None, zeros are used.

  • channels_x_shears (sequence of float or None, optional) – Per-channel shear values. If None, zeros are used.

  • channels_y_shears (sequence of float or None, optional) – Per-channel shear values. If None, zeros are used.

  • globdet_groups (sequence of sequence of int or None, optional) – Group definition for merged output channels. Each group contains input channel indices. A group index can be 0-based or 1-based. If None, all channels are merged into one output channel.

  • global_channels (sequence of ndarray or None, optional) – Optional preallocated output list for merged output channels. If provided with larger arrays, centered spatial views are reused when possible.

  • channels_pixels_nm (float or sequence, optional) – Pixel size in nanometers. Can be scalar, (y, x), or per-channel.

  • channels_gains (float or sequence, optional) – Per-channel gains in e-/ADU. Input channels are converted to photons before merging and the merged global channel is converted back to ADU using the average gain.

  • cuda (bool, optional) – Whether to use CUDA execution.

  • parallel (bool, optional) – Whether to use parallel execution.

Returns:

A tuple (new_channels, info) where:

  • new_channels is a list containing one merged channel per group,

  • info is a dictionary containing reusable intermediate results.

The dictionary contains the following keys:

'channels_pixels_nm'

Normalized per-channel pixel sizes.

'ref_pix'

Reference pixel size used for the common scaling.

'scales_x'

Per-channel x scaling factors.

'scales_y'

Per-channel y scaling factors.

'channels_x_shifts_nm'

Normalized per-channel x translations.

'channels_y_shifts_nm'

Normalized per-channel y translations.

'channels_rotations_deg'

Normalized per-channel rotations.

'channels_x_shears'

Normalized per-channel x shears.

'channels_y_shears'

Normalized per-channel y shears.

'transform_matrices'

Transform matrices applied to each input channel.

'crop_shape'

Common centered crop shape applied after transformation.

'crop_bboxes'

Per-channel centered crop boxes as (x0, y0, x1, y1).

Return type:

tuple

Raises:

  • ValueError – If no channel is provided or if a per-channel parameter length does not match len(channels).

  • SyntaxError – If mode is not recognized.

Examples

>>> import numpy as np
>>> channels = [
...     np.ones((2, 4, 4), dtype=np.float32),
...     np.ones((2, 4, 4), dtype=np.float32) * 3,
... ]
>>> global_channels, info = globdet_channels(channels)
>>> len(global_channels)
1
>>> global_channels[0].shape
(2, 4, 4)

>>> global_channels, info = globdet_channels(channels, mode="std")
>>> np.allclose(global_channels[0], 1.0)
True