vista.algorithms.detectors.pstnn.PSTNN

class vista.algorithms.detectors.pstnn.PSTNN(patch_size=40, stride=40, lambda_param=None, convergence_tolerance=1e-07, max_iterations=50, n_skipped_singular_values=1, min_area=1, max_area=1000, use_gpu=False, threshold_multiplier=5.0, detection_mode='both')[source]

Partial Sum of Tensor Nuclear Norm detector for small target detection.

Decomposes a temporal image sequence into a low-rank background component and a sparse target component using ADMM optimization on patch-tensors. The sparse component is then thresholded and connected blobs are detected as targets with weighted centroid positions.

Parameters:

  • patch_size (int) – Height and width of patches for tensor construction (pixels)

  • stride (int) – Stride between patches. Equal to patch_size for non-overlapping patches.

  • lambda_param (float or None) – Sparsity weight controlling background vs target trade-off. Smaller values produce sparser (cleaner) target components. If None, automatically computed as 1 / sqrt(max(n1, n2) * n3) where n1, n2, n3 are the tensor dimensions.

  • convergence_tolerance (float) – ADMM convergence threshold on relative change in the Frobenius norm of D - B - T

  • max_iterations (int) – Maximum number of ADMM iterations

  • n_skipped_singular_values (int) – Number of top singular values to preserve (not penalize) in the partial nuclear norm. These correspond to dominant background structure.

  • min_area (int) – Minimum blob area in pixels for detection filtering

  • max_area (int) – Maximum blob area in pixels for detection filtering

  • use_gpu (bool) – Whether to use GPU (PyTorch CUDA) for SVD operations

  • threshold_multiplier (float) – Number of standard deviations above the mean of the absolute sparse component for adaptive thresholding during blob detection

  • detection_mode (str) – Type of targets to detect in the sparse component: - ‘bright’: Detect bright targets (positive sparse values exceeding threshold) - ‘dark’: Detect dark targets (negative sparse values exceeding threshold) - ‘both’: Detect both bright and dark targets (absolute deviation exceeding threshold)

name

Algorithm name (“PSTNN”)

Type:

str

Examples

>>> from vista.algorithms.detectors.pstnn import PSTNN
>>> pstnn = PSTNN(patch_size=40, stride=40, max_iterations=50)
>>> # Decompose multi-frame imagery (frames x height x width)
>>> sparse_targets = pstnn.decompose(images)
>>> # Detect blobs in a single sparse target frame
>>> rows, columns = pstnn.detect(sparse_targets[0])
__init__(patch_size=40, stride=40, lambda_param=None, convergence_tolerance=1e-07, max_iterations=50, n_skipped_singular_values=1, min_area=1, max_area=1000, use_gpu=False, threshold_multiplier=5.0, detection_mode='both')[source]

Methods

__init__([patch_size, stride, lambda_param, ...])

decompose(images[, callback])

Decompose a multi-frame image sequence into sparse target images.

detect(target_image)

Detect blobs in a single sparse target image and return weighted centroids.

Attributes

name

name = 'PSTNN'
__init__(patch_size=40, stride=40, lambda_param=None, convergence_tolerance=1e-07, max_iterations=50, n_skipped_singular_values=1, min_area=1, max_area=1000, use_gpu=False, threshold_multiplier=5.0, detection_mode='both')[source]
decompose(images, callback=None)[source]

Decompose a multi-frame image sequence into sparse target images.

Parameters:

  • images (ndarray) – 3D array of shape (num_frames, height, width) with float32 values

  • callback (callable, optional) – Function called after each ADMM iteration with signature callback(iteration, max_iterations) returning False to cancel

Returns:

3D array of shape (num_frames, height, width) containing the sparse target component for each frame

Return type:

ndarray

detect(target_image)[source]

Detect blobs in a single sparse target image and return weighted centroids.

Parameters:

target_image (ndarray) – 2D sparse target image from the decomposition step

Returns:

  • rows (ndarray) – Array of detection centroid row coordinates (float64)

  • columns (ndarray) – Array of detection centroid column coordinates (float64)

Return type:

tuple