Trackers

End-to-end tracking algorithms.

End-to-end tracker implementations.

This module provides complete tracker implementations that combine filtering, data association, and track management.

Single Target Tracking

Single target tracking algorithms.

Single-target tracker implementation.

This module provides a simple single-target tracker using Kalman filtering.

class pytcl.trackers.single_target.SingleTargetTracker(state_dim, meas_dim, F, H, Q, R, gate_threshold=None)[source]

Bases: object

Single-target tracker using Kalman filtering.

This tracker maintains a single track and provides predict/update functionality with optional gating.

Parameters:

state_dim (int) – Dimension of state vector.
meas_dim (int) – Dimension of measurement vector.
F (callable or ndarray) – State transition matrix or function F(dt) -> ndarray.
H (ndarray) – Measurement matrix.
Q (callable or ndarray) – Process noise covariance or function Q(dt) -> ndarray.
R (ndarray) – Measurement noise covariance.
gate_threshold (float, optional) – Chi-squared gate threshold (default: None, no gating).

Examples

>>> import numpy as np
>>> # Constant velocity model in 2D
>>> F = lambda dt: np.array([[1, dt, 0, 0],
...                          [0, 1, 0, 0],
...                          [0, 0, 1, dt],
...                          [0, 0, 0, 1]])
>>> H = np.array([[1, 0, 0, 0],
...               [0, 0, 1, 0]])
>>> Q = lambda dt: 0.1 * np.eye(4)
>>> R = np.eye(2) * 0.5
>>> tracker = SingleTargetTracker(4, 2, F, H, Q, R)
>>> tracker.initialize(np.array([0, 1, 0, 1]), np.eye(4))
>>> predicted = tracker.predict(1.0)
>>> predicted.state
array([1., 1., 1., 1.])
>>> updated = tracker.update(np.array([1.1, 1.2]))

__init__(state_dim, meas_dim, F, H, Q, R, gate_threshold=None)[source]

initialize(state, covariance, time=0.0)[source]

Initialize the tracker with initial state.

Parameters:

state (array_like) – Initial state estimate.
covariance (array_like) – Initial state covariance.
time (float, optional) – Initial time (default: 0).

property is_initialized: bool: Check if tracker is initialized.

property state: TrackState | None: Get current track state.

predict(dt)[source]

Predict state to new time.

Parameters:: dt (float) – Time step.
Returns:: Predicted state.
Return type:: TrackState
Raises:: RuntimeError – If tracker is not initialized.

update(measurement, measurement_covariance=None)[source]

Update state with measurement.

Parameters:

measurement (array_like) – Measurement vector.
measurement_covariance (array_like, optional) –
Covariance for this detection, shape (meas_dim, meas_dim). When omitted the tracker’s fixed R is used.

Supply this when the measurement error varies between detections – a converted polar detection, for instance, has a Cartesian covariance that is anisotropic and grows with range, so no single R describes it. Both the gate and the Kalman gain then use the covariance that actually applies.

Returns:

state (TrackState) – Updated state.
likelihood (float) – Measurement likelihood (Mahalanobis distance).

Raises:

RuntimeError – If tracker is not initialized.
ValueError – If measurement_covariance is not (meas_dim, meas_dim).

Return type:

tuple[TrackState, float]

predict_measurement(measurement_covariance=None)[source]

Predict measurement and innovation covariance.

Parameters:

measurement_covariance (array_like, optional) – Covariance of the detection being considered. Omit to use the tracker’s fixed R.

Returns:

z_pred (ndarray) – Predicted measurement.
S (ndarray) – Innovation covariance.

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]]]

class pytcl.trackers.single_target.TrackState(state, covariance, time)[source]

Bases: NamedTuple

State of a single target track.

Variables:

state (ndarray) – State estimate vector.
covariance (ndarray) – State covariance matrix.
time (float) – Time of state estimate.

state: ndarray[tuple[Any, ...], dtype[float64]]: Alias for field number 0

covariance: ndarray[tuple[Any, ...], dtype[float64]]: Alias for field number 1

time: float: Alias for field number 2

Multi-Target Tracking

