Metadata-Version: 2.4
Name: gri-kalman
Version: 0.1.0
Summary: Per-target Kalman/IMM tracking: interacting multiple models, maneuver segmentation, RTS smoothing, EKF/UKF observable updates, and a motion-model bank
Project-URL: Homepage, https://geosolresearch.com
Project-URL: Repository, https://gitlab.com/geosol-foss/python/gri-kalman
Project-URL: Issues, https://gitlab.com/geosol-foss/python/gri-kalman/-/issues
Project-URL: Changelog, https://gitlab.com/geosol-foss/python/gri-kalman/-/releases
Author-email: GeoSol Research Inc <contact@geosolresearch.com>
License-Expression: MIT
License-File: LICENSE
Keywords: IMM,RTS,UKF,estimation,kalman,tracking
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.12
Requires-Dist: gri-ell>=0.2.0
Requires-Dist: gri-obs>=0.1.0
Requires-Dist: gri-pos>=0.2.0
Requires-Dist: gri-utils>=0.3.3
Requires-Dist: numpy>=2.3.3
Requires-Dist: scipy>=1.16.2
Description-Content-Type: text/markdown

# gri-kalman

Per-target Kalman tracking for geolocation: interacting multiple model (IMM)
filters with a motion-model bank, maneuver segmentation, RTS smoothing, and
EKF/UKF measurement updates from either `Ell` position fixes or raw observables.

This package was factored out of `gri-convolve` so the per-target estimators can
be reused without the ellipsoid-convolution stack. It depends only on gri-ell,
gri-obs, gri-pos, gri-utils (plus numpy/scipy).

## Install

```bash
uv add gri-kalman
```

## Trackers

All implement the `Tracker` protocol (`update` / `update_observable` / `predict` /
`coast` / `smoothed_track` / `result` / `is_initialized`):

| Tracker | Description |
| --- | --- |
| `IMM` | Interacting multiple model filter over a motion-model bank |
| `SmartIMM` | IMM with outlier rejection on the measurement stream |
| `SegmentedIMM` | Maneuver-segmenting IMM (per-segment filters) |
| `SmartSegmentedIMM` | Segmenting + outlier-rejecting (the recommended default) |

Motion models: `ConstantVelocity`, `ConstantAcceleration`, `NearlyConstantSpeed`,
`CoordinatedTurn`, `Singer`, `ClimbDescent`, `Static` (plus the
`LinearMotionModel` / `NonlinearMotionModel` / `MotionModel` base protocols).

Smoothing: `rts_smooth`, `rts_smooth_segments`, `track_to_ells`. Result container:
`KalmanResult`.

## EKF vs UKF for observable updates

`update()` consumes an `Ell` (3D position + covariance) and is always an exact
linear update. `update_observable()` consumes a nonlinear observable (TDOA, FDOA,
AOA, Range, ...); choose the linearization with `update_method`:

- `"ekf"` (default): linearizes at the predicted mean via the observable's
  `jacobian()`. Cheap and accurate when the prior is tight relative to the
  geometry's nonlinearity.
- `"ukf"`: propagates sigma points through `predicted()` (no Jacobian). More
  robust (better-calibrated covariance) when the prior is broad and the
  observable is strongly nonlinear -- e.g. track initiation, long coast gaps,
  AOA, or satellite TDOA. Tune the spread with `ukf_alpha`.

The UKF's advantage is consistency, not necessarily smaller point error; switch
to it for robustness when the prior is broad, not expecting lower position error
in mildly nonlinear cases.

## Notes

- State is ECEF; positions/covariances interchange with gri-ell `Ell` objects.
- Downstream consumers: the multi-target engine `gri-multitrack` orchestrates
  these trackers via the `Tracker` protocol; gri-convolve no longer ships them.

## License

MIT -- see [LICENSE](LICENSE).
