HALCON Website / HALCON Operator Reference / Tools / Kalman Filter
ClassesClassesClassesClasses | | | | Operators

update_kalmanT_update_kalmanUpdateKalmanupdate_kalmanUpdateKalmanUpdateKalman (Operator)

Name

update_kalmanT_update_kalmanUpdateKalmanupdate_kalmanUpdateKalmanUpdateKalman — Read an update file of a Kalman filter.

Signature

update_kalman( : : FileName, DimensionIn, ModelIn, MeasurementIn : DimensionOut, ModelOut, MeasurementOut)

Herror T_update_kalman(const Htuple FileName, const Htuple DimensionIn, const Htuple ModelIn, const Htuple MeasurementIn, Htuple* DimensionOut, Htuple* ModelOut, Htuple* MeasurementOut)

Herror update_kalman(const HTuple& FileName, const HTuple& DimensionIn, const HTuple& ModelIn, const HTuple& MeasurementIn, HTuple* DimensionOut, HTuple* ModelOut, HTuple* MeasurementOut)

void UpdateKalman(const HTuple& FileName, const HTuple& DimensionIn, const HTuple& ModelIn, const HTuple& MeasurementIn, HTuple* DimensionOut, HTuple* ModelOut, HTuple* MeasurementOut)

static HTuple HMisc::UpdateKalman(const HString& FileName, const HTuple& DimensionIn, const HTuple& ModelIn, const HTuple& MeasurementIn, HTuple* ModelOut, HTuple* MeasurementOut)

static HTuple HMisc::UpdateKalman(const char* FileName, const HTuple& DimensionIn, const HTuple& ModelIn, const HTuple& MeasurementIn, HTuple* ModelOut, HTuple* MeasurementOut)

void HOperatorSetX.UpdateKalman(
[in] VARIANT FileName, [in] VARIANT DimensionIn, [in] VARIANT ModelIn, [in] VARIANT MeasurementIn, [out] VARIANT* DimensionOut, [out] VARIANT* ModelOut, [out] VARIANT* MeasurementOut)

VARIANT HMiscX.UpdateKalman(
[in] BSTR FileName, [in] VARIANT DimensionIn, [in] VARIANT ModelIn, [in] VARIANT MeasurementIn, [out] VARIANT* ModelOut, [out] VARIANT* MeasurementOut)

static void HOperatorSet.UpdateKalman(HTuple fileName, HTuple dimensionIn, HTuple modelIn, HTuple measurementIn, out HTuple dimensionOut, out HTuple modelOut, out HTuple measurementOut)

static HTuple HMisc.UpdateKalman(string fileName, HTuple dimensionIn, HTuple modelIn, HTuple measurementIn, out HTuple modelOut, out HTuple measurementOut)

Description

The operator update_kalmanupdate_kalmanUpdateKalmanupdate_kalmanUpdateKalmanUpdateKalman reads the update file FileNameFileNameFileNameFileNameFileNamefileName of a Kalman filter. Kalman filters return an estimate of the current state (or even the prediction of a future state) of a discrete, stochastically disturbed, linear system.

A Kalman filtering is based on a mathematical model of the system to be examined which at any point in time has the following characteristics:

Model parameter:

transition matrix A, control matrix G including the controller output u and the measurement matrix C

Model stochastic:

system-error covariance matrix Q, system-error - measurement-error covariance matrix L and measurement-error covariance matrix R

Measurement vector:

y

History of the system:

extrapolation vector x* and extrapolation-error covariance matrix P*

Many systems do not need entries “from outside” and therefore G and u can be dropped. Further, system errors and measurement errors are normally not correlated (L is dropped). Some of the characteristics mentioned above may change dynamically (from one iteration to the next). The operator update_kalmanupdate_kalmanUpdateKalmanupdate_kalmanUpdateKalmanUpdateKalman serves to modify parts of the system according to an update file (ASCII) with the following structure (see also read_kalmanread_kalmanReadKalmanread_kalmanReadKalmanReadKalman): 

      Dimension row
      + content row
      + matrix A
      + matrix C
      + matrix Q
      + matrix G + vector u
      + matrix L
      + matrix R

The dimension row thereby has the following form: 

      n = <integer> m = <integer> p = <integer>

whereby n indicates the number of the state variables, m the number of the measurement values and p the number of the controller members (see also DimensionInDimensionInDimensionInDimensionInDimensionIndimensionIn / DimensionOutDimensionOutDimensionOutDimensionOutDimensionOutdimensionOut). The maximal dimension will hereby be limited by a system constant (= 30 for the time being). As in this case changes should take effect at a valid model, the dimensions n and m are invariant (and will only be indicated for purposes of control).

The content row has the following form: 

       A*C*Q*G*u*L*R*

and describes the further content of the file. Instead of '*', '+' (= parameter is available) respectively '-' (= parameter is missing) has to be set. In contrast to description files for read_kalmanread_kalmanReadKalmanread_kalmanReadKalmanReadKalman, the system description needs not be complete in this case. Only those parts of the system which are changed must be indicated. The indication of estimated values is unnecessary, as these values must stem from the latest filtering according to the structure of the filter.

