trackingIMM

Interacting multiple model (IMM) filter for object tracking

Description

The trackingIMM object represents an interacting multiple model (IMM) filter designed for tracking objects that are highly maneuverable. Use the filter to predict the future location of an object, to reduce noise in the detected location, or help associate multiple object detections with their tracks.

The IMM filter deals with the multiple motion models in the Bayesian framework. This method resolves the target motion uncertainty by using multiple models at a time for a maneuvering target. The IMM algorithm processes all the models simultaneously and switches between models according to their updated weights.

Creation

Syntax

imm = trackingIMM

imm = trackingIMM(trackingFilters)

imm = trackingIMM(trackingFilters,modelConversionFcn)

imm = trackingIMM(trackingFilters,modelConversionFcn,transitionProbabilities)

imm = trackingIMM(___,Name,Value)

Description

imm = trackingIMM returns an IMM filter object with default tracking filters {trackingEKF,trackingEKF,trackingEKF} with the motion models set as constant velocity, constant acceleration, and constant turn, respectively. The filter uses the default conversion function, @switchimm.

imm = trackingIMM(trackingFilters) specifies the TrackingFilters property and sets all other properties to default values.

imm = trackingIMM(trackingFilters,modelConversionFcn) also specifies the ModelConversionFcn property.

imm = trackingIMM(trackingFilters,modelConversionFcn,transitionProbabilities) also specifies the TransitionProbabilities property.

imm = trackingIMM(___,Name,Value) specifies the properties of the filter using one or more Name,Value pair arguments. Any unspecified properties take default values. Specify any other input arguments from previous syntaxes first.

Properties

State — Filter state

[0;0;0;0;0;0] (default) | real-valued M-element vector

Filter state, specified as a real-valued M-element vector. Specify the initial state when creating the object using name-value pairs.

The definition of the State vector in this property is the same as the state definition of the first tracking filter specified in the TrackingFilters property. The state definition of a tracking filter is governed by the motion model or state transition function used in the filter.

Data Types: single | double

StateCovariance — State estimation error covariance

diag([1 100 1 100 1 100]) (default) | M-by-M matrix | scalar

State error covariance, specified as an M-by-M matrix, where M is the size of the filter state. A scalar input is extended to an M-by-M matrix. The covariance matrix represents the uncertainty in the filter state. Specify the initial state covariance when creating the object using name-value pairs.

Example: eye(6)

Data Types: single | double

TrackingFilters — List of filters

{trackingEKF,trackingEKF,trackingEKF} (default) | cell array of tracking filters

List of filters, specified as a cell array of tracking filters. By default, the filters have equal probability. Specify ModelProbabilities if the filters have different probabilities.

If you want a trackingIMM filter with single-precision floating-point variables, specify the filters using single-precision. For example,

filter1 = trackingEKF('StateTransitionFcn',@constvel,'State',single([1;2;3;4]));
filter2 = trackingEKF('StateTransitionFcn',@constvel,'State',single([2;3;3;1]));
filter = trackingIMM({filter1,filter2})

Data Types: cell

HasMeasurementWrapping — Wrapping of measurement residuals

Read-only: K-element logical vector

This property is read-only.

Wrapping of measurement residuals in the filter, specified as a K-element logical vector, where K is the number of underlying tracking filters specified in the TrackingFilters property. If an underlying filter enables measurement wrapping, then the corresponding element is a 1 (true). Otherwise, it is 0 (false).

ModelConversionFcn — Function to convert state or state covariance

@switchimm (default) | function handle

Function to convert the state or state covariance, specified as a function handle. The function converts the state or state covariance from one model type to another. The function signature is:

function x2 = modelConversionFcn(modelType1,x1,modelType2)

The modelType1 and modelType2 inputs are the names of the two model names. x1 specifies the State or StateCovariance of the first model. x2 outputs the State or StateCovariance

Data Types: function_handle

TransitionProbabilities — Probability of filter model transitions

0.9 (default) | positive real scalar | L-element vector | L-by-L matrix

Probability of filter model transitions, specified as a positive real scalar, L-element vector, or L-by-L matrix, where L is the number of filters:

• When specified as a scalar, the probability is uniform for staying on each filter. The remaining probability (1-p) is distributed evenly across the other motion models.

• When specified as a vector, each element defines the probability of staying on each filter. The remaining probability (1-p) is distributed evenly across the other motion models evenly.

• When specified as a matrix, the (j,k) element defines the probability of transitioning from the jth filter to the kth filter. All elements must lie on the interval [0,1], and each row must sum to 1.

The transition probability defined for each model corresponds to the probability that the filter switches from this model to another model in one second.

Example: 0.75

