gri-kalman 0.1.0

Per-target Kalman/IMM tracking: interacting multiple models, maneuver segmentation, RTS smoothing, EKF/UKF observable updates, and a motion-model bank

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

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.