Multi-target tracking algorithms including track management.

Multi-target tracker implementation.

This module provides a multi-target tracker using GNN data association and Kalman filtering with track management (initiation, maintenance, deletion).

class pytcl.trackers.multi_target.MultiTargetTracker(state_dim, meas_dim, F, H, Q, R, gate_probability=0.99, confirm_hits=3, confirm_window=5, max_misses=5, init_covariance=None)[source]

Bases: object

Multi-target tracker with GNN data association.

This tracker maintains multiple tracks and handles: - Track initiation from unassociated measurements - Track update via GNN data association - Track confirmation (M-of-N logic) - Track deletion (miss count)

Parameters:

state_dim (int) – Dimension of state vector.
meas_dim (int) – Dimension of measurement vector.
F (callable or ndarray) – State transition matrix or function F(dt) -> ndarray.
H (ndarray) – Measurement matrix.
Q (callable or ndarray) – Process noise covariance or function Q(dt) -> ndarray.
R (ndarray) – Measurement noise covariance.
gate_probability (float, optional) – Gate probability for association (default: 0.99).
confirm_hits (int, optional) – Hits needed to confirm track (default: 3).
confirm_window (int, optional) – Window for M-of-N confirmation (default: 5).
max_misses (int, optional) – Consecutive misses before deletion (default: 5).
init_covariance (ndarray, optional) – Initial covariance for new tracks. If None, uses 100*R projected to state.

Examples

>>> import numpy as np
>>> # Constant velocity model
>>> F = lambda dt: np.array([[1, dt, 0, 0],
...                          [0, 1, 0, 0],
...                          [0, 0, 1, dt],
...                          [0, 0, 0, 1]])
>>> H = np.array([[1, 0, 0, 0],
...               [0, 0, 1, 0]])
>>> Q = lambda dt: 0.1 * np.eye(4)
>>> R = np.eye(2) * 0.5
>>> tracker = MultiTargetTracker(4, 2, F, H, Q, R)
>>> # Process measurements
>>> measurements = [np.array([1, 2]), np.array([5, 6])]
>>> tracks = tracker.process(measurements, dt=1.0)

__init__(state_dim, meas_dim, F, H, Q, R, gate_probability=0.99, confirm_hits=3, confirm_window=5, max_misses=5, init_covariance=None)[source]

property tracks: List[Track]: Get list of active tracks.

property confirmed_tracks: List[Track]: Get list of confirmed tracks only.

process(measurements, dt, measurement_covariances=None)[source]

Process measurements at new time step.

Parameters:

measurements (list of array_like) – List of measurement vectors.
dt (float) – Time step since last update.
measurement_covariances (sequence of array_like, optional) –
Per-detection measurement covariance, one (meas_dim, meas_dim) matrix per entry in measurements. When omitted the tracker’s fixed R is used for every detection.

Supply this when the measurement error is not the same for every detection. The usual case is a converted polar detection: its Cartesian covariance is J R_polar J^T, which is anisotropic and grows with range, so no single R describes it. Forcing one makes the gate either too tight at long range – true detections fall outside it and the tracker spawns duplicate tracks – or too loose at short range, which admits clutter and inflates the covariance.

Returns:

Active tracks after update.

Return type:

list of Track

Raises:

ValueError – If measurement_covariances is given and its length does not match measurements, or a matrix is not (meas_dim, meas_dim).

class pytcl.trackers.multi_target.Track(id, state, covariance, status, hits, misses, time)[source]

Bases: NamedTuple

Multi-target track.

Variables:

id (int) – Unique track identifier.
state (ndarray) – State estimate vector.
covariance (ndarray) – State covariance matrix.
status (TrackStatus) – Track status.
hits (int) – Number of measurement updates.
misses (int) – Number of consecutive missed detections.
time (float) – Time of last update.

id: int: Alias for field number 0

state: ndarray[tuple[Any, ...], dtype[float64]]: Alias for field number 1

covariance: ndarray[tuple[Any, ...], dtype[float64]]: Alias for field number 2

status: TrackStatus: Alias for field number 3

hits: int: Alias for field number 4

misses: int: Alias for field number 5

time: float: Alias for field number 6

class pytcl.trackers.multi_target.TrackStatus(value)[source]

Bases: Enum

Track status enumeration.

TENTATIVE = 'tentative'

CONFIRMED = 'confirmed'

DELETED = 'deleted'

Multiple Hypothesis Tracking (MHT)

Hypothesis-oriented MHT implementation.

Multiple Hypothesis Tracking (MHT) implementation.

MHT maintains multiple hypotheses about measurement-to-track associations, deferring hard decisions until more information is available. This allows the tracker to recover from association errors.

This implementation uses track-oriented MHT with N-scan pruning.

References

S. Blackman and R. Popoli, “Design and Analysis of Modern Tracking Systems,” Artech House, 1999.
D. Reid, “An Algorithm for Tracking Multiple Targets,” IEEE Trans. Automatic Control, 1979.

class pytcl.trackers.mht.MHTConfig(n_scan=3, max_hypotheses=100, detection_prob=0.9, clutter_density=1e-06, gate_probability=0.99, confirm_threshold=3, delete_threshold=5, min_hypothesis_prob=1e-06, new_track_weight=0.1)[source]

Bases: NamedTuple

Configuration for MHT tracker.

Variables:

n_scan (int) – Number of scans for N-scan pruning. Default 3.
max_hypotheses (int) – Maximum number of hypotheses to maintain. Default 100.
detection_prob (float) – Probability of detection (Pd). Default 0.9.
clutter_density (float) – Spatial density of false alarms. Default 1e-6.
gate_probability (float) – Gating probability for chi-squared test. Default 0.99.
confirm_threshold (int) – Number of hits to confirm a track. Default 3.
delete_threshold (int) – Number of consecutive misses to delete a track. Default 5.
min_hypothesis_prob (float) – Minimum hypothesis probability. Default 1e-6.
new_track_weight (float) – Prior weight for new track hypothesis. Default 0.1.

n_scan: int: Alias for field number 0

max_hypotheses: int: Alias for field number 1

detection_prob: float: Alias for field number 2

clutter_density: float: Alias for field number 3

gate_probability: float: Alias for field number 4

confirm_threshold: int: Alias for field number 5

delete_threshold: int: Alias for field number 6

min_hypothesis_prob: float: Alias for field number 7

new_track_weight: float: Alias for field number 8

class pytcl.trackers.mht.MHTResult(confirmed_tracks, tentative_tracks, all_tracks, n_hypotheses, best_hypothesis_prob)[source]

Bases: NamedTuple

Result of MHT processing step.

Variables:

confirmed_tracks (list of MHTTrack) – Tracks that are confirmed.
tentative_tracks (list of MHTTrack) – Tracks that are tentative.
all_tracks (list of MHTTrack) – All active tracks from best hypothesis.
n_hypotheses (int) – Number of active hypotheses.
best_hypothesis_prob (float) – Probability of the best hypothesis.

confirmed_tracks: List[MHTTrack]: Alias for field number 0

tentative_tracks: List[MHTTrack]: Alias for field number 1

all_tracks: List[MHTTrack]: Alias for field number 2

n_hypotheses: int: Alias for field number 3

best_hypothesis_prob: float: Alias for field number 4

class pytcl.trackers.mht.MHTTracker(state_dim, meas_dim, F, H, Q, R, config=None, init_covariance=None)[source]

Bases: object

Multiple Hypothesis Tracking (MHT) tracker.

Maintains multiple hypotheses about measurement-to-track associations, with N-scan pruning for complexity control.

Parameters:

state_dim (int) – Dimension of state vector.
meas_dim (int) – Dimension of measurement vector.
F (callable or ndarray) – State transition matrix or function F(dt) -> ndarray.
H (ndarray) – Measurement matrix.
Q (callable or ndarray) – Process noise covariance or function Q(dt) -> ndarray.
R (ndarray) – Measurement noise covariance.
config (MHTConfig, optional) – Tracker configuration. Uses defaults if not provided.
init_covariance (ndarray, optional) – Initial covariance for new tracks.

Examples

>>> import numpy as np
>>> # Constant velocity model
>>> F = lambda dt: np.array([[1, dt, 0, 0],
...                          [0, 1, 0, 0],
...                          [0, 0, 1, dt],
...                          [0, 0, 0, 1]])
>>> H = np.array([[1, 0, 0, 0],
...               [0, 0, 1, 0]])
>>> Q = lambda dt: 0.1 * np.eye(4)
>>> R = np.eye(2) * 0.5
>>> tracker = MHTTracker(4, 2, F, H, Q, R)
>>> # Process measurements
>>> measurements = [np.array([1, 2]), np.array([5, 6])]
>>> result = tracker.process(measurements, dt=1.0)

__init__(state_dim, meas_dim, F, H, Q, R, config=None, init_covariance=None)[source]

process(measurements, dt)[source]

Process measurements at new time step.

Parameters:

measurements (list of array_like) – List of measurement vectors.
dt (float) – Time step since last update.

Returns:

result – Tracking result with confirmed and tentative tracks.

Return type:

MHTResult

property tracks: List[MHTTrack]: Get all tracks from best hypothesis.

property confirmed_tracks: List[MHTTrack]: Get confirmed tracks from best hypothesis.

property n_hypotheses: int: Number of active hypotheses.

Hypothesis Management

Track hypothesis creation, scoring, and pruning.

Hypothesis management for Multiple Hypothesis Tracking (MHT).

This module provides data structures and algorithms for managing hypothesis trees in track-oriented MHT implementations.

References

S. Blackman and R. Popoli, “Design and Analysis of Modern Tracking Systems,” Artech House, 1999.
D. Reid, “An Algorithm for Tracking Multiple Targets,” IEEE Trans. Automatic Control, 1979.

class pytcl.trackers.hypothesis.MHTTrackStatus(value)[source]

Bases: Enum

Track status in MHT.

TENTATIVE = 'tentative'

CONFIRMED = 'confirmed'

DELETED = 'deleted'

class pytcl.trackers.hypothesis.MHTTrack(id, state, covariance, score, status, history, parent_id, scan_created, n_hits, n_misses)[source]

Bases: NamedTuple

Track state within MHT.

Variables:

id (int) – Unique track identifier.
state (ndarray) – State estimate vector.
covariance (ndarray) – State covariance matrix.
score (float) – Log-likelihood ratio score.
status (MHTTrackStatus) – Track status.
history (list of int) – Measurement indices associated with this track branch. -1 indicates a missed detection.
parent_id (int) – ID of parent track (-1 for root tracks).
scan_created (int) – Scan number when this track branch was created.
n_hits (int) – Number of measurement updates.
n_misses (int) – Number of consecutive misses.

id: int: Alias for field number 0

state: ndarray[tuple[Any, ...], dtype[floating]]: Alias for field number 1

covariance: ndarray[tuple[Any, ...], dtype[floating]]: Alias for field number 2

score: float: Alias for field number 3

status: MHTTrackStatus: Alias for field number 4

history: List[int]: Alias for field number 5

parent_id: int: Alias for field number 6

scan_created: int: Alias for field number 7

n_hits: int: Alias for field number 8

n_misses: int: Alias for field number 9

class pytcl.trackers.hypothesis.Hypothesis(id, probability, track_ids, scan_created, parent_id)[source]

Bases: NamedTuple

A global hypothesis in MHT.

A hypothesis represents a consistent assignment of measurements to tracks across multiple scans. Each hypothesis maintains a set of track branches that are mutually compatible.

Variables:

id (int) – Unique hypothesis identifier.
probability (float) – Posterior probability of this hypothesis.
track_ids (list of int) – IDs of tracks included in this hypothesis.
scan_created (int) – Scan number when this hypothesis was created.
parent_id (int) – ID of parent hypothesis (-1 for initial hypothesis).

id: int: Alias for field number 0

probability: float: Alias for field number 1

track_ids: List[int]: Alias for field number 2

scan_created: int: Alias for field number 3

parent_id: int: Alias for field number 4

class pytcl.trackers.hypothesis.HypothesisAssignment(track_id, measurement_idx, likelihood)[source]

Bases: NamedTuple

A track-to-measurement assignment within a hypothesis.

Variables:

track_id (int) – Track ID.
measurement_idx (int) – Measurement index (-1 for missed detection).
likelihood (float) – Likelihood of this assignment.

track_id: int: Alias for field number 0

measurement_idx: int: Alias for field number 1

likelihood: float: Alias for field number 2

pytcl.trackers.hypothesis.generate_joint_associations(gated, n_tracks, n_meas)[source]

Generate all valid joint measurement-to-track associations.

A valid association satisfies: - Each measurement is assigned to at most one track - Each track is assigned to at most one measurement - Only gated track-measurement pairs are considered

Parameters:

gated (ndarray) – Boolean gating matrix, shape (n_tracks, n_meas). gated[i, j] = True if track i can be associated with measurement j.
n_tracks (int) – Number of tracks.
n_meas (int) – Number of measurements.

Returns:

associations – List of valid associations. Each dict maps track_id to meas_idx. meas_idx = -1 indicates missed detection.

Return type:

list of dict

Examples

>>> gated = np.array([[True, True], [True, True]])
>>> associations = generate_joint_associations(gated, 2, 2)
>>> len(associations)  # All valid 2-track, 2-measurement associations
7

pytcl.trackers.hypothesis.compute_association_likelihood(association, likelihood_matrix, detection_prob, clutter_density, n_meas)[source]

Compute likelihood of a joint association.

Parameters:

association (dict) – Mapping from track_id to measurement_idx (-1 for miss).
likelihood_matrix (ndarray) – Likelihood values, shape (n_tracks, n_meas).
detection_prob (float) – Probability of detection.
clutter_density (float) – Spatial density of clutter (false alarms).
n_meas (int) – Total number of measurements.

Returns:

likelihood – Joint likelihood of the association.

Return type:

float

Examples

>>> import numpy as np
>>> # 2 tracks, 2 measurements
>>> likelihood_matrix = np.array([[0.9, 0.1],
...                                [0.1, 0.8]])
>>> # Association: track 0 -> meas 0, track 1 -> meas 1
>>> association = {0: 0, 1: 1}
>>> lik = compute_association_likelihood(
...     association, likelihood_matrix,
...     detection_prob=0.9, clutter_density=1e-6, n_meas=2
... )
>>> lik > 0
True
>>> # Association with missed detection
>>> assoc_miss = {0: 0, 1: -1}  # track 1 misses
>>> lik_miss = compute_association_likelihood(
...     assoc_miss, likelihood_matrix,
...     detection_prob=0.9, clutter_density=1e-6, n_meas=2
... )
>>> lik > lik_miss  # Full detection more likely
True

pytcl.trackers.hypothesis.n_scan_prune(hypotheses, tracks, n_scan, current_scan)[source]

N-scan pruning of hypotheses.

Removes hypotheses that diverged from the most likely hypothesis more than n_scan scans ago. This implements “deferred decision” pruning where associations older than N scans are committed to.

Parameters:

hypotheses (list of Hypothesis) – Current hypotheses.
tracks (dict) – Mapping from track_id to MHTTrack.
n_scan (int) – Number of scans to look back.
current_scan (int) – Current scan number.

Returns:

pruned_hypotheses (list of Hypothesis) – Hypotheses surviving pruning.
committed_track_ids (set) – Track IDs that are now committed (survived N-scan).

Return type:

Tuple[List[Hypothesis], Set[int]]

Examples

>>> import numpy as np
>>> from pytcl.trackers.hypothesis import (
...     Hypothesis, MHTTrack, MHTTrackStatus, n_scan_prune
... )
>>> # Two hypotheses, tracks with different creation scans
>>> track1 = MHTTrack(id=0, state=np.zeros(2), covariance=np.eye(2),
...                   score=1.0, status=MHTTrackStatus.CONFIRMED,
...                   history=[0], parent_id=-1, scan_created=0,
...                   n_hits=3, n_misses=0)
>>> track2 = MHTTrack(id=1, state=np.zeros(2), covariance=np.eye(2),
...                   score=0.5, status=MHTTrackStatus.TENTATIVE,
...                   history=[1], parent_id=-1, scan_created=2,
...                   n_hits=1, n_misses=0)
>>> tracks = {0: track1, 1: track2}
>>> hyp1 = Hypothesis(id=0, probability=0.8, track_ids=[0],
...                   scan_created=0, parent_id=-1)
>>> hyp2 = Hypothesis(id=1, probability=0.2, track_ids=[1],
...                   scan_created=2, parent_id=-1)
>>> pruned, committed = n_scan_prune([hyp1, hyp2], tracks, n_scan=2,
...                                   current_scan=3)
>>> len(pruned) >= 1
True

Notes

N-scan pruning works by:

1. Finding tracks that agree across all high-probability hypotheses
   at scan (current_scan - n_scan)
2. Removing hypotheses that disagree with the "committed" decision

pytcl.trackers.hypothesis.prune_hypotheses_by_probability(hypotheses, max_hypotheses, min_probability=1e-06)[source]

Prune hypotheses by probability threshold and count limit.

Parameters:

hypotheses (list of Hypothesis) – Current hypotheses.
max_hypotheses (int) – Maximum number of hypotheses to retain.
min_probability (float) – Minimum probability threshold.

Returns:

pruned – Pruned and renormalized hypotheses.

Return type:

list of Hypothesis

Examples

>>> from pytcl.trackers.hypothesis import Hypothesis, prune_hypotheses_by_probability
>>> # 5 hypotheses with varying probabilities
>>> hyps = [
...     Hypothesis(id=0, probability=0.5, track_ids=[0], scan_created=0, parent_id=-1),
...     Hypothesis(id=1, probability=0.3, track_ids=[1], scan_created=0, parent_id=-1),
...     Hypothesis(id=2, probability=0.1, track_ids=[2], scan_created=0, parent_id=-1),
...     Hypothesis(id=3, probability=0.05, track_ids=[3], scan_created=0, parent_id=-1),
...     Hypothesis(id=4, probability=1e-8, track_ids=[4], scan_created=0, parent_id=-1),
... ]
>>> pruned = prune_hypotheses_by_probability(hyps, max_hypotheses=3)
>>> len(pruned)  # Only top 3 kept
3
>>> sum(h.probability for h in pruned)  # Renormalized to 1
1.0

class pytcl.trackers.hypothesis.HypothesisTree(max_hypotheses=100, n_scan=3, min_probability=1e-06)[source]

Bases: object

Manages hypothesis tree for MHT.

The hypothesis tree represents all possible interpretations of measurement-to-track associations across multiple scans.

Parameters:

max_hypotheses (int) – Maximum number of hypotheses to maintain.
n_scan (int) – Number of scans for N-scan pruning.
min_probability (float) – Minimum hypothesis probability threshold.

Variables:

hypotheses (list of Hypothesis) – Current set of hypotheses.
tracks (dict) – Mapping from track_id to MHTTrack.
current_scan (int) – Current scan number.

__init__(max_hypotheses=100, n_scan=3, min_probability=1e-06)[source]

hypotheses: List[Hypothesis]

tracks: Dict[int, MHTTrack]

initialize(initial_tracks=None)[source]

Initialize the hypothesis tree.

Parameters:: initial_tracks (list of MHTTrack, optional) – Initial tracks to include.

add_track(track)[source]

Add a new track to the tree.

Parameters:: track (MHTTrack) – Track to add.
Returns:: track_id – ID assigned to the track.
Return type:: int

expand_hypotheses(associations, likelihoods, new_tracks)[source]

Expand hypotheses with new associations.

Parameters:

associations (list of dict) – Valid joint associations.
likelihoods (list of float) – Likelihood of each association.
new_tracks (dict) – Mapping from association_idx to list of new tracks created by that association.

prune()[source]

Apply all pruning strategies.

get_best_hypothesis()[source]

Get the most probable hypothesis.

get_best_tracks()[source]

Get tracks from the best hypothesis.

get_confirmed_tracks()[source]

Get confirmed tracks from the best hypothesis.