ExtendedKalmanFilter

Introduction and Overview

Implements a extended Kalman filter. For now the best documentation is my free book Kalman and Bayesian Filters in Python [1]

The test files in this directory also give you a basic idea of use, albeit without much description.

In brief, you will first construct this object, specifying the size of the state vector with dim_x and the size of the measurement vector that you will be using with dim_z. These are mostly used to perform size checks when you assign values to the various matrices. For example, if you specified dim_z=2 and then try to assign a 3x3 matrix to R (the measurement noise matrix you will get an assert exception because R should be 2x2. (If for whatever reason you need to alter the size of things midstream just use the underscore version of the matrices to assign directly: your_filter._R = a_3x3_matrix.)

After construction the filter will have default matrices created for you, but you must specify the values for each. It’s usually easiest to just overwrite them rather than assign to each element yourself. This will be clearer in the example below. All are of type numpy.array.

References

[1]Labbe, Roger. “Kalman and Bayesian Filters in Python”.
github repo:
https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python
read online:
http://nbviewer.ipython.org/github/rlabbe/Kalman-and-Bayesian-Filters-in-Python/blob/master/table_of_contents.ipynb
PDF version (often lags the two sources above)
https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python/blob/master/Kalman_and_Bayesian_Filters_in_Python.pdf

Copyright 2014 Roger R Labbe Jr.

filterpy library. http://github.com/rlabbe/filterpy

Documentation at: https://filterpy.readthedocs.org

Supporting book at: https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python

This is licensed under an MIT license. See the readme.MD file for more information.

class filterpy.kalman.ExtendedKalmanFilter(dim_x, dim_z, dim_u=0)[source]
__init__(dim_x, dim_z, dim_u=0)

Extended Kalman filter. You are responsible for setting the various state variables to reasonable values; the defaults below will not give you a functional filter.

Parameters

dim_x : int

Number of state variables for the Kalman filter. For example, if you are tracking the position and velocity of an object in two dimensions, dim_x would be 4.

This is used to set the default size of P, Q, and u

dim_z : int
Number of of measurement inputs. For example, if the sensor provides you with position in (x,y), dim_z would be 2.
K

Kalman gain

P

covariance matrix

Q

Process uncertainty

R

measurement uncertainty

S

system uncertainty in measurement space

predict(u=0)

Predict next position.

Parameters

u : np.array
Optional control vector. If non-zero, it is multiplied by B to create the control input into the system.
predict_update(z, HJacobian, Hx, u=0)

Performs the predict/update innovation of the extended Kalman filter.

Parameters

z : np.array
measurement for this step. If None, only predict step is perfomed.
HJacobian : function
function which computes the Jacobian of the H matrix (measurement function). Takes state variable (self.x) as input, returns H.
Hx : function
function which takes a state variable and returns the measurement that would correspond to that state.
u : np.array or scalar
optional control vector input to the filter.
predict_x(u=0)

predicts the next state of X. If you need to compute the next state yourself, override this function. You would need to do this, for example, if the usual Taylor expansion to generate F is not providing accurate results for you.

update(z, HJacobian, Hx, R=None)

Performs the update innovation of the extended Kalman filter.

Parameters

z : np.array
measurement for this step. If None, only predict step is perfomed.
HJacobian : function
function which computes the Jacobian of the H matrix (measurement function). Takes state variable (self.x) as input, returns H.
Hx : function
function which takes a state variable and returns the measurement that would correspond to that state.
y

measurement residual (innovation)