Data Types: single | double

MeasurementNoise — Measurement noise covariance

1 (default) | positive scalar | positive-definite real-valued matrix

Measurement noise covariance, specified as a positive scalar or positive-definite real-valued matrix. When specified as a scalar, the matrix is a multiple of the N-by-N identity matrix. N is the size of the measurement vector.

Specify MeasurementNoise before any call to the correct function.

Example: 0.2

ModelProbabilities — Weight of each filter

1/L*ones(L) (default) | vector of probabilities between 0 and 1

Weight of each filter, specified as a vector of probabilities from 0 to 1. By default, the weight of each component of the filter is equal. L is the number of filters. The IMM filter updates the weight of each filter in the prediction step.

Data Types: single | double

EnableSmoothing — Enable state smoothing

false (default) | true

Enable state smoothing, specified as false or true. When specified as true, you can

• Use the smooth function to smooth the state estimates in the previous time steps.

• Specify the maximum number of smoothing steps using the MaxNumSmoothingSteps property of the filter.

Note

The smoothing capability is only supported when the trackingIMM object is configured with Gaussian filters.

MaxNumSmoothingSteps — Maximum number of smoothing steps

5 (default) | positive integer

Maximum number of backward smoothing steps, specified as a positive integer.

Dependencies

To enable this property, set the EnableSmoothing property to true.

MaxNumOOSMSteps — Maximum number of out-of-sequence measurement steps

0 (default) | nonnegative integer

Maximum number of out-of-sequence measurement (OOSM) steps, specified as a nonnegative integer.

• Setting this property to 0 disables the OOSM retrodiction capability of the filter object.

• Setting this property to a positive integer enables the OOSM retrodiction capability of the filter object. When you set this property as N>1, the filter object saves the past state and state covariance history up to the last N+1 corrections. You can use the OOSM and the retrodict and retroCorrect (or retroCorrectJPDA for multiple OOSMs) object functions to reduce the uncertainty of the estimated state.

Increasing the value of this property increases the amount of memory that must be allocated for the state history, but enables you to process OOSMs that arrive after longer delays. Note that the effect of the uncertainty reduction using an OOSM decreases as the delay becomes longer.

Note

When you specify the MaxNumOOSMSteps property for the trackingIMM object, the MaxNumOOSMSteps properties of the underlying filters specified in the TrackingFilters property are neglected. For the purpose of memory saving, specify the MaxNumOOSMSteps properties of the underlying filters as 0.

ModelNames — Filter model names

character vector | string scalar

Names of the models used by the filter when calling ModelConversionFcn, specified as a character vector or string scalar. You can provide names of each filter during the construction of the object. By default, the trackingIMM infers these model names from the TrackingFilters property. After construction, this property is read-only.

Object Functions

predict	Predict state and state estimation error covariance of tracking filter
correct	Correct state and state estimation error covariance using tracking filter
correctjpda	Correct state and state estimation error covariance using tracking filter and JPDA
distance	Distances between current and predicted measurements of tracking filter
likelihood	Likelihood of measurement from tracking filter
clone	Create duplicate tracking filter
initialize	Initialize state and covariance of tracking filter
smooth	Backward smooth state estimates of trackingIMM filter
retrodict	Retrodict filter to previous time step
retroCorrect	Correct filter with OOSM using retrodiction
retroCorrectJPDA	Correct tracking filter with OOSMs using JPDA-based algorithm
tunableProperties	Get tunable properties of filter
setTunedProperties	Set properties to tuned values
setMeasurementSizes	Sets the sizes of the measurement and measurement noise

Examples

Run trackingIMM Filter

This example shows how to create and run an interacting multiple model (IMM) filter using a trackingIMM object. Call the predict and correct functions to track an object and correct the state estimate based on measurements.

Create the filter. Use name-value pairs to specify additional properties of the object.

detection = objectDetection(0, [1;1;0], 'MeasurementNoise', [1 0.2 0; 0.2 2 0; 0 0 1]);
filter = {initctekf(detection);initcvekf(detection)};
modelConv = @switchimm;
transProb = [0.9,0.9];
imm = trackingIMM('State',[1;1;3;1;5;1;1],'StateCovariance',eye(7),...
     'TransitionProbabilities',transProb,'TrackingFilters',filter,...
     'ModelConversionFcn',modelConv);

Call predict to get the predicted state and covariance of the filter. Use a 0.5 sec time step.

[xPred,pPred] = predict(imm,0.5);

Call correct with a given measurement.

meas = [1;1;0];
[xCorr,pCorr] = correct(imm,meas);

Continue to predict the filter state. Specify the desired time step in seconds if necessary.

[xPred,pPred] = predict(imm);         % Predict over 1 second
[xPred,pPred] = predict(imm,2);       % Predict over 2 seconds

Multi-Model Tracking with Custom Motion Models using trackingIMM

This example shows the creation and execution of an IMM (Interacting Multiple Model) filter for two linear Kalman filters with custom motion models.

Create two linear Kalman filters, filter1 and filter2, with custom motion models. filter1 has a state of [x;y;vx;vy] and assumes a constant velocity transition in the x- and y-directions. filter2 has a state of [x;vx;ax;y] and assumes a constant acceleration in the x-direction and remains stationary in the y-direction.

dT=0.1;
filter1 = trackingKF('MotionModel','Custom', ...
    'StateTransitionModel',[1 0 dT 0;0 1 0 dT;0 0 1 0;0 0 0 1], ...
    'MeasurementModel',[1 0 0 0;0 1 0 0]);

filter2 = trackingKF('MotionModel','Custom', ...
    'StateTransitionModel',[1 dT dT^2/2 0;0 1 dT 0;0 0 1 0;0 0 0 1], ...
    'MeasurementModel',[1 0 0 0;0 0 0 1]);

Create an IMM filter with filter1, filter2, and a custom ModelConversionFcn. Initialize and tune the IMM filter by setting appropriate initial state, state covariance, and process noise.

imm = trackingIMM({filter1;filter2},'ModelNames',{'cv','ca'},...
    'ModelConversionFcn',@CustomLinearModelConversionFcn);
initialize(imm,zeros(4,1),blkdiag(1,1,10,10));
imm.TrackingFilters{2}.ProcessNoise(4,4) = 10;

Generate a target with an initial position of [0;0], and define its trajectory to have constant acceleration in the x-direction and constant velocity in the y-direction. Use the target data to correct the IMM filter every 0.1s for 20s.

x = 0;
y = 0;
vx = 3.66;
vy = 1.83;
ax = 0.53;
for i = 1:200
    x = x + vx*dT + ax*dT^2/2;
    vx = vx + ax*dT;
    y = y + vy*dT;
    predict(imm);
    correct(imm,[x;y]);
end

Display the predicted state for the IMM filter.

disp(imm.State)

  179.1699
   36.5911
   13.7177
    1.5239

Display the predicted states for the TrackingFilters and ModelProbabilities.

disp(imm.TrackingFilters{1}.State)

  179.1697
   36.5919
   13.7147
    1.6887

disp(imm.TrackingFilters{2}.State)

  179.1711
   13.7455
    0.0931
   36.5834

disp(imm.ModelProbabilities)

    0.9024
    0.0976

function x2 = CustomLinearModelConversionFcn(modelName1,x1,modelName2,x2)
if strcmpi(modelName1,modelName2)
    x2 = x1;
    return;
end
if strcmpi(modelName1,'cv') && strcmpi(modelName2,'ca')
    % cv to ca conversion
    if isvector(x2)
        x2(1) = x1(1); % x
        x2(2) = x1(3); % vx
        x2(3) = 0; % ax
        x2(4) = x1(2); % y
    else
        x2([1 2 4],[1 2 4]) = x1([1 3 2],[1 3 2]);
        x2(3,3) = 100;
    end
elseif strcmpi(modelName1,'ca') && strcmpi(modelName2,'cv')
    % ca to cv conversion
    if isvector(x2)
        x2(1) = x1(1); % x
        x2(2) = x1(4); % y
        x2(3) = x1(2); % vx
        x2(4) = 0; % vy
    else
        x2([1 2 3],[1 2 3]) = x1([1 4 2],[1 4 2]);
        x2(4,4) = 100;
    end
else
    disp('Model Name must be cv or ca');
end
end

References

[1] Bar-Shalom, Yaakov, Peter K. Willett, and Xin Tian. Tracking and data fusion. Storrs, CT, USA:: YBS publishing, 2011.

[2] Blackman, Samuel, and Robert Popoli. "Design and analysis of modern tracking systems." Norwood, MA: Artech House, 1999.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The filter supports strict single-precision code generation when it is configured with either trackingEKF, trackingUKF, or trackingCKF objects set in single-precision.

  For details, see Generate Code with Strict Single-Precision and Non-Dynamic Memory Allocation.

• The filter supports non-dynamic memory allocation code generation when it is configured with either trackingEKF, trackingUKF, or trackingCKF objects.

  For details, see Generate Code with Strict Single-Precision and Non-Dynamic Memory Allocation.

Version History

Introduced in R2018b

R2024a: Specify model names

You can specify model names of each filter by using the new ModelNames property. Using specified model names allows multi-model tracking with custom motion models.