track

sleap_nn.tracking.mot.track

Track state for the MOT trackers.

Classes:

Name	Description
MOTTrack	One track of a MOT tracker.
TrackState	Lifecycle state of a :class:MOTTrack.

MOTTrack

One track of a MOT tracker.

Attributes:

Name	Type	Description
tid	int	Internal id, unique within one tracker instance.
state	TrackState	Lifecycle state.
mean	ndarray	Kalman state mean.
cov	ndarray	Kalman state covariance.
hits	int	Total matches (hits_start at spawn).
hit_streak	int	Consecutive steps with a match.
age	int	Steps since spawn.
time_since_update	int	Steps since the last match.
start_frame	int	Frame index of the first detection.
last_frame	int	Frame index of the latest matched detection.
step	int	The tracker's step counter at the latest match.
last_box	ndarray	Latest observed padded xyxy box.
last_raw_box	ndarray	Latest observed unpadded extent.
last_keypoints	Optional[ndarray]	Latest observed keypoints (pose carrier) or None.
kf_center_at_update	ndarray	Kalman posterior center right after the latest update; the predicted pose is last_keypoints + (predicted center - kf_center_at_update) so both terms use the same reference point.
last_score	float	Latest matched detection score.
observations	Dict[int, ndarray]	OC-SORT observation history {step: xyxy} (bounded; kept only by trackers with keeps_observation_history).
last_observation	Optional[ndarray]	Latest observed xyxy (spawn excluded), or None.
velocity	Optional[ndarray]	OC-SORT unit velocity direction (dy, dx) or None (keeps_observation_history trackers only).
frozen	Optional[Tuple[ndarray, ndarray, int]]	OC-SORT state saved at the first miss (mean, cov, step) or None.
appearance	Optional[AppearanceMemory]	Appearance memory (appearance-using trackers) or None.
members	List[Tuple[int, Any, float]]	(frame_idx, source_object, similarity) of the detections assigned while the track is tentative, labeled retroactively when it confirms (then emptied: later detections are labeled as matched).
public_id	Optional[int]	Public id (sio.Track key) once confirmed, else None.

Source code in sleap_nn/tracking/mot/track.py

@attrs.define(eq=False)
class MOTTrack:
    """One track of a MOT tracker.

    Attributes:
        tid: Internal id, unique within one tracker instance.
        state: Lifecycle state.
        mean: Kalman state mean.
        cov: Kalman state covariance.
        hits: Total matches (``hits_start`` at spawn).
        hit_streak: Consecutive steps with a match.
        age: Steps since spawn.
        time_since_update: Steps since the last match.
        start_frame: Frame index of the first detection.
        last_frame: Frame index of the latest matched detection.
        step: The tracker's step counter at the latest match.
        last_box: Latest observed padded ``xyxy`` box.
        last_raw_box: Latest observed unpadded extent.
        last_keypoints: Latest observed keypoints (pose carrier) or ``None``.
        kf_center_at_update: Kalman posterior center right after the latest
            update; the predicted pose is ``last_keypoints + (predicted center -
            kf_center_at_update)`` so both terms use the same reference point.
        last_score: Latest matched detection score.
        observations: OC-SORT observation history ``{step: xyxy}`` (bounded;
            kept only by trackers with ``keeps_observation_history``).
        last_observation: Latest observed ``xyxy`` (spawn excluded), or ``None``.
        velocity: OC-SORT unit velocity direction ``(dy, dx)`` or ``None``
            (``keeps_observation_history`` trackers only).
        frozen: OC-SORT state saved at the first miss ``(mean, cov, step)`` or
            ``None``.
        appearance: Appearance memory (appearance-using trackers) or ``None``.
        members: ``(frame_idx, source_object, similarity)`` of the detections
            assigned while the track is tentative, labeled retroactively when it
            confirms (then emptied: later detections are labeled as matched).
        public_id: Public id (``sio.Track`` key) once confirmed, else ``None``.
    """

    tid: int
    state: TrackState
    mean: np.ndarray
    cov: np.ndarray
    start_frame: int
    last_frame: int
    step: int
    last_box: np.ndarray
    last_raw_box: np.ndarray
    kf_center_at_update: np.ndarray
    last_keypoints: Optional[np.ndarray] = None
    last_score: float = 1.0
    hits: int = 1
    hit_streak: int = 1
    age: int = 0
    time_since_update: int = 0
    observations: Dict[int, np.ndarray] = attrs.field(factory=dict)
    last_observation: Optional[np.ndarray] = None
    velocity: Optional[np.ndarray] = None
    frozen: Optional[Tuple[np.ndarray, np.ndarray, int]] = None
    appearance: Optional[AppearanceMemory] = None
    members: List[Tuple[int, Any, float]] = attrs.field(factory=list)
    public_id: Optional[int] = None

    @property
    def is_live(self) -> bool:
        """Whether the track can still be matched (not removed)."""
        return self.state != TrackState.REMOVED

is_live property

Whether the track can still be matched (not removed).

TrackState

Bases: IntEnum

Lifecycle state of a :class:MOTTrack.

TENTATIVE tracks are not yet confirmed (fewer than min_hits matches); CONFIRMED tracks were matched at the latest step; LOST tracks are confirmed but currently unmatched (kept for re-association for track_buffer steps); REMOVED tracks are finished.

Source code in sleap_nn/tracking/mot/track.py

class TrackState(enum.IntEnum):
    """Lifecycle state of a :class:`MOTTrack`.

    ``TENTATIVE`` tracks are not yet confirmed (fewer than ``min_hits``
    matches); ``CONFIRMED`` tracks were matched at the latest step; ``LOST``
    tracks are confirmed but currently unmatched (kept for re-association for
    ``track_buffer`` steps); ``REMOVED`` tracks are finished.
    """

    TENTATIVE = 0
    CONFIRMED = 1
    LOST = 2
    REMOVED = 3