HALCON 21.05.0.0 / HALCON Operator Reference / Legacy / Tools
ClassesClasses | | Operators

read_kalmanT_read_kalmanReadKalmanReadKalmanread_kalman (Operator)

Name

read_kalmanT_read_kalmanReadKalmanReadKalmanread_kalman — Read the description file of a Kalman filter.

Warning

read_kalmanread_kalmanReadKalmanReadKalmanReadKalmanread_kalman is obsolete and is only provided for reasons of backward compatibility.

Signature

read_kalman( : : FileName : Dimension, Model, Measurement, Prediction)

Herror T_read_kalman(const Htuple FileName, Htuple* Dimension, Htuple* Model, Htuple* Measurement, Htuple* Prediction)

void ReadKalman(const HTuple& FileName, HTuple* Dimension, HTuple* Model, HTuple* Measurement, HTuple* Prediction)

static HTuple HMisc::ReadKalman(const HString& FileName, HTuple* Model, HTuple* Measurement, HTuple* Prediction)

static HTuple HMisc::ReadKalman(const char* FileName, HTuple* Model, HTuple* Measurement, HTuple* Prediction)

static HTuple HMisc::ReadKalman(const wchar_t* FileName, HTuple* Model, HTuple* Measurement, HTuple* Prediction)   (Windows only)

static void HOperatorSet.ReadKalman(HTuple fileName, out HTuple dimension, out HTuple model, out HTuple measurement, out HTuple prediction)

static HTuple HMisc.ReadKalman(string fileName, out HTuple model, out HTuple measurement, out HTuple prediction)

def read_kalman(file_name: str) -> Tuple[Sequence[int], Sequence[float], Sequence[float], Sequence[float]]

Description

The operator read_kalmanread_kalmanReadKalmanReadKalmanReadKalmanread_kalman reads the description file FileNameFileNameFileNameFileNamefileNamefile_name 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. They are successfully used in image processing, especially in the analysis of image sequences. 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

Estimate of the initial state of the system:

state and corresponding covariance matrix

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). The characteristics mentioned above can be stored in an ASCII-file and then can be read with the help of the operator read_kalmanread_kalmanReadKalmanReadKalmanReadKalmanread_kalman. This ASCII-file must have the following structure: Dimension row + content row + matrix A + matrix C + matrix Q [ + matrix G + vector u ] [ + matrix L ] + matrix R [ + matrix P0 ] [ + vector x0 ] The dimension row thereby is always of 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 DimensionDimensionDimensionDimensiondimensiondimension). The maximal dimension will hereby be limited by a system constant (= 30 for the time being).

The content row has the following form: A*C*Q*G*u*L*R*P*x* and describes the following content of the file. Instead of '*', '+' (= parameter is available) respectively '-' (= parameter is missing) have to be set. Please note that only the parameters marked by [...] in the above list may be left out in the description file. If the initial state estimate is missing (i.e. 'x-'), the components of the vector will supposed to be 0.0. If the covariance matrix of the initial state estimate is missing (i.e. 'P-'), the error will be supposed to be tremendous. In this case the matrix elements will be set to 10000.0. This value seems to be very high, however, it is only sufficient if the range of components of the state vector x is smaller to the tenth power. (r x s) matrices will be stored per row in the following form: (the spaces and line feed characters can be chosen at will),

vectors will be stored correspondingly in the following form: The following parameter values are returned by the operator read_kalmanread_kalmanReadKalmanReadKalmanReadKalmanread_kalman:

DimensionDimensionDimensionDimensiondimensiondimension:

This parameter includes the dimensions of the status vector, the measurement vector and the controller vector. DimensionDimensionDimensionDimensiondimensiondimension thereby is a vector [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. For a system without determining control (i.e. without influence “from outside”) therefore DimensionDimensionDimensionDimensiondimensiondimension = [n,m,0].

ModelModelModelModelmodelmodel:

This parameter includes the lined up matrices (vectors) A, C, Q, G, u and (if necessary) L having been stored in row-major order. ModelModelModelModelmodelmodel therefore is a vector of the length n*n + n*m + n*n + n*p + p [+ n*m]. The last summand is dropped, in case the system errors and measurement errors are not correlated, i.e. there is no value for L.

MeasurementMeasurementMeasurementMeasurementmeasurementmeasurement:

This parameter includes the matrix R which has been stored in row-major order. MeasurementMeasurementMeasurementMeasurementmeasurementmeasurement therefore is vector of the dimension m*m.

PredictionPredictionPredictionPredictionpredictionprediction:

This parameter includes the matrix (the error covariance matrix of the initial state estimate) and the initial state estimate lined up. This means, it is a vector of the length n*n + n.

Execution Information

Parameters

FileNameFileNameFileNameFileNamefileNamefile_name (input_control)  filename.read → HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Description file for a Kalman filter.

Default value: 'kalman.init' "kalman.init" "kalman.init" "kalman.init" "kalman.init" "kalman.init"

DimensionDimensionDimensionDimensiondimensiondimension (output_control)  integer-array → HTupleSequence[int]HTupleHtuple (integer) (int / long) (Hlong) (Hlong)

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

ModelModelModelModelmodelmodel (output_control)  real-array → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

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

MeasurementMeasurementMeasurementMeasurementmeasurementmeasurement (output_control)  real-array → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

The matrix R stored in row-major order.

PredictionPredictionPredictionPredictionpredictionprediction (output_control)  real-array → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

The matrix (error covariance matrix of the initial state estimate) stored in row-major order and the initial state estimate lined up.

Example (HDevelop)

* An example of the description-file:
*
* n=3 m=1 p=0
* A+C+Q+G-u-L-R+P+x+
* transition matrix A:
* 1 1 0.5
* 0 1 1
* 0 0 1
* measurement matrix C:
* 1 0 0
* system-error covariance matrix Q:
* 54.3 37.9 48.0
* 37.9 34.3 42.5
* 48.0 42.5 43.7
* measurement-error covariance matrix R:
* 1.2
* estimation-error covariance matrix (for the initial estimate) P0: \
* 0 0 0
* 0 180.5 0
* 0 0 100
* initial estimate x0:
* 0 100 0
*
* the result of read_kalman with the upper descriptionfile
* as inputparameter:
*
* Dimension   = [3,1,0]
* Model       = [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]
* Measurement = [1.2]
* Prediction  = [0.0,0.0,0.0,0.0,180.5,0.0,0.0,0.0,100.0,0.0,100.0,
*                           0.0].

Example (C)

/*An example of the description-file:                                 */
/*                                                                    */
/*n=3 m=1 p=0                                                         */
/*A+C+Q+G-u-L-R+P+x+                                                  */
/*transition matrix A:                                                */
/*1 1 0.5                                                             */
/*0 1 1                                                               */
/*0 0 1                                                               */
/*measurement matrix C:                                               */
/*1 0 0                                                               */
/*system-error covariance matrix Q:                                   */
/*54.3 37.9 48.0                                                      */
/*37.9 34.3 42.5                                                      */
/*48.0 42.5 43.7                                                      */
/*measurement-error covariance matrix R:                              */
/*1.2                                                                 */
/*estimation-error covariance matrix (for the initial estimate) P0:   */
/*0 0 0                                                               */
/*0 180.5 0                                                           */
/*0 0 100                                                             */
/*initial estimate x0:                                                */
/*0 100 0                                                             */
/*                                                                    */
/*the result of read_kalman with the upper descriptionfile            */
/*as inputparameter:                                                  */
/*                                                                    */
/*Dimension   = [3,1,0]                                               */
/*Model       = [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]   */
/*Measurement = [1.2]                                                 */
/*Prediction  = [0.0,0.0,0.0,0.0,180.5,0.0,0.0,0.0,100.0,0.0,100.0,   */
/*                          0.0]                                      */

Example (HDevelop)

* An example of the description-file:
*
* n=3 m=1 p=0
* A+C+Q+G-u-L-R+P+x+
* transition matrix A:
* 1 1 0.5
* 0 1 1
* 0 0 1
* measurement matrix C:
* 1 0 0
* system-error covariance matrix Q:
* 54.3 37.9 48.0
* 37.9 34.3 42.5
* 48.0 42.5 43.7
* measurement-error covariance matrix R:
* 1.2
* estimation-error covariance matrix (for the initial estimate) P0: \
* 0 0 0
* 0 180.5 0
* 0 0 100
* initial estimate x0:
* 0 100 0
*
* the result of read_kalman with the upper descriptionfile
* as inputparameter:
*
* Dimension   = [3,1,0]
* Model       = [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]
* Measurement = [1.2]
* Prediction  = [0.0,0.0,0.0,0.0,180.5,0.0,0.0,0.0,100.0,0.0,100.0,
*                           0.0].

Example (HDevelop)

* An example of the description-file:
*
* n=3 m=1 p=0
* A+C+Q+G-u-L-R+P+x+
* transition matrix A:
* 1 1 0.5
* 0 1 1
* 0 0 1
* measurement matrix C:
* 1 0 0
* system-error covariance matrix Q:
* 54.3 37.9 48.0
* 37.9 34.3 42.5
* 48.0 42.5 43.7
* measurement-error covariance matrix R:
* 1.2
* estimation-error covariance matrix (for the initial estimate) P0: \
* 0 0 0
* 0 180.5 0
* 0 0 100
* initial estimate x0:
* 0 100 0
*
* the result of read_kalman with the upper descriptionfile
* as inputparameter:
*
* Dimension   = [3,1,0]
* Model       = [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]
* Measurement = [1.2]
* Prediction  = [0.0,0.0,0.0,0.0,180.5,0.0,0.0,0.0,100.0,0.0,100.0,
*                           0.0].

Example (HDevelop)

* An example of the description-file:
*
* n=3 m=1 p=0
* A+C+Q+G-u-L-R+P+x+
* transition matrix A:
* 1 1 0.5
* 0 1 1
* 0 0 1
* measurement matrix C:
* 1 0 0
* system-error covariance matrix Q:
* 54.3 37.9 48.0
* 37.9 34.3 42.5
* 48.0 42.5 43.7
* measurement-error covariance matrix R:
* 1.2
* estimation-error covariance matrix (for the initial estimate) P0: \
* 0 0 0
* 0 180.5 0
* 0 0 100
* initial estimate x0:
* 0 100 0
*
* the result of read_kalman with the upper descriptionfile
* as inputparameter:
*
* Dimension   = [3,1,0]
* Model       = [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]
* Measurement = [1.2]
* Prediction  = [0.0,0.0,0.0,0.0,180.5,0.0,0.0,0.0,100.0,0.0,100.0,
*                           0.0].

Result

If the description file is readable and correct, the operator read_kalmanread_kalmanReadKalmanReadKalmanReadKalmanread_kalman returns the value TRUE. Otherwise an exception is raised.

Possible Successors

filter_kalmanfilter_kalmanFilterKalmanFilterKalmanFilterKalmanfilter_kalman

See also

update_kalmanupdate_kalmanUpdateKalmanUpdateKalmanUpdateKalmanupdate_kalman, filter_kalmanfilter_kalmanFilterKalmanFilterKalmanFilterKalmanfilter_kalman

Module

Foundation

ClassesClasses | | Operators
HALCON Operator Reference 21.05.0.0 Copyright © 1996-2021 MVTec Software GmbH
Follow us on