vista.algorithms.background_removal.godec.godec

vista.algorithms.background_removal.godec.godec(images, rank=5, sparsity=0.01, max_iter=10, power_iters=2, callback=None, frame_block_size=None, block_overlap_frames=0)[source]

Remove background from imagery using GoDec (Go Decomposition).

Decomposes the data matrix M into L + S + G where:

  • L is the low-rank component (background)

  • S is the sparse component (foreground / targets)

  • G is the residual noise (implicit: G = M - L - S)

The algorithm alternates between computing a low-rank approximation of (M - S) via randomized SVD and extracting the sparse foreground via hard thresholding of (M - L). All operations are dominated by large matrix multiplications, making this algorithm naturally suited for GPU acceleration.

Parameters:

  • images (torch.Tensor) – 3D tensor of shape (num_frames, height, width) with dtype float32. Can be on CPU or GPU.

  • rank (int or None, optional) – Rank of the low-rank background component, by default 5. Higher values capture more complex backgrounds. If None, automatically selected via knee detection on singular values.

  • sparsity (float, optional) – Fraction of entries in the sparse foreground component, by default 0.01. Higher values allow more foreground content. Range: 0.0 to 1.0.

  • max_iter (int, optional) – Maximum number of GoDec iterations, by default 10. Convergence is typically reached within 5-10 iterations.

  • power_iters (int, optional) – Number of power iterations in randomized SVD, by default 2. More iterations improve numerical accuracy at moderate cost.

  • callback (callable, optional) – Called after each iteration with (iteration, max_iter). Should return False to cancel processing.

  • frame_block_size (int or None, optional) – When set, the imagery is split into blocks of this many frames and GoDec is run on each block independently. Results are combined by splitting overlapping regions at their midpoint. By default None (process all frames at once).

  • block_overlap_frames (int, optional) – Number of frames of overlap between consecutive blocks, by default 0. Must be less than frame_block_size. Overlapping regions are split at their midpoint when combining block results.

Returns:

(background, foreground) both on the same device as input, with the same shape (num_frames, height, width) and dtype float32.

Return type:

tuple of (torch.Tensor, torch.Tensor)

Raises:

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