Rauch Tung Striebel Smoother

class byotrack.implementation.refiner.smoother.RTSSmoother(detection_std: float | Tensor = 3.0, process_std: float | Tensor = 1.5, kalman_order: int = 1, *, anisotropy: tuple[float, float, float] = (1.0, 1.0, 1.0), initial_std_factor=10.0)

Bases: Refiner

Smooth tracks positions by running the optimal Rauch-Tung-Striebel smoothing.

It will also fill out NaN values in tracks. (Except if a track starts with NaN values, the track will now starts at the first non-NaN value.)

It models the tracks motion and position measurement using a Kalman filter framework (with Gaussian iid noise). In order to have consistent results, the tracks positions should be extracted as the positions of an independent detection process that is not already filtered/smoothed.

See torch_kf and filterpy for more details.

detection_std

Expected measurement noise on the detection process. The detection process is modeled with a Gaussian noise with this given std. (You can provide a different noise for each dimension). See torch_kf.ckf.constant_kalman_filter. Default: 3.0 pixels

Type:

float | torch.Tensor

process_std

Expected process noise. See torch_kf.ckf.constant_kalman_filter, the process is modeled as constant order-th derivative motion. This quantify how much the supposedly “constant” order-th derivative can change between two consecutive frames. A common rule of thumb is to use 3 * process_std ~= max_t(| x^(order)(t) - x^(order)(t+1)|). It can be provided for each dimension). Default: 1.5 pixels / frame^order

Type:

float | torch.Tensor

kalman_order

Order of the Kalman filter to use. 0 for brownian motions, 1 for directed brownian motion, 2 for accelerated brownian motions, etc… Default: 1

Type:

int

anisotropy

Deprecated and ignored. If the data is anisotrope, it should directly be incorporated inside detection_std and process_std. Will be removed in a future version.

Type:

tuple[float, float, float]

initial_std_factor

The initial state is created with an initial uncertainty set to the measurement_std of the Kalman Filter on measured states and this factor times the process_std for unmeasured states. Default: 10.0

Type:

float

run(video: Sequence[np.ndarray] | np.ndarray | None, tracks: Collection[byotrack.Track]) → list[byotrack.Track]

Run the refiner on a whole video.

Parameters:

• video (Sequence[np.ndarray] | np.ndarray | None) – Optional sequence of T frames (array). Each array is expected to have a shape ([D, ]H, W, C). Some refiners may not require any video. In that case, you may provide explicitly None.

• tracks (Collection[byotrack.Track]) – Tracks of particles

Returns:

Refined tracks of particles

Return type:

Collection[byotrack.Track]