Image & Signal Filters#

The massphoto.filter module provides spatial and temporal filters for image and movie processing, used as building blocks for candidate event detection and background estimation.

massphoto.filter.correlation_map(movie, kern=None, kern_params=None, kern_hsize=6)[source]#

Calculate spatial correlation maps between a movie and a 2D PSF template.

Parameters:

  • movie (np.ndarray) – Input 2D image or 3D movie array (frames, y, x).

  • kern (np.ndarray | Callable | None, default=None) – 2D PSF kernel array or a callable generating the kernel. If None, the default empirical PSF model is used.

  • kern_params (dict | None, default=None) – Parameters passed to kern if it is callable.

  • kern_hsize (int, default=6) – Half-size (in pixels) of the kernel box when generated from a callable. The full kernel size is 2 * kern_hsize + 1.

Returns:

A tuple of (norm_corr_map, corr_map): - norm_corr_map: Normalized cross-correlation map (Pearson correlation in each local window). - corr_map: Unnormalized cross-correlation map scaled by the kernel energy.

Both arrays preserve NaN locations from the input movie. Frames containing only invalid values remain NaN.

Return type:

tuple[np.ndarray, np.ndarray]

Raises:

ValueError – If kern is neither a NumPy array, a callable, nor None.

massphoto.filter.step_correlation(img, navg=20, ngap=1, median_filter_size=0, axis=0)[source]#

Normalised step-correlation (Pearson-style NCC) along time axis (axis 0).

For each time index t, compute trailing-window means/variances (length n = navg) on the two sides of a potential step, separated by ngap masked frames:

mean_after(t), var_after(t) - window after the step mean_before(t), var_before(t) - window before the step

Correlation with a ±1 step template [-1,…, -1, +1,…, +1] (length 2n, mean 0) reduces to:

r(t) = (mean_after - mean_before) /

sqrt( (mean_after - mean_before)**2 + 2 * ( var_after + var_before ) )

With this sign convention, an up-step (low->high) gives +1 for an ideal noiseless step, and a down-step gives -1. Edges where windows are invalid are set to NaN.

Parameters:

  • img (np.ndarray) – Movie array with time on axis 0 (shape [T, …]).

  • navg (int, default=20) – Number of frames averaged on each side of the step.

  • ngap (int, default=1) – Number of masked frames between the two averaging windows.

  • median_filter_size (int, default=0) – Optional spatial median filter kernel size applied to each frame before temporal correlation. Set to 0 to disable.

  • axis (int, default=0) – Axis along which to compute the step-correlation. Default is 0 (time axis).

Returns:

Step-correlation array with the same shape as img.

Return type:

np.ndarray

massphoto.filter.gaussian_laplace(movie, sigma=1.5, **kwargs)[source]#

Apply a Gaussian Laplace filter to each image in a movie stack.

Parameters:

  • movie (np.ndarray) – Stack of images represented as a NumPy array. The last two dimensions correspond to height and width (..., y, x).

  • sigma (float, default=1.5) – Standard deviation of the Gaussian kernel.

  • **kwargs – Additional keyword arguments passed to scipy.ndimage.gaussian_laplace().

Returns:

Filtered images with the same shape as the input array.

Return type:

np.ndarray

massphoto.filter.symmetry_filter(img, radius=2, alpha=3, beta=0.0)[source]#

Fast radial symmetry transform for detecting rotationally symmetric features.

Parameters:

  • img (np.ndarray) – Input 2D image or n-D image stack (..., y, x).

  • radius (int, default=2) – Feature radius in pixels to detect.

  • alpha (int, default=3) – Radial strictness parameter (higher values select strictly radial symmetry, whereas lower values allow bilateral features).

  • beta (float, default=0.0) – Gradient threshold; gradients below this value do not contribute.

Returns:

Radial symmetry map with the same shape as img.

Return type:

np.ndarray

massphoto.filter.median_filter_sep_nd(img, kernel_size, smoothing=0.0, axes=(-2, -1), pad_mode='constant', subtract_bg=True)[source]#

Apply a separable median filter to an n-dimensional array.

The separable median filter is implemented by applying 1D median filters sequentially along the specified axes of the array.

Parameters:

  • img (np.ndarray) – Input n-dimensional array to be filtered.

  • kernel_size (int) – Size of the median filter kernel.

  • smoothing (float, default=0.0) – Amount of Gaussian smoothing to apply after filtering. Default is 0 (no smoothing).

  • axes (int or tuple of int, default=(-2, -1)) – Axes along which to apply the median filter. Default is the last two axes.

  • pad_mode (str, default='constant') – Padding mode to use for the array. Options are ‘edge’, ‘constant’, ‘reflect’, ‘symmetric’.

  • subtract_bg (bool, default=True) – If True, subtract the background from the filtered image. If False, return the filtered image

Returns:

Filtered array.

Return type:

np.ndarray

massphoto.filter.stack_apply_filter(filter_func, movie, **kwargs)[source]#

Apply a filter function to a stack of images.

The function iterates over all dimensions except the last two (y, x).

Parameters:

  • filter_func (Callable) – Filter function to apply.

  • movie (np.ndarray) – Stack of input images.

  • **kwargs – Additional keyword arguments to pass to the filter function.

Returns:

Stack of filtered images.

Return type:

np.ndarray