vista.algorithms.background_removal.subspace_background_removal.subspace_background_removal

vista.algorithms.background_removal.subspace_background_removal.subspace_background_removal(images, rank=5, window_size=25, gap_size=3, tile_size=None, callback=None)[source]

Remove background from imagery using a sliding-window low-rank SVD approach.

For each frame t, background reference frames are selected from a symmetric window around t, excluding frames within a gap of +/- gap_size. A truncated SVD of the reference frames captures the low-rank background subspace, and the current frame is projected onto it to estimate the background.

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:

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

  • rank (int or None, optional) – Number of singular values to retain for the background subspace, by default 5. Higher values capture more complex backgrounds but may include target signal. If None, automatically selected via knee detection per frame.

  • window_size (int, optional) – Number of reference frames to use on each side of the current frame, by default 25. Total potential reference frames = 2 * window_size (minus those in the gap).

  • gap_size (int, optional) – Number of frames to exclude on each side of the current frame, by default 3. Prevents target signal near frame t from leaking into the background estimate.

  • 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 frame with (frame_processed, total_frames). Should return False to cancel processing.

Returns:

(background, foreground) with the same shape and dtype as input.

Return type:

tuple of (numpy.ndarray, numpy.ndarray)

Raises:

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