nrl-tracker 1.0.1__tar.gz

nrl_tracker-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,339 @@
+# Contributing to Tracker Component Library (Python)
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to the Python port of the Tracker Component Library.
+
+## Development Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/nedonatelli/TCL.git
+   cd TCL
+   ```
+
+2. **Create a virtual environment:**
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. **Install development dependencies:**
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+4. **Install pre-commit hooks:**
+   ```bash
+   pre-commit install
+   ```
+
+## Code Style
+
+We follow these conventions:
+
+- **Code formatting:** [Black](https://black.readthedocs.io/) with default settings
+- **Linting:** [Flake8](https://flake8.pycqa.org/)
+- **Type hints:** Required for all public functions
+- **Docstrings:** NumPy style
+
+### Example Function
+
+```python
+def cart2sphere(
+    cart_points: ArrayLike,
+    system_type: int = 0,
+) -> NDArray[np.floating[Any]]:
+    """
+    Convert Cartesian coordinates to spherical coordinates.
+
+    Parameters
+    ----------
+    cart_points : array_like
+        Cartesian points with shape (3,) or (3, n) where each column is [x, y, z].
+    system_type : int, optional
+        Spherical coordinate system convention. Default is 0.
+        - 0: [range, azimuth, elevation] with azimuth from x-axis in xy-plane
+        - 1: [range, azimuth, elevation] with azimuth from y-axis
+
+    Returns
+    -------
+    NDArray
+        Spherical coordinates with shape (3,) or (3, n).
+        Each column is [range, azimuth, elevation].
+
+    Examples
+    --------
+    >>> cart2sphere([1, 0, 0])
+    array([1.        , 0.        , 0.        ])
+
+    >>> cart2sphere([[1, 0], [0, 1], [0, 0]])
+    array([[1.        , 1.        ],
+           [0.        , 1.57079633],
+           [0.        , 0.        ]])
+
+    Notes
+    -----
+    This is a port of Cart2Sphere.m from the MATLAB library.
+
+    References
+    ----------
+    .. [1] D. F. Crouse, "The Tracker Component Library..."
+    """
+    ...
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=pytcl --cov-report=html
+
+# Run specific test file
+pytest tests/unit/test_core.py
+
+# Run tests matching a pattern
+pytest -k "test_wrap"
+
+# Run only fast tests
+pytest -m "not slow"
+```
+
+### Writing Tests
+
+1. **Place tests in the appropriate directory:**
+   - `tests/unit/` - Unit tests for individual functions
+   - `tests/integration/` - Integration tests
+   - `tests/fixtures/` - Test data files
+
+2. **Use descriptive test names:**
+   ```python
+   def test_cart2sphere_single_point():
+       ...
+
+   def test_cart2sphere_multiple_points():
+       ...
+
+   def test_cart2sphere_raises_on_invalid_input():
+       ...
+   ```
+
+3. **Test against MATLAB reference values:**
+   ```python
+   @pytest.mark.matlab_validated
+   def test_cart2sphere_matches_matlab():
+       # Load reference values generated from MATLAB
+       ref = np.load('tests/fixtures/cart2sphere_reference.npz')
+       result = cart2sphere(ref['input'])
+       np.testing.assert_allclose(result, ref['expected'], rtol=1e-12)
+   ```
+
+### Generating MATLAB Reference Data
+
+For functions ported from MATLAB, generate reference test data:
+
+```matlab
+% In MATLAB with TrackerComponentLibrary loaded
+input = randn(3, 100);
+output = Cart2Sphere(input);
+save('cart2sphere_reference.mat', 'input', 'output');
+```
+
+Then convert to NumPy format:
+```python
+from scipy.io import loadmat
+import numpy as np
+
+data = loadmat('cart2sphere_reference.mat')
+np.savez('cart2sphere_reference.npz', 
+         input=data['input'], 
+         expected=data['output'])
+```
+
+## Porting Functions from MATLAB
+
+When porting a function from the original MATLAB library:
+
+1. **Study the original:**
+   - Read the MATLAB code and comments thoroughly
+   - Understand the algorithm and edge cases
+   - Note any MATLAB-specific behaviors
+
+2. **Follow naming conventions:**
+   - MATLAB: `Cart2Sphere`, `FPolyKal`, `KalmanUpdate`
+   - Python: `cart2sphere`, `poly_kalman_F`, `kalman_update`
+
+3. **Handle array conventions:**
+   - MATLAB uses column vectors by default
+   - NumPy is row-major but we follow MATLAB conventions for state vectors
+   - Document clearly when shapes differ
+
+4. **Add the reference:**
+   ```python
+   Notes
+   -----
+   This is a port of Cart2Sphere.m from the MATLAB Tracker Component Library.
+   
+   References
+   ----------
+   .. [1] Original implementation: 
+          https://github.com/USNavalResearchLaboratory/TrackerComponentLibrary
+   ```
+
+5. **Test thoroughly:**
+   - Generate MATLAB reference values
+   - Test edge cases (empty arrays, single values, etc.)
+   - Test numerical accuracy
+
+## Pull Request Process
+
+1. **Create a feature branch:**
+   ```bash
+   git checkout -b feature/add-coordinated-turn-model
+   ```
+
+2. **Make your changes:**
+   - Write code following style guidelines
+   - Add tests
+   - Update documentation
+
+3. **Run quality checks:**
+   ```bash
+   # Format code
+   black .
+   
+   # Lint
+   flake8 pytcl tests
+   
+   # Type check
+   mypy pytcl
+   
+   # Run tests
+   pytest
+   ```
+
+4. **Submit the PR:**
+   - Write a clear description
+   - Reference any related issues
+   - Ensure CI passes
+
+## Priority Areas
+
+If you're looking for ways to contribute, these areas are priorities:
+
+### High Priority
+- Coordinate system conversions (`coordinate_systems/conversions/`)
+- Basic Kalman filter implementation (`dynamic_estimation/kalman/`)
+- Constant velocity/acceleration models (`dynamic_models/discrete_time/`)
+- Hungarian algorithm for assignment (`assignment_algorithms/`)
+
+### Medium Priority  
+- UKF and EKF implementations
+- Coordinated turn models
+- JPDA data association
+- OSPA metric
+
+### Lower Priority
+- Astronomical code (consider using astropy)
+- Gravity/magnetism models
+- Terrain models
+
+## Release Process
+
+When preparing a new release, follow these steps:
+
+### 1. Update Version Numbers
+
+Update the version in these files:
+- `pyproject.toml` - `version = "X.Y.Z"`
+- `docs/conf.py` - `release = "X.Y.Z"`
+- `docs/_static/landing.html` - Update the status badge version
+
+### 2. Update Landing Page Statistics
+
+In `docs/_static/landing.html`, update the statistics to reflect current metrics:
+- **Version badge** (line ~730): `vX.Y.Z — 720+ Functions`
+- **Test count** (line ~766): Run `pytest --collect-only` to get current test count
+- **Other stats** as needed (functions, modules, etc.)
+
+### 3. Sync Examples
+
+Copy examples from the root `examples/` directory to `docs/examples/`:
+
+```bash
+cp examples/*.py docs/examples/
+```
+
+### 4. Run Quality Checks
+
+```bash
+# Sort imports
+isort pytcl tests examples docs/examples
+
+# Format code
+black .
+
+# Lint
+flake8 pytcl tests examples docs/examples
+
+# Type check
+mypy pytcl examples docs/examples
+
+# Run full test suite with coverage
+pytest --cov=pytcl --cov-report=term-missing
+```
+
+### 5. Verify Examples Run
+
+Run each example script to ensure they execute without errors:
+
+```bash
+for f in examples/*.py; do echo "Running $f..."; python "$f" || exit 1; done
+```
+
+### 6. Update Roadmap Files
+
+Update both `ROADMAP.md` and `docs/roadmap.rst`:
+
+**In `ROADMAP.md`:**
+- Check off completed items with `[x]` or ~~strikethrough~~
+- Update phase status (e.g., "✅ Completed in vX.Y.Z")
+- Add any new planned features discovered during development
+- Update version targets for upcoming phases if needed
+
+**In `docs/roadmap.rst`:**
+- Update "Current State (vX.Y.Z)" section header with new version
+- Update statistics (functions, tests, coverage)
+- Add new completed phase under "Completed Phases"
+- Update the "Version Targets" table with new release
+
+### 7. Update Documentation
+
+- Ensure all new features are documented
+- Rebuild docs locally to verify: `cd docs && make html`
+
+### 8. Create Release Commit
+
+```bash
+git add -A
+git commit -m "Release vX.Y.Z: <brief description>"
+git tag vX.Y.Z
+git push origin main --tags
+```
+
+### 9. Publish to PyPI
+
+```bash
+python -m build
+twine upload dist/*
+```
+
+## Questions?
+
+- Open an issue for bugs or feature requests
+- Start a discussion for questions or ideas
+
+Thank you for contributing!

nrl_tracker-1.0.1/LICENSE

@@ -0,0 +1,42 @@
+This work is in the public domain.
+
+The original MATLAB Tracker Component Library was developed by the U.S. Naval
+Research Laboratory and released under the following terms:
+
+DISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited.
+
+This Python port follows the same licensing terms.
+
+As a work of the United States Government, this project is not subject to
+copyright protection in the United States. Additionally, we waive copyright
+and related rights in the work worldwide through the CC0 1.0 Universal
+public domain dedication.
+
+CC0 1.0 Universal Summary
+-------------------------
+
+No Copyright
+
+The person who associated a work with this deed has dedicated the work to
+the public domain by waiving all of their rights to the work worldwide under
+copyright law, including all related and neighboring rights, to the extent
+allowed by law.
+
+You can copy, modify, distribute and perform the work, even for commercial
+purposes, all without asking permission.
+
+Other Information
+
+In no way are the patent or trademark rights of any person affected by CC0,
+nor are the rights that other persons may have in the work or in how the
+work is used, such as publicity or privacy rights.
+
+Unless expressly stated otherwise, the person who associated a work with
+this deed makes no warranties about the work, and disclaims liability for
+all uses of the work, to the fullest extent permitted by applicable law.
+
+When using or citing the work, you should not imply endorsement by the
+author or the affirmer.
+
+For the full legal text, see:
+https://creativecommons.org/publicdomain/zero/1.0/legalcode

nrl_tracker-1.0.1/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.md
+include CONTRIBUTING.md
+recursive-include pytcl *.py
+recursive-include tests *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

nrl_tracker-1.0.1/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.1
+Name: nrl-tracker
+Version: 1.0.1
+Summary: Python port of the U.S. Naval Research Laboratory's Tracker Component Library for target tracking algorithms
+Author: Original: David F. Crouse, Naval Research Laboratory
+Maintainer: Python Port Contributors
+Project-URL: Homepage, https://pytcl.readthedocs.io/en
+Project-URL: Documentation, https://pytcl.readthedocs.io/en/latest/docs.html
+Project-URL: Repository, https://github.com/nedonatelli/TCL
+Project-URL: Bug Tracker, https://github.com/nedonatelli/TCL/issues
+Project-URL: Original MATLAB Library, https://github.com/USNavalResearchLaboratory/TrackerComponentLibrary
+Keywords: tracking,kalman-filter,target-tracking,data-association,estimation,navigation,coordinate-systems,signal-processing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: Public Domain
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: numba>=0.57.0
+Provides-Extra: astronomy
+Requires-Dist: astropy>=5.0; extra == "astronomy"
+Requires-Dist: jplephem>=2.18; extra == "astronomy"
+Provides-Extra: geodesy
+Requires-Dist: pyproj>=3.4.0; extra == "geodesy"
+Requires-Dist: geographiclib>=2.0; extra == "geodesy"
+Provides-Extra: visualization
+Requires-Dist: plotly>=5.15.0; extra == "visualization"
+Provides-Extra: optimization
+Requires-Dist: cvxpy>=1.3.0; extra == "optimization"
+Provides-Extra: signal
+Requires-Dist: pywavelets>=1.4.0; extra == "signal"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=7.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Requires-Dist: sphinx>=6.0.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "dev"
+Requires-Dist: myst-parser>=1.0.0; extra == "dev"
+Requires-Dist: nbsphinx>=0.9.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: nrl-tracker[astronomy,dev,geodesy,optimization,signal,visualization]; extra == "all"
+
+# Tracker Component Library (Python)
+
+[![PyPI version](https://img.shields.io/badge/pypi-v1.0.0-blue.svg)](https://pypi.org/project/nrl-tracker/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: Public Domain](https://img.shields.io/badge/License-Public%20Domain-brightgreen.svg)](https://en.wikipedia.org/wiki/Public_domain)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Tests](https://img.shields.io/badge/tests-1598%20passing-success.svg)](https://github.com/nedonatelli/TCL)
+
+A Python port of the [U.S. Naval Research Laboratory's Tracker Component Library](https://github.com/USNavalResearchLaboratory/TrackerComponentLibrary), a comprehensive collection of algorithms for target tracking, estimation, coordinate systems, and related mathematical functions.
+
+**800+ functions** | **144 modules** | **1,598 tests** | **15+ algorithm categories**
+
+## 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 (EKF, UKF, etc.), particle filters, and batch estimation
+- **Assignment Algorithms**: Hungarian algorithm, auction algorithms, and multi-dimensional assignment
+- **Mathematical Functions**: Special functions, statistics, numerical integration, and more
+- **Astronomical Code**: Ephemeris calculations, time systems, celestial mechanics
+- **Navigation**: Geodetic calculations, INS algorithms, GNSS utilities
+- **Geophysical Models**: Gravity, magnetism, atmosphere, and terrain models
+
+## Installation
+
+### Basic Installation
+
+```bash
+pip install nrl-tracker
+```
+
+### With Optional Dependencies
+
+```bash
+# For astronomy features (ephemerides, celestial mechanics)
+pip install nrl-tracker[astronomy]
+
+# For geodesy features (coordinate transforms, map projections)
+pip install nrl-tracker[geodesy]
+
+# For visualization
+pip install nrl-tracker[visualization]
+
+# For development
+pip install nrl-tracker[dev]
+
+# Install everything
+pip install nrl-tracker[all]
+```
+
+### From Source
+
+```bash
+git clone https://github.com/nedonatelli/TCL.git
+cd TCL
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Coordinate Conversions
+
+```python
+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
+
+```python
+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
+
+```python
+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}")
+```
+
+## 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
+└── misc/                    # Utilities, visualization
+```
+
+## Documentation
+
+- [API Reference](https://pytcl.readthedocs.io/en/latest/api/)
+- [User Guides](https://pytcl.readthedocs.io/en/latest/user_guide/)
+- [Examples](examples/)
+
+## 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
+
+```bash
+# 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](CONTRIBUTING.md) for guidelines.
+
+### Development Setup
+
+```bash
+git clone https://github.com/nedonatelli/TCL.git
+cd TCL
+pip install -e ".[dev]"
+pre-commit install
+```
+
+### Running Quality Checks
+
+```bash
+# 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:
+
+```bibtex
+@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](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](https://github.com/rlabbe/filterpy) - Kalman filtering library
+- [Stone Soup](https://github.com/dstl/Stone-Soup) - Framework for tracking algorithms
+- [Astropy](https://www.astropy.org/) - Astronomy library for Python