switchimm

Model conversion function for trackingIMM object

Syntax

state2 = switchimm(modelType1,state1,modelType2)

state2 = switchimm(___,outputFormat)

stateCov2 = switchimm(modelType1,stateCov1,modelType2)

stateCov2 = switchimm(___,outputFormat)

stateCov2 = switchimm(modelType1,stateCov1,modelType2,outputFormat,state1)

Description

State Conversion

state2 = switchimm(modelType1,state1,modelType2) converts the State specified in state1, from modelType1 state definition to modelType2 state definition.

• modelType1 –– Specifies the string name of the current motion model.

• state1 –– Specifies the State corresponding to modelType1.

• modelType2 –– Specifies the string name of the motion model to which state1 needs to be converted.

state2 = switchimm(___,outputFormat) additionally lets you specify the dimensionality and data type of the output. When not specified, state2 has the same dimensionality and data type as state1.

Linear State Covariance Conversion

stateCov2 = switchimm(modelType1,stateCov1,modelType2) converts the StateCovariance specified in stateCov1, from modelType1 state definition to modelType2 state definition. The conversion between modelType1 and modelType2 must be linear.

• modelType1 –– Specifies the string name of the current motion model.

• stateCov1 –– Specifies the StateCovariance corresponding to modelType1.

• modelType2 –– Specifies the string name of the motion model to which stateCov1 needs to be converted.

stateCov2 = switchimm(___,outputFormat) additionally lets you specify the dimensionality and data type of the output. When not specified, stateCov2 has the same dimensionality and data type as stateCov1.

Nonlinear State Covariance Conversion

stateCov2 = switchimm(modelType1,stateCov1,modelType2,outputFormat,state1) enables nonlinear conversion of StateCovariance between motion model definitions, such as between constacc and ctrv. The nonlinear conversion of state covariance requires both the current state, state1, and the state covariance, stateCov1, as inputs.

• modelType1 –– Specifies the string name of the current motion model.

• stateCov1 –– Specifies the StateCovariance corresponding to modelType1.

• modelType2 –– Specifies the string name of the motion model to which stateCov1 needs to be converted.

• outputFormat –– Specifies the dimensionality and data type of the output.

• state1 –– Specifies the State corresponding to modelType1.

(since R2024b)

Examples

Convert State from Constant Acceleration to Constant Velocity

Convert state from constant acceleration model to constant velocity model using the switchimm function.

Initialization

Set the current model to 'constacc' and the destination model to 'constvel'. The variable x1 defines the state in the current model.

modelType1 = 'constacc';
modelType2 = 'constvel';
x1 = single([1;2;3;4;5;6]);

Conversion

The switchimm function converts the 2-D constant acceleration state input to a 2-D constant velocity state output. The output has the same dimensionality and data type as the input x1.

x = switchimm(modelType1,x1,modelType2)

x = 4×1 single column vector

     1
     2
     4
     5

Convert State from Constant Acceleration to Constant Turn

Convert state from constant acceleration model to constant turn model using the switchimm function. Specify x2 as an input parameter.

Initialization

Set the current model to 'constacc' and the destination model to 'constturn'. The variable x1 defines the state in the current model. The size and data type of the output is determined by the optional input x2.

modelType1 = 'constacc';
modelType2 = 'constturn';
x1 = [1;2;3;4;5;6];
x2 = [0;0;0;0;0;0;0];

Conversion

The switchimm function converts the 2-D constant acceleration state input to a 3-D constant turn model state output. The output has the same size and data type as the input x2.

x = switchimm(modelType1,x1,modelType2,x2)

x = 7×1

     1
     2
     4
     5
     0
     0
     0

Convert from Constant Velocity State to Constant Acceleration State

Convert state and state covariance from the constant velocity model to the constant acceleration model using the switchimm function.

Set the current model to 'constvel' and the destination model to 'constacc'. Define the current state and state covariance.

modelType1 = 'constvel';
modelType2 = 'constacc';

x1 = ones(4,1);
P1 = 1e4*eye(4);

Use the switchimm function to convert the state and sate covariance from a constant velocity model to a constant acceleration model.

The function fills undefined state component with 0.

x2 = switchimm(modelType1,x1,modelType2)

x2 = 6×1

     1
     1
     0
     1
     1
     0

The function fills undefined diagonal elements of covariance with 100.

P2 = switchimm(modelType1,P1,modelType2)

P2 = 6×6

       10000           0           0           0           0           0
           0       10000           0           0           0           0
           0           0         100           0           0           0
           0           0           0       10000           0           0
           0           0           0           0       10000           0
           0           0           0           0           0         100

Convert from Constant Acceleration State to Constant Turn Rate and Velocity Magnitude State

Nonlinear conversion for state and state covariance from the constant acceleration model to the constant turn rate and velocity magnitude (CTRV) model using the switchimm function.

Set the current model to "constacc" and the destination model to "ctrv". Define the current state and state covariance.

modelType1 = "constacc";
modelType2 = "ctrv";

x1 = ones(6,1);
P1 = 10*ones(6);

Use the switchimm function to convert the state and state covariance from a constant acceleration model to a CTRV model.

The function fills undefined state component with 0.

x2 = switchimm(modelType1,x1,modelType2)

x2 = 5×1

    1.0000
    1.0000
    1.4142
   45.0000
         0

The function fills undefined diagonal elements of covariance with 100.

P2 = switchimm(modelType1,P1,modelType2,zeros(5,5),x1)

P2 = 5×5

   10.0000   10.0000   14.1421         0         0
   10.0000   10.0000   14.1421         0         0
   14.1421   14.1421   20.0000         0         0
         0         0         0         0         0
         0         0         0         0  100.0000

Input Arguments

modelType1 — Current motion model

"constvel" | "constacc" | "constturn" | "ctrv" | "singer"

Current motion model, specified as:

• "constvel" –– Constant velocity motion model.

• "constacc" –– Constant-acceleration motion model.

• "constturn" –– Constant turn-rate motion model (velocity in the xy-plane is represented with Cartesian components, Vx and Vy).

• "ctrv" –– Constant turn-rate motion model (velocity in the xy-plane is represented with velocity magnitude and direction).

• "singer" –– Singer acceleration motion model.

modelType2 — Target motion model for conversion

"constvel" | "constacc" | "constturn" | "ctrv" | "singer"

Target motion model for conversion, specified as:

• "constvel" –– Constant velocity motion model.

• "constacc" –– Constant-acceleration motion model.

• "constturn" –– Constant turn-rate motion model.

• "ctrv" –– Constant turn-rate motion model.

• "singer" –– Singer acceleration motion model.

state1 — State of current model

real column vector

State vector corresponding to the current model in modelType1, specified as an L-by-1 real vector.

The size of the state vector must fit the motion model. For example, if the modelType is "constvel", the state vector must be of size 2, 4, or 6. Similarly, if the modelType is "constacc" or "singer", the state vector must be of size 3, 6, or 9. If the modelType is "constturn" or "ctrv", the state vector must be of size 5 or 7. The relationship between model type, state size, and the space dimension is given by the following table:

modelType1	Supported Space Dimension	State size
"constvel"	1-D, 2-D, 3-D	2 ✕ Space dimension
"constacc"	1-D, 2-D, 3-D	3 ✕ Space dimension
"constturn"	2-D and 3-D	5 for 2-D space and 7 for 3-D space
"ctrv"	2-D and 3-D	5 for 2-D space and 7 for 3-D space
"singer"	1-D, 2-D, 3-D	3 ✕ Space dimension

The "constturn" and "ctrv" model type supports only 2-D and 3-D spaces, since a turn cannot be made in 1-D space. If the space dimension is computed to be 1-D, the function treats the output dimension as 2 and the values corresponding to the second dimension are set to 0. For example, run the following in the MATLAB^® command prompt:

switchimm("constvel",rand(2,1),"constturn")

Data Types: single | double

stateCov1 — State covariance of current model

matrix

State covariance matrix corresponding to the current model in modelType1, specified as an L-by-L real matrix.

Data Types: single | double

outputFormat — Specify dimensionality and data type of output state or state covariance

vector | matrix

The optional input outputFormat has the same dimensionality and data type as the output state vector or the state covariance matrix. The variable outputFormat does not contain the actual output state information, but only holds the dimensionality and data type of the output state. For example, when outputFormat is set to [0;0;0;0;0;0;0], the function determines the output state vector to be a vector of size 7 with a data type of double.

The size of the state vector must fit the motion model. For example, if the modelType is "constvel", the state vector must be of size 2, 4, or 6. Similarly, if the modelType is "constacc" or "singer", the state vector must be of size 3, 6, or 9. If the modelType is "constturn" or "ctrv", the state vector must be of size 5 or 7. The relationship between model type, state size, and the space dimension is given by the following table:

modelType1	Supported Space Dimension	State size
"constvel"	1-D, 2-D, 3-D	2 ✕ Space dimension
"constacc"	1-D, 2-D, 3-D	3 ✕ Space dimension
"constturn"	2-D and 3-D	5 for 2-D space and 7 for 3-D space
"ctrv"	2-D and 3-D	5 for 2-D space and 7 for 3-D space
"singer"	1-D, 2-D, 3-D	3 ✕ Space dimension

Example: [0;0;0;0;0;0;0]

Data Types: single | double

Output Arguments

state2 — State corresponding to modelType2

vector

State vector corresponding to the motion model specified in modelType2.

The relationship between model type, state size, and the space dimension is given by the following table:

modelType1	Supported Space Dimension	State size
"constvel"	1-D, 2-D, 3-D	2 ✕ Space dimension
"constacc"	1-D, 2-D, 3-D	3 ✕ Space dimension
"constturn"	2-D and 3-D	5 for 2-D space and 7 for 3-D space
"ctrv"	2-D and 3-D	5 for 2-D space and 7 for 3-D space
"singer"	1-D, 2-D, 3-D	3 ✕ Space dimension

If outputFormat is not specified:

Given modelType1 and state1, the function determines the input state dimension based on the relationship specified in the table. For example, if modelType1 is "constvel", and state1 is a 4-by-1 vector, the input state dimension is given by 4/2, which equals 2.

If modelType1 is "constacc" or "singer" and state1 is a 6-by-1 vector, the input state dimension is given by 6/3, which equals 2.

In this case when outputFormat is not specified, the output state2 has the same data type as state1 and the dimension is calculated using modelType1 and state1.

If outputFormat is specified:

The function calculates the output space dimension using modelType2 and outputFormat. For example, if modelType2 is "constacc" or "singer" and outputFormat is a 6-by-1 vector, the output state dimension is given by 6/3, which equals 2.

The output x has the same data type and dimensionality as outputFormat.

stateCov2 — State covariance corresponding to modelType2

matrix

State covariance matrix corresponding to the motion model specified in modelType2.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2018b

R2024b: Nonlinear state covariance conversion

Starting R2024b, the switchimm function supports the new ctrv motion model. To convert the state covariance between motion models nonlinearly, such as between constacc and ctrv, you must use the new syntax, which requires both the current state and the state covariance as inputs.