My Project
Public Member Functions | List of all members
UnscentedKalman Class Reference

Implementation of unscented kalman filter (UKF) for filtering non-linear processes. More...

#include <UnscentedKalman.h>

Public Member Functions

 UnscentedKalman (int state_n, int obs_n, int state_k=0, double alpha=0.001, double beta=2.0)
 Initializes Unscented Kalman filter. More...
 
cv::Mat getState ()
 Returns the process state vector. More...
 
cv::Mat getStateCovariance ()
 Returns the process state covariance matrix. More...
 
void initialize ()
 (Re-)initialize UKF internal state. More...
 
void predict (UnscentedProcess *process_model)
 Updated the state by predicting. More...
 
void update (UnscentedObservation *observation)
 Updates the state by an observation. More...
 

Detailed Description

Implementation of unscented kalman filter (UKF) for filtering non-linear processes.

See http://www.cs.unc.edu/~welch/kalman/media/pdf/Julier1997_SPIE_KF.pdf for more details about UKF.

The UKF estimates a process state (represented by a vector) using observations of the process. Observations are some derivate of the process state as usually the process state cannot be directly observed.

UnscentedProcess models the process by predicting the next filter state based on the current filter state.

UnscentedObservation models the observation by predicting observation results based on the current filter state.

UnscentedKalman holds the estimated process state vector and its covariance matrix. The new process state can be estimated using predict and update methods.

The current implementation does not separate process noise elements from the process state vector. It is therefore the responsibility of the user to include noise terms into process state and state covariance.

class MyUnscentedProcess : public UnscentedProcess {
void f(cv::Mat& state) { // compute new state }
cv::Mat getProcessNoise() { return _noise; }
} myProcess;
class MyUnscentedObservation : public UnscentedObservation {
void h(cv::Mat& z, cv::Mat& state) { // compute measurement vector z from state }
cv::Mat getObservation() { return _obs; }
cv::Mat getObservationNoise() { return _noise; }
} myObservation;
int state_n = NUMBER_OF_ELEMENTS_IN_PROCESS_STATE_VECTOR;
int obs_n = NUMBER_OF_ELEMENTS_IN_PROCESS_OBSERVATION_VECTOR;
int state_k = NUMBER_OF_PROCESS_NOISE_ELEMENTS; //TODO: Not supported at the moment.
UnscentedKalman ukf(state_n, obs_n, state_k);
initializeState(ukf.getState(), ukf.getStateCovariance());
ukf.initialize();
while (1) {
ukf.predict(&myProcess);
// measure new observation.
ukf.update(&myObservation);
cv::Mat state = ukf.getState();
// unpack state information from the state vector and do something with it.
}
UnscentedKalman(int state_n, int obs_n, int state_k=0, double alpha=0.001, double beta=2.0)
Initializes Unscented Kalman filter.

Definition at line 97 of file UnscentedKalman.h.

Constructor & Destructor Documentation

◆ UnscentedKalman()

UnscentedKalman ( int  state_n,
int  obs_n,
int  state_k = 0,
double  alpha = 0.001,
double  beta = 2.0 
)

Initializes Unscented Kalman filter.

Initializes Unscented Kalman filter. The state vector returned by getState and state covariance matrix returned by getStateCovariance should be initialized before using the filter.

Separate state noise vector is currently unsupported. The user should include noise terms in the state vector directly. Set the noise mean into state vector and noise variance into state covariance matrix.

Parameters
state_nThe number of elements in process state vector.
obs_nThe number of elements in observation vector.
state_kThe number of noise elements used in the process model. TODO: This is currently unsupported.
alphaSpread of sigma points.
betaPrior knowlegde about the distribution (2 for Gaussian).

Member Function Documentation

◆ getState()

cv::Mat getState ( )
inline

Returns the process state vector.

The returned state vector contains the current state of the process. The returned vector may be modified if the current process state is known, for example in initialization phase. If the vector is modified, initialize method must be called before calling either predict or update methods.

Returns
A vector of state_n elements.

Definition at line 175 of file UnscentedKalman.h.

◆ getStateCovariance()

cv::Mat getStateCovariance ( )
inline

Returns the process state covariance matrix.

The returned matrix contains the current state covariance. The matrix may be modified if the covariance is known, for example in initialization phase. If the matrix is modified, initialize method must be called before calling either predict of update methods.

Returns
state_n by state_n covariance matrix.

Definition at line 190 of file UnscentedKalman.h.

◆ initialize()

void initialize ( )

(Re-)initialize UKF internal state.

Must be called before predict/update when ever state or state co-variance are changed.

◆ predict()

void predict ( UnscentedProcess process_model)

Updated the state by predicting.

Updates the process state by predicting new state from the current state. Normally each predict call is followed with a call to update method.

Parameters
process_modelThe model implementation that is used to predict the next state.

◆ update()

void update ( UnscentedObservation observation)

Updates the state by an observation.

Updates the process state by a measurement that indirectly observed the correct process state. The observation implementation needs to hold the current measurement data and implement a transformation from process state into measurement (the UnscentedObservation::h method).

Parameters
observationThe observation implementation the is used to update the current state.

The documentation for this class was generated from the following file: