Tracker Component Library

A Python port of the U.S. Naval Research Laboratory’s Tracker Component Library, providing a comprehensive collection of algorithms for target tracking and state estimation.

v2.8.0 — 1,610 functions | 195 modules | 5,574 test functions | ty type-checked | 88% coverage | 9 interactive notebooks | GPU acceleration (CuPy + MLX)

Note

On MATLAB parity: the core tracking workflow — filter, associate, track, evaluate, in Earth-referenced coordinates — is fully ported and validated against independent references. The full MATLAB public surface is covered at roughly a third by function count; see MATLAB TCL parity inventory for the function-level accounting and MATLAB-to-pytcl migration map for verified name mappings.

Start Here

Filtering & Estimation

Tracking & Association

Domain-Specific

Performance & Advanced

Reference & Learning

Overview

The Tracker Component Library provides:

  • Dynamic Estimation: Kalman filters (KF, EKF, UKF, CKF, CEKF, IMM), particle filters (RBPF), smoothers (RTS, fixed-lag, two-filter), information filters (SRIF), H-infinity

  • Data Association: GNN, JPDA, MHT, 2D/3D assignment (Hungarian, auction, Murty)

  • Coordinate Systems: Cartesian, spherical, geodetic conversions; map projections (UTM, Mercator, Lambert); rotation representations

  • Dynamic Models: Constant velocity, acceleration, Singer, coordinated turn, and polynomial motion models

  • Navigation: INS mechanization, INS/GNSS integration, great circle/rhumb line navigation, TDOA localization

  • Geophysical Models: Gravity (WGS84, EGM96/2008), magnetism (WMM2025 default, WMM2020, IGRF-14, IGRF-13, EMM), atmosphere (simplified thermosphere), tidal effects, terrain/DEM utilities

  • Astronomical: Orbital mechanics, Kepler propagation, Lambert problem, reference frame transformations, JPL ephemerides (DE405/430/432s/440), relativistic corrections (Schwarzschild, geodetic precession, Shapiro delay)

  • Mathematical Functions: Special functions (Marcum Q, Lambert W, Debye, hypergeometric, Bessel), statistics, numerical integration

  • GPU Acceleration: CuPy (NVIDIA CUDA) and MLX (Apple Silicon) backends for batch Kalman filtering, particle filters, and matrix operations (measured on MLX: 1.6x at 100 tracks to 40x at 20,000 tracks for batch Kalman)

  • Data Persistence: HDF5 and SQL backends for tracking data storage and retrieval

Installation

pip install nrl-tracker

Or install from source:

git clone https://github.com/nedonatelli/TCL.git
cd TCL
pip install -e .

Quick Start

Here’s a simple example using the Kalman filter:

import numpy as np
from pytcl.dynamic_estimation import kf_predict, kf_update
from pytcl.dynamic_models import f_constant_velocity, q_constant_velocity

# Initial state [x, vx, y, vy]
x = np.array([0.0, 1.0, 0.0, 0.5])
P = np.eye(4) * 0.1

# Motion model
T = 1.0  # time step
F = f_constant_velocity(T=T, num_dims=2)
Q = q_constant_velocity(T=T, sigma_a=0.1, num_dims=2)

# Predict
pred = kf_predict(x, P, F, Q)
print(f"Predicted state: {pred.x}")

# Measurement model (position only)
H = np.array([[1, 0, 0, 0], [0, 0, 1, 0]])
R = np.eye(2) * 0.5
z = np.array([1.1, 0.6])

# Update
upd = kf_update(pred.x, pred.P, z, H, R)
print(f"Updated state: {upd.x}")

Indices and tables