(r x s) matrices will be stored in row-major order in the following form: 

        <comment, i.e. string>
        <a11> <a12> ... <a1s>
          .     .         .
        <ar1> <ar2> ... <ars>

(the spaces/line feed characters can be chosen at will),

vectors will be stored correspondingly in the following form: 

        <comment, i.e. string>
        <a1> ... <ak>

The following parameter values of the operator read_kalmanread_kalmanReadKalmanread_kalmanReadKalmanReadKalman will be changed:

DimensionInDimensionInDimensionInDimensionInDimensionIndimensionIn / DimensionOutDimensionOutDimensionOutDimensionOutDimensionOutdimensionOut:

These parameters include the dimensions of the state vector, measurement vector and controller vector and therefore are vectors [n,m,p], whereby n indicates the number of the state variables, m the number of the measurement values and p the number of the controller members. n and m are invariant for a given system, i.e. they must not differ from corresponding input values of the update file. For a system without without influence “from outside” 'p = 0'"p = 0""p = 0""p = 0""p = 0""p = 0".

ModelInModelInModelInModelInModelInmodelIn / ModelOutModelOutModelOutModelOutModelOutmodelOut:

These parameters include the lined up matrices (vectors) A, C, Q, G, u and if necessary L which have been stored in row-major order. ModelInModelInModelInModelInModelInmodelIn / ModelOutModelOutModelOutModelOutModelOutmodelOut therefore are vectors of the length n*n + n*m + n*n + n*p + p [+ n*m]. The last summand is dropped if system errors and measurement errors are not correlated, i.e. no value has been set for L.

MeasurementInMeasurementInMeasurementInMeasurementInMeasurementInmeasurementIn / MeasurementOutMeasurementOutMeasurementOutMeasurementOutMeasurementOutmeasurementOut:

These parameters include the matrix R stored in row-major order, and therefore are vectors of the dimension m*m.

Parallelization

Parameters

FileNameFileNameFileNameFileNameFileNamefileName (input_control)  filename.read → HTupleHTupleHTupleVARIANTHtuple (string) (string) (HString) (char*) (BSTR) (char*)

Update file for a Kalman filter.

Default value: 'kalman.updt' "kalman.updt" "kalman.updt" "kalman.updt" "kalman.updt" "kalman.updt"

DimensionInDimensionInDimensionInDimensionInDimensionIndimensionIn (input_control)  integer-array → HTupleHTupleHTupleVARIANTHtuple (integer) (int / long) (Hlong) (Hlong) (Hlong) (Hlong)

The dimensions of the state vector, measurement vector and controller vector.

Default value: [3,1,0]

Typical range of values: 0 ≤ DimensionIn DimensionIn DimensionIn DimensionIn DimensionIn dimensionIn ≤ 30

ModelInModelInModelInModelInModelInmodelIn (input_control)  real-array → HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (double) (double) (double)

The lined up matrices A,C,Q, possibly G and u, and if necessary L which all have been stored in row-major order.

Default value: [1.0,1.0,0.5,0.0,1.0,1.0,0.0,0.0,1.0,1.0,0.0,0.0,54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]

Typical range of values: 0.0 ≤ ModelIn ModelIn ModelIn ModelIn ModelIn modelIn ≤ 10000.0

MeasurementInMeasurementInMeasurementInMeasurementInMeasurementInmeasurementIn (input_control)  real-array → HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (double) (double) (double)

The matrix R stored in row-major order.

Default value: [1,2]

Typical range of values: 0.0 ≤ MeasurementIn MeasurementIn MeasurementIn MeasurementIn MeasurementIn measurementIn ≤ 10000.0

DimensionOutDimensionOutDimensionOutDimensionOutDimensionOutdimensionOut (output_control)  integer-array → HTupleHTupleHTupleVARIANTHtuple (integer) (int / long) (Hlong) (Hlong) (Hlong) (Hlong)

The dimensions of the state vector, measurement vector and controller vector.

ModelOutModelOutModelOutModelOutModelOutmodelOut (output_control)  real-array → HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (double) (double) (double)

The lined up matrices A,C,Q, possibly G and u, and if necessary L which all have been stored in row-major order.

MeasurementOutMeasurementOutMeasurementOutMeasurementOutMeasurementOutmeasurementOut (output_control)  real-array → HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (double) (double) (double)

The matrix R stored in row-major order.

Example (HDevelop)

* The following values are describing the system
*
* DimensionIn   = [3,1,0]
* ModelIn       = [1.0,1.0,0.5,0.0,1.0,1.0,0.0,0.0,1.0,1.0,0.0,0.0,
*                       54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]
* MeasurementIn = [1,2]
*
* An example of the Updatefile:
*
* n=3 m=1 p=0
* A+C-Q-G-u-L-R-
* transitions at time t=15:
* 2 1 1
* 0 2 2
* 0 0 2
*
* the results of update_kalman:
*
* DimensionOut   = [3,1,0]
* ModelOut       = [2.0,1.0,1.0,0.0,2.0,2.0,0.0,0.0,2.0,1.0,0.0,0.0,
*                        54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]
* MeasurementOut = [1.2]

Example (C)

/* The following values are describing the system                      */
/*                                                                     */
/*DimensionIn   = [3,1,0]                                              */
/*ModelIn       = [1.0,1.0,0.5,0.0,1.0,1.0,0.0,0.0,1.0,1.0,0.0,0.0,    */
/*                      54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]  */
/*MeasurementIn = [1,2]                                                */
/*                                                                     */
/*An example of the Updatefile:                                        */
/*                                                                     */
/*n=3 m=1 p=0                                                          */
/*A+C-Q-G-u-L-R-                                                       */
/*transitions at time t=15:                                            */
/*2 1 1                                                                */
/*0 2 2                                                                */
/*0 0 2                                                                */
/*                                                                     */
/*the results of update_kalman:                                        */
/*                                                                     */
/*DimensionOut   = [3,1,0]                                             */
/*ModelOut       = [2.0,1.0,1.0,0.0,2.0,2.0,0.0,0.0,2.0,1.0,0.0,0.0,   */
/*                       54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7] */
/*MeasurementOut = [1.2]                                               */

Example (HDevelop)

* The following values are describing the system
*
* DimensionIn   = [3,1,0]
* ModelIn       = [1.0,1.0,0.5,0.0,1.0,1.0,0.0,0.0,1.0,1.0,0.0,0.0,
*                       54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]
* MeasurementIn = [1,2]
*
* An example of the Updatefile:
*
* n=3 m=1 p=0
* A+C-Q-G-u-L-R-
* transitions at time t=15:
* 2 1 1
* 0 2 2
* 0 0 2
*
* the results of update_kalman:
*
* DimensionOut   = [3,1,0]
* ModelOut       = [2.0,1.0,1.0,0.0,2.0,2.0,0.0,0.0,2.0,1.0,0.0,0.0,
*                        54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]
* MeasurementOut = [1.2]

Example (HDevelop)

* The following values are describing the system
*
* DimensionIn   = [3,1,0]
* ModelIn       = [1.0,1.0,0.5,0.0,1.0,1.0,0.0,0.0,1.0,1.0,0.0,0.0,
*                       54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]
* MeasurementIn = [1,2]
*
* An example of the Updatefile:
*
* n=3 m=1 p=0
* A+C-Q-G-u-L-R-
* transitions at time t=15:
* 2 1 1
* 0 2 2
* 0 0 2
*
* the results of update_kalman:
*
* DimensionOut   = [3,1,0]
* ModelOut       = [2.0,1.0,1.0,0.0,2.0,2.0,0.0,0.0,2.0,1.0,0.0,0.0,
*                        54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]
* MeasurementOut = [1.2]

Example (HDevelop)

* The following values are describing the system
*
* DimensionIn   = [3,1,0]
* ModelIn       = [1.0,1.0,0.5,0.0,1.0,1.0,0.0,0.0,1.0,1.0,0.0,0.0,
*                       54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]
* MeasurementIn = [1,2]
*
* An example of the Updatefile:
*
* n=3 m=1 p=0
* A+C-Q-G-u-L-R-
* transitions at time t=15:
* 2 1 1
* 0 2 2
* 0 0 2
*
* the results of update_kalman:
*
* DimensionOut   = [3,1,0]
* ModelOut       = [2.0,1.0,1.0,0.0,2.0,2.0,0.0,0.0,2.0,1.0,0.0,0.0,
*                        54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]
* MeasurementOut = [1.2]

Example (HDevelop)

* The following values are describing the system
*
* DimensionIn   = [3,1,0]
* ModelIn       = [1.0,1.0,0.5,0.0,1.0,1.0,0.0,0.0,1.0,1.0,0.0,0.0,
*                       54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]
* MeasurementIn = [1,2]
*
* An example of the Updatefile:
*
* n=3 m=1 p=0
* A+C-Q-G-u-L-R-
* transitions at time t=15:
* 2 1 1
* 0 2 2
* 0 0 2
*
* the results of update_kalman:
*
* DimensionOut   = [3,1,0]
* ModelOut       = [2.0,1.0,1.0,0.0,2.0,2.0,0.0,0.0,2.0,1.0,0.0,0.0,
*                        54.3,37.9,48.0,37.9,34.3,42.5,48.0,42.5,43.7]
* MeasurementOut = [1.2]

Result

If the update file is readable and correct, the operator update_kalmanupdate_kalmanUpdateKalmanupdate_kalmanUpdateKalmanUpdateKalman returns the value 2 (H_MSG_TRUE). Otherwise an exception is raised.

Possible Successors

filter_kalmanfilter_kalmanFilterKalmanfilter_kalmanFilterKalmanFilterKalman

See also

read_kalmanread_kalmanReadKalmanread_kalmanReadKalmanReadKalman, filter_kalmanfilter_kalmanFilterKalmanfilter_kalmanFilterKalmanFilterKalman

Module

Foundation

ClassesClassesClassesClasses | | | | Operators
HALCON Operator Reference 11.0.5 Copyright © 1996-2015 MVTec Software GmbH