nrl-tracker 1.15.0

Python port of the U.S. Naval Research Laboratory's Tracker Component Library for target tracking algorithms

Tracker Component Library (Python)

A Python port of the U.S. Naval Research Laboratory's Tracker Component Library, a comprehensive collection of algorithms for target tracking, estimation, coordinate systems, and related mathematical functions.

1,048 functions | 133 modules | 3,306 tests | 100% MATLAB parity

Overview

The Tracker Component Library provides building blocks for developing target tracking algorithms, including:

• Coordinate Systems: Conversions between Cartesian, spherical, geodetic, and other coordinate systems
• Dynamic Models: State transition matrices for constant velocity, coordinated turn, and other motion models
• Estimation Algorithms: Kalman filters (KF, EKF, UKF, CKF, CEKF, H-infinity), particle filters (bootstrap, RBPF), smoothers, and batch estimation
• Assignment Algorithms: Hungarian algorithm, auction algorithms, 3D/ND assignment, k-best assignments
• Data Association: Global Nearest Neighbor, JPDA, MHT for multi-target tracking
• Mathematical Functions: Special functions, statistics, numerical integration, and more
• Astronomical Code: SGP4/SDP4 propagation, TLE parsing, special orbits (parabolic/hyperbolic), ephemerides, relativistic corrections
• Reference Frames: GCRF, ITRF, TEME, TOD, MOD with full transformation chains
• Navigation: Geodetic calculations, INS mechanization, GNSS utilities, INS/GNSS integration
• Geophysical Models: Gravity (WGS84, EGM96/2008), magnetism (WMM, IGRF, EMM, WMMHR2025), atmosphere (NRLMSISE-00), tides, terrain (GEBCO 2025, Earth2014)
• Signal Processing: Digital filters, matched filtering, CFAR detection, transforms (FFT, STFT, wavelets)
• GPU Acceleration: CuPy (NVIDIA CUDA) and MLX (Apple Silicon) backends for batch Kalman filtering and particle filters

Installation

Basic Installation

pip install nrl-tracker

With Optional Dependencies

# For astronomy features (ephemerides, celestial mechanics)
pip install nrl-tracker[astronomy]

# For geodesy features (coordinate transforms, map projections)
pip install nrl-tracker[geodesy]

# For terrain data (GEBCO, Earth2014 via NetCDF)
pip install nrl-tracker[terrain]

# For visualization
pip install nrl-tracker[visualization]

# For optimization (CVXPY)
pip install nrl-tracker[optimization]

# For signal processing (wavelets)
pip install nrl-tracker[signal]

# For GPU acceleration (NVIDIA CUDA)
pip install nrl-tracker[gpu]

# For GPU acceleration (Apple Silicon M1/M2/M3)
pip install nrl-tracker[gpu-apple]

# For development
pip install nrl-tracker[dev]

# Install everything
pip install nrl-tracker[all]

From Source

git clone https://github.com/nedonatelli/TCL.git
cd TCL
pip install -e ".[dev]"

Quick Start

Coordinate Conversions

import numpy as np
from pytcl.coordinate_systems import cart2sphere, sphere2cart

# Convert Cartesian to spherical coordinates
cart_point = np.array([1.0, 1.0, 1.0])
r, az, el = cart2sphere(cart_point)
print(f"Range: {r:.3f}, Azimuth: {np.degrees(az):.1f}°, Elevation: {np.degrees(el):.1f}°")

# Convert back
cart_recovered = sphere2cart(r, az, el)

Kalman Filter

from pytcl.dynamic_estimation.kalman import KalmanFilter
from pytcl.dynamic_models import constant_velocity_model

# Create a constant velocity model
dt = 0.1
F, Q = constant_velocity_model(dt, dimension=2, process_noise_intensity=1.0)

# Initialize filter
kf = KalmanFilter(
    F=F,  # State transition matrix
    H=np.array([[1, 0, 0, 0], [0, 0, 1, 0]]),  # Measurement matrix
    Q=Q,  # Process noise
    R=np.eye(2) * 10,  # Measurement noise
)

# Run filter
x_est, P_est = kf.predict()
x_est, P_est = kf.update(measurement)

Assignment Problem

from pytcl.assignment_algorithms import hungarian

# Cost matrix (tracks x measurements)
cost_matrix = np.array([
    [10, 5, 13],
    [3, 15, 8],
    [7, 9, 12],
])

# Solve assignment
assignment, total_cost = hungarian(cost_matrix)
print(f"Optimal assignment: {assignment}, Total cost: {total_cost}")

GPU Acceleration

The library supports GPU acceleration for batch processing of multiple tracks:

from pytcl.gpu import is_gpu_available, get_backend, to_gpu, to_cpu

# Check GPU availability (auto-detects CUDA or Apple Silicon)
if is_gpu_available():
    print(f"GPU available, using {get_backend()} backend")

    # Transfer data to GPU
    x_gpu = to_gpu(states)  # (n_tracks, state_dim)
    P_gpu = to_gpu(covariances)  # (n_tracks, state_dim, state_dim)

    # Use batch Kalman filter operations
    from pytcl.gpu import batch_kf_predict
    x_pred, P_pred = batch_kf_predict(x_gpu, P_gpu, F, Q)

    # Transfer results back to CPU
    x_pred_cpu = to_cpu(x_pred)

Supported backends:

• NVIDIA CUDA: Via CuPy (pip install nrl-tracker[gpu])
• Apple Silicon: Via MLX (pip install nrl-tracker[gpu-apple])

The backend is automatically selected based on your platform.

Module Structure

pytcl/
├── core/                    # Foundation utilities and constants
├── mathematical_functions/  # Basic math, statistics, special functions
├── coordinate_systems/      # Coordinate conversions and transforms
├── dynamic_models/          # State transition and process noise models
├── dynamic_estimation/      # Kalman filters, particle filters
├── static_estimation/       # ML, least squares estimation
├── assignment_algorithms/   # 2D and multi-dimensional assignment
├── clustering/              # Mixture reduction, clustering
├── performance_evaluation/  # OSPA, track metrics
├── astronomical/            # Ephemerides, time systems
├── navigation/              # Geodetic, INS, GNSS
├── atmosphere/              # Atmosphere models, refraction
├── gravity/                 # Gravity models
├── magnetism/               # Magnetic field models
├── terrain/                 # Terrain elevation models
├── gpu/                     # GPU acceleration (CuPy/MLX)
└── misc/                    # Utilities, visualization

Examples & Tutorials

The library includes 39 runnable code examples demonstrating all major features:

Examples (29 files in /examples/)

Comprehensive demonstrations of library functionality:

• Tracking & Estimation: Kalman filters, particle filters, smoothers
• Assignment: Hungarian algorithm, k-best assignments, 3D assignment
• Coordinates: Frame conversions, transformations, geodetic calculations
• Dynamics: State models, motion models, dynamic systems
• Filtering: Uncertainty visualization, multi-target tracking
• Astronomy: Ephemerides, orbital mechanics, relativistic corrections
• Navigation: INS/GNSS integration, geophysical modeling
• Signal Processing: Detection, filtering, transforms
• Terrain & Atmosphere: Elevation models, atmospheric properties

Status: ✅ All 29 examples validated and passing (100% execution success)

Tutorials (10 modules in /docs/tutorials/)

Interactive learning modules with visualizations:

• Assignment algorithms and 3D assignment problems
• Atmospheric and geophysical models
• Dynamical systems and reference frames
• Filtering and smoothing techniques
• Sensor fusion and advanced filtering
• Special functions and mathematical tools

Status: ✅ All 10 tutorials validated and passing (100% execution success)

Documentation

• API Reference
• User Guides
• Examples - 29 validated example scripts
• Tutorials - 10 interactive tutorial modules

Comparison with Original MATLAB Library

This library aims to provide equivalent functionality to the original MATLAB library with Pythonic APIs:

MATLAB	Python
Cart2Sphere(cartPoints)	cart2sphere(cart_points)
FPolyKal(T, xDim, order)	poly_kalman_F(dt, dim, order)
KalmanUpdate(...)	KalmanFilter.update(...)

Key differences:

• Function names use snake_case instead of PascalCase
• Arrays are NumPy arrays (row-major) vs MATLAB matrices (column-major)
• 0-based indexing vs 1-based indexing
• Object-oriented APIs where appropriate

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=pytcl

# Run only fast tests
pytest -m "not slow"

# Run tests validated against MATLAB
pytest -m matlab_validated

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/nedonatelli/TCL.git
cd TCL
pip install -e ".[dev]"
pre-commit install

Running Quality Checks

# Format code
black .

# Lint
flake8 pytcl

# Type check
mypy pytcl

# Run all checks
pre-commit run --all-files

Citation

If you use this library in your research, please cite the original MATLAB library:

@article{crouse2017tracker,
  title={The Tracker Component Library: Free Routines for Rapid Prototyping},
  author={Crouse, David F.},
  journal={IEEE Aerospace and Electronic Systems Magazine},
  volume={32},
  number={5},
  pages={18--27},
  year={2017},
  publisher={IEEE}
}

License

This project is in the public domain, following the original MATLAB library's license. See LICENSE for details.

Acknowledgments

• Original MATLAB library by David F. Crouse at the U.S. Naval Research Laboratory
• This port follows the Federal Source Code Policy (OMB M-16-21)

Related Projects

• FilterPy - Kalman filtering library
• Stone Soup - Framework for tracking algorithms
• Astropy - Astronomy library for Python