ExtendedKalmanFilter

giant.ufo.extended_kalman_filter:

class giant.ufo.extended_kalman_filter.ExtendedKalmanFilter(dynamics, state_initializer, initial_measurement=None)

This class implements a simple extended kalman filter for processing measurements and estimating a state for a target that generated those measurements.

The EKF works by linearizing about the current best estimate of the state at each measurement time, computing an update using the linearized space, updating the state, and then returning to the non-linear domain to propagate to the next measurement time. This is relatively fast and powerful, but it does require an adequate initial guess for the state vector for the linearization to be reasonable.

Using this EKF is fairly straight forward. Simply specify the Dynamics model that governs your system (and your state vector) and provide a function that takes in a Measurement instance and a Dynamics.State class object which initializes the state off of the first measurement of the target. Then you can simply call initialize() to initialize the state vector and process_measurement() to process measurements (note that you should not call process_measurement() to process the measurement you used to initialize the state vector). Once you have processed all of your measurements, you can optionally call method smooth() to perform backwards smoothing and get a best fit estimate of all of the residuals.

Tuning the filter is done through the process_noise attribute of the Dynamics class (if it has one), Measurement.covariance attribute, and the state_initializer function which can be used to set the initial state covariance.

This is certainly not the most feature rich EKF and is intended primarily for light-weight work in determining tracks of non-cooperative targets observed in images as part of the ufo package. That being said, it is general enough that you could use it for other things if you wanted to, but doing that is beyond the scope of this documentation.

Parameters:

• dynamics (Dynamics) – The Dynamics instance to use to propagate the state and covariance

• state_initializer (Callable[[Measurement, Type[State]], State]) – A callable that initializes the state given an initial measurement. This should take in the initial Measurement and the Dynamics.State type (class object) and return the initialized Dynamics.State instance with at minimum position, velocity, and covariance filled out.

• initial_measurement (Measurement | None) – Optionally provide the initial measurement. If this is not None then the initialize() method will be called. If it is None then the initialize() method will need to be called manually.

Summary of Methods

compute_residual_statistics	This method computes the mean and standard deviation of the residual history from the EKF
initialize	This method (re)initializes the EKF by setting the initial state using the state_initializer function and resetting all of the history lists.
process_measurement	This does a update step for a new measurement.
propagate_and_predict	This function integrates to the new measurement time and predicts the measurement at that time based on the propagated state.
smooth	This method performs backwards smoothing (kind-of) for all measurements processed by this EKF.