propagation

byotrack.implementation.refiner.propagation.forward_backward_propagation(tracks_matrix: Tensor, method: str | Callable[[...], Tensor], **kwargs) → Tensor

Fill all NaN values in the tracks matrix by merging a forward and backward propagation

Esimate missing positions for any defined track and frame. First it computes forward estimations, then backward ones. If estimations overlap (for instance with missing positions inside a track), it will merge smoothly the estimations.

We provide two implementations for directed propagation: Constant where we propagate the last known position of the track TPS where we use ThinPlateSpline using the active tracks to estimate the motion of other tracks

Parameters:

• tracks_matrix (torch.Tensor) – Tracks data in a single tensor (See Track.tensorize) Shape: (T, N, D), dtype: float32

• method (str | Callable[..., torch.Tensor]) – Method to use for propagation. Either “tps”, “constant” of a self defined function to be called.

• **kwargs (Any) – Additional arguments given to the method

Returns:

Extrapolated point for each track and time

Shape: (T, N, D), dtype: float32

Return type:

torch.Tensor

byotrack.implementation.refiner.propagation.merge(tracks_matrix: Tensor, forward_positions: Tensor, backward_positions: Tensor) → Tensor

Merge forward and backward propagation into a single propagation matrix

If both propagation defines a position estimation, a weighted average is performed.

Parameters:

• tracks_matrix (torch.Tensor) – Original tracks data (Track.tensorize) Shape: (T, N, D), dtype: float32

• forward_positions (torch.Tensor) – Forward estimation of positions Shape: (T, N, D), dtype: float32

• backward_positions (torch.Tensor) – backward estimation of positions Shape: (T, N, D), dtype: float32

Returns:

Merged propagation matrix

Shape: (T, N, D), dtype: float32

Return type:

torch.tensor

byotrack.implementation.refiner.propagation.constant_directed_propagate(tracks_matrix: Tensor, forward=True) → Tensor

Propagate tracks matrix with the last known position in a single direction

Parameters:

• tracks_matrix (torch.Tensor) – Tracks data in a single tensor (See Tracks.tensorize) Shape: (T, N, D), dtype: float32

• forward (bool) – Forward or backward propagation Default: True (Forward)

Returns:

Estimation of tracks point in a single direction

Shape: (T, N, D), dtype: float32

Return type:

torch.Tensor

byotrack.implementation.refiner.propagation.tps_directed_propagate(tracks_matrix: Tensor, forward=True, alpha=5.0, track_mask: Tensor | None = None) → Tensor

Propagate tracks matrix using Thin Plate Spline (TPS) algorithm in a single direction

Note

We use torch-tps which is very fast but not very accurate. For instance, shuflling the tracks may yield different results (<1px deviation). We have not noticed any real impact on EMC2 stitching performances. Alpha > 5.0 is advised (reduces the numerical errors + outliers resilience).

Parameters:

• tracks_matrix (torch.Tensor) – Tracks data in a single tensor (See Tracks.tensorize) Shape: (T, N, D), dtype: float32

• forward (bool) – Forward or backward propagation Default: True (Forward)

• alpha (float) – Regularization parameter of TPS Default: 5.0 (alpha > 5.0 is advised)

• track_mask (Optional[torch.Tensor]) – Filter out some tracks to build control points Allow to drop uncertain tracks or to simulate propagation with less particles Shape: (N, ), dtype: bool

Returns:

Estimation of tracks point in a single direction

Shape: (T, N, D), dtype: float32

Return type:

torch.Tensor