Tracker Component Library (Python)

PyPI version Python 3.10+ License: Public Domain Linted and formatted with Ruff Tests MATLAB Parity Coverage Type Checking

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 | 4,622 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

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
ruff format .

# Lint (includes import sorting)
ruff check .

# 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

Project links

Data verified by PyPI on Jul 27, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.8.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nedonatelli from gravatar.com nedonatelli

Credits

Author: Original: David F. Crouse, Naval Research Laboratory

Maintainer: Python Port Contributors

GitHub Statistics

Data verified by PyPI on Jul 27, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Public Domain

Requires

Python >=3.10

Provides Extra

all astronomy benchmark dev geodesy gpu gpu-apple optimization signal terrain visualization

Tags

tracking kalman-filter target-tracking data-association estimation navigation coordinate-systems signal-processing

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nrl_tracker-1.17.0.tar.gz (860.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

nrl_tracker-1.17.0-py3-none-any.whl (603.3 kB view details)

Uploaded Python 3

File details

Details for the file nrl_tracker-1.17.0.tar.gz.

File metadata

  • Download URL: nrl_tracker-1.17.0.tar.gz
  • Upload date:
  • Size: 860.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for nrl_tracker-1.17.0.tar.gz
Algorithm Hash digest
SHA256 96d5397fceb2bd2021e358df26a49584248ddfa092b7716c686c7c747b4daf5f
MD5 3450da19c7f8c4eef5a9fc7f4c82df66
BLAKE2b-256 a3a4aee349ccc74c1ac75e3fc3d7cef2255c4198b70cfa68e41624b7f518f1ad

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrl_tracker-1.17.0.tar.gz:

Publisher: publish.yml on nedonatelli/TCL

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nrl_tracker-1.17.0-py3-none-any.whl.

File metadata

  • Download URL: nrl_tracker-1.17.0-py3-none-any.whl
  • Upload date:
  • Size: 603.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for nrl_tracker-1.17.0-py3-none-any.whl
Algorithm Hash digest
SHA256 115e4e3b28000d987e5f1dd9acda12d49a912d8e1e0a0f4bc2a03727e9a77e85
MD5 752ae5cd38e1367f0ee67030751663ae
BLAKE2b-256 42a15b2128516666045c20df29369fda4e75faa26460407e848747d86d509817

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrl_tracker-1.17.0-py3-none-any.whl:

Publisher: publish.yml on nedonatelli/TCL

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

2.8.0

2 files

2.7.0

2 files

2.6.0

2 files

2.5.0

2 files

2.4.0

2 files

2.3.0

2 files

2.2.0

2 files

2.1.0

2 files

2.0.0

2 files

1.19.0

2 files

1.18.0

2 files

This release

1.17.0 This release

2 files

1.16.0

2 files

1.15.1

2 files

1.15.0

2 files

1.14.0

2 files

1.13.2

2 files

1.13.1

2 files

1.13.0

2 files

1.12.1

2 files

1.12.0

2 files

1.11.1

2 files

1.11.0

2 files

1.10.0

2 files

1.9.2

2 files

1.9.1

2 files

1.9.0

2 files

1.8.0

2 files

1.7.5

2 files

1.7.4

2 files

1.7.3

2 files

1.7.1

2 files

1.7.0

2 files

1.6.0

2 files

1.5.0

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.1

2 files

1.0.0

2 files

0.22.5

2 files

0.22.4

2 files

0.22.3

2 files

0.22.2

2 files

0.22.1

2 files

0.22.0

2 files

0.21.5

2 files

0.21.4

2 files

0.21.3

2 files

0.21.2

2 files

0.21.1

2 files

0.21.0

2 files

0.20.1

2 files

0.20.0

2 files

0.19.1

2 files

0.16.0

2 files

0.15.0

2 files

0.14.4

2 files

0.14.0

2 files

0.13.2

2 files

0.13.0

2 files

0.12.0

2 files

0.11.0

2 files

0.10.1

2 files

0.10.0

2 files

0.9.0

2 files

0.8.0

2 files

0.7.1

2 files

0.6.0

2 files

0.5.1

2 files

0.5.0

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.1

2 files

0.3.0

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page