gri-kalman 0.1.1

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, AscendDescend, Static (plus the LinearMotionModel / NonlinearMotionModel / MotionModel base protocols).

Local-level (ENU) awareness

The state is ECEF, but a maneuver's "horizontal" and "vertical" are defined relative to local up, not the ECEF axes. Models whose dynamics or noise are anisotropic in that sense take a level_rotation provider (an ECEF position -> 3x3 ECEF->ENU rotation):

• CoordinatedTurn turns in the local horizontal plane about local up (not the ECEF polar axis).
• AscendDescend puts its large maneuvering noise along local up.
• ConstantVelocity can split process noise / velocity prior into horizontal and a small vertical component, to model a level mover (boat, car, cruising aircraft).

Pass a constant rotation for a fixed local-level frame (rigorous over a bounded area) or the position-dependent wgs84_level_rotation to follow Earth curvature with no re-origining.

Gauss-Markov reverting components

Several models hold a state that should revert toward zero absent evidence, all via the same first-order Gauss-Markov (Ornstein-Uhlenbeck) mechanism — a (tau, sigma) pair (time constant + steady-state spread), gauss_markov_step:

• Static reverts its (nuisance) velocity toward zero.
• CoordinatedTurn reverts its turn rate toward zero (straight), so a turn rate picked up from noise on a straight leg relaxes instead of persisting.
• Singer reverts its acceleration toward zero (the canonical named case).

The pull is gentle (long tau) — real maneuver evidence overrides it within a scan or two, so it costs no responsiveness.

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.