vista.algorithms.background_removal.static_subspace_background_removal.static_subspace_background_removal

vista.algorithms.background_removal.static_subspace_background_removal.static_subspace_background_removal(background_images, target_images, rank=5, tile_size=None, callback=None)[source]

Remove background from target imagery using a fixed low-rank subspace modeled from a separate set of background frames.

A truncated SVD of background_images defines the low-rank background subspace, and each target frame is projected onto that subspace to estimate its background contribution.

When tile_size is provided, each frame is divided into non-overlapping square tiles that are processed independently, reducing the per-SVD matrix size.

Parameters:

  • background_images (numpy.ndarray) – 3D array of shape (num_background_frames, height, width) used to model the background. Typically frames without transient events.

  • target_images (numpy.ndarray) – 3D array of shape (num_target_frames, height, width) to which the background removal is applied. Must share height and width with background_images.

  • rank (int or None, optional) – Number of singular values to retain for the background subspace, by default 5. If None, automatically selected via knee detection.

  • tile_size (int or None, optional) – Size of square tiles for processing, by default None (no tiling). When provided, images are divided into tile_size x tile_size tiles and each tile is processed independently. Recommended values: 32, 64, or 128.

  • callback (callable, optional) – Called after each target frame with (frame_processed, total_frames). Should return False to cancel processing.

Returns:

(background, foreground) arrays with the shape and dtype of target_images.

Return type:

tuple of (numpy.ndarray, numpy.ndarray)

Raises:

  • InterruptedError – If the callback returns False (user cancellation).

  • ValueError – If the height/width of background_images and target_images do not match, or if background_images is empty.