Main Content

trackingFilterTuner

Tracking filter tuner

Description

The trackingFilterTuner object creates a tracking filter tuner that tunes the tunable properties of a tracking filter object, such as the trackingEKF object. Use the FilterInitializationFcn property to initialize a tracking filter for tuning. Use the tune object function to tune the filter. Tuning the filter using trackingFilterTuner requires Optimization Toolbox™ or Global Optimization Toolbox depending on the solver algorithm you choose in the Solver property.

Creation

Description

example

tuner = trackingFilterTuner creates a tracking filter tuner with default property values.

example

tuner = trackingFilterTuner(Name=Value) specifies properties using one or more name-value arguments. For example, trackingFilterTuner(Solver="patternsearch") specifies the pattern search algorithm as the solver algorithm.

Properties

expand all

Filter initialization function, specified as a string scalar or a character vector representing the name of a valid filter initialization function. For this property, a valid filter initialization function is a function that returns a tunable tracking filter object. As of R2022b, these tracking filter objects are tunable:

You can use any of these built-in filter initialization functions.

To write a custom initialization function, refer to the code for any of the initialization functions. For example, type the following command in the command window to see the implementation for the initcvekf function.

edit initcvekf

Note

To specify the Cost property as "RMSE" or "NEES", the filter returned by the filter initialization function must use one of these built-in motion models:

If the filter does not use one of these motion models, specify the Cost property as "Custom".

Note

If you specify the UseMex property to true, changing the value of the FilterInitializationFcn property triggers code generation.

Data Types: char | string

Source of filter tunable properties, specified as:

  • "Default" — The filter object specified in the FilterInitializationFcn property defines the properties to be tuned, the tuned elements, and the tuning bounds. To get the tunable properties of the filter, use the tunableProperties object function of the tunable filter object.

  • "Custom" — Specify the tunable properties as a tunableFilterProperties object in the CustomTunableProperties property.

Note

If you set the UseMex property to true, changing the value of the TunablePropertiesSource property triggers code generation.

Data Types: char | string

Custom tunable properties, specified as a tunableFilterProperties object. You can use the tunableProperties function of the filter object to obtain the default tunableFilterProperties object and modify it to obtain a custom tunableFilterProperties object.

Note

If you set the UseMex property to true, changing the value of the CustomTunableProperties property triggers code generation.

Dependencies

To enable this property, set the TunablePropertiesSource property to "Custom".

Data Types: object

Tuning cost, specified as one of these options:

  • "RMSE" — The tuner minimizes the root mean square of the error between the ground truth and the filter estimates over all the time steps and Monte-Carlo runs. To use this option, the filter returned by the FilterInitialization property must use one of these built-in motion models:

    Use this option if the absolute distance between the truth and estimate is the most important aspect for your tuning. See Objective Function for RMSE for more algorithm details.

  • "NEES" — The tuner minimizes the normalized estimate error squared between the ground truth and the filter estimates over all the time steps and Monte-Carlo runs. To use this option, the filter returned by the filter initialization function must use one of these built-in motion models:

    Use this option if you want to optimize the state estimate error covariance for a consistent filter. See Objective Function for NEES for more algorithm details.

  • "Custom" — Specify the cost function in the CustomCostFcn property. Use a custom cost function if any of these conditions is true:

    • You want to tune the filter using a custom cost.

    • The filter uses a motion model that is not a constvel, constacc, constturn, or singer motion model.

    • The truth table contains data other than target position and velocity.

Data Types: char | string

Custom cost function, specified as a string scalar, a character vector, or a function handle. The custom cost function must use the following syntax:

cost = myCostFun(trackHistory,truth)

  • trackHistoryN-by-M array of track structures, where N is the number of the rows in the truth time table and M is the number of Monte-Carlo runs specified in the detection log input of the tune object function. Each structure has these fields:

    • UpdateTime — The time at which the filter was updated, specified as a scalar.

    • State — The state estimate at the update time.

    • StateCovariance — The state estimate error covariance at the update time.

  • truth — A truth time table that is the same as the truth time table input for the tune object function.

  • cost — A scalar value representing the cost.

Dependencies

To enable this property, set the Cost property to "Custom".

Data Types: char | string | function_handle

Optimization solver, specified as one of these options:

  • "fmincon" — This option requires Optimization Toolbox. See fmincon (Optimization Toolbox) for details.

  • "patternsearch" — This option requires Global Optimization Toolbox. See patternsearch (Global Optimization Toolbox) for details.

  • "particleswarm" — This option requires Global Optimization Toolbox. See particleswarm (Global Optimization Toolbox) for details.

Data Types: char | string

Enable using code generation, specified as a logical 0 (false) or 1 (true). Specifying true requires MATLAB® Coder™ license.

If you set the property to true, the object first generates mex code and then runs the tuning based on the generated code. For large data sets, using generated code can expedite the tuning process.

Data Types: logical

Enable using parallel processing, specified as a logical 0 (false) or 1 (true). Specifying true requires Parallel Computing Toolbox™. For large data sets, using parallel processing can expedite the tuning process.

Note

If you set the UseMex property to true, changing the value of the useParallel property triggers code generation.

Data Types: logical

Options to control the solver in the Solver property, specified as an optimoptions (Optimization Toolbox) object. The default value of [] represents the default setup for the solver.

Object Functions

tuneTune tracking filter
exportToFunctionExport filter initialization function
plotFilterErrorsPlot tracking filter errors

Examples

collapse all

Load the tuning data containing the truth and detection data. The truth data has the position and velocity of one target for a duration of 9.5 seconds. The detection data has object detections of ten Monte-Carlo runs for the same period.

load("filterTuningData.mat","truth","detlog");

Create a trackingFilterTuner object.

tuner = trackingFilterTuner;

By default, the FiliterInitialization property of the tuner returns an initialization function that initializes a trackingEKF object.

initFcn = tuner.FilterInitializationFcn
initFcn = 
"initcvekf"

Initialize the trackingEKF object and display the untuned process noise.

filter = feval(tuner.FilterInitializationFcn,detlog{1});
disp(filter.ProcessNoise);
     1     0     0
     0     1     0
     0     0     1

Specify the SolverOptions property so that the tuner displays the tuning progress for every iteration and set the maximum number of iterations to 30.

tuner.SolverOptions = optimoptions("fmincon",Display ="iter", ...
    MaxIterations=30);

Using the tune object function, tune the filter with the detection log and the truth data. Return the tuned properties.

tunedProps = tune(tuner,detlog,truth);
Your initial point x0 is not between bounds lb and ub; FMINCON
shifted x0 to strictly satisfy the bounds.

                                            First-order      Norm of
 Iter F-count            f(x)  Feasibility   optimality         step
    0       7    9.294119e+00    0.000e+00    3.977e-02
    1      14    9.274890e+00    0.000e+00    3.653e-02    1.313e-01
    2      21    9.182690e+00    0.000e+00    3.089e-02    6.852e-01
    3      28    9.077721e+00    0.000e+00    4.671e-02    1.166e+00
    4      35    9.073360e+00    0.000e+00    4.441e-02    9.369e-02
    5      42    9.054802e+00    0.000e+00    4.320e-02    2.909e-01
    6      49    9.047225e+00    0.000e+00    2.914e-02    2.754e-01
    7      56    9.047721e+00    0.000e+00    1.084e-02    3.484e-02
    8      63    9.047374e+00    0.000e+00    4.113e-03    5.013e-02
    9      70    9.047364e+00    0.000e+00    2.893e-03    1.480e-02
   10      77    9.047318e+00    0.000e+00    1.734e-03    1.414e-02
   11      84    9.047302e+00    0.000e+00    9.999e-04    7.210e-03
   12      91    9.045889e+00    0.000e+00    1.152e-03    6.212e-02
   13      98    9.045539e+00    0.000e+00    8.820e-04    2.369e-02
   14     105    9.045480e+00    0.000e+00    8.302e-04    5.352e-03
   15     112    9.045468e+00    0.000e+00    6.217e-04    2.099e-03
   16     119    9.045470e+00    0.000e+00    2.000e-04    1.936e-03
   17     126    9.045223e+00    0.000e+00    1.153e-03    2.499e-02
   18     133    9.045106e+00    0.000e+00    3.033e-04    1.772e-02
   19     140    9.045095e+00    0.000e+00    1.018e-04    2.418e-03
   20     147    9.045095e+00    0.000e+00    1.007e-04    5.276e-04
   21     154    9.045095e+00    0.000e+00    9.443e-05    9.549e-04
   22     161    9.045095e+00    0.000e+00    8.803e-05    7.331e-04
   23     168    9.045095e+00    0.000e+00    7.113e-05    1.197e-03
   24     175    9.045094e+00    0.000e+00    1.094e-04    7.076e-04
   25     182    9.045094e+00    0.000e+00    1.111e-04    6.153e-04
   26     189    9.045094e+00    0.000e+00    7.520e-05    2.503e-04
   27     196    9.045094e+00    0.000e+00    4.000e-05    1.866e-04
   28     203    9.045034e+00    0.000e+00    3.476e-04    1.553e-02
   29     210    9.045015e+00    0.000e+00    3.322e-05    7.214e-03
   30     217    9.045013e+00    0.000e+00    1.526e-05    1.220e-03

Solver stopped prematurely.

fmincon stopped because it exceeded the iteration limit,
options.MaxIterations = 3.000000e+01.

Set the filter tunable properties by using the setTunedProperty object function of the filter. Display the tuned process noise.

setTunedProperties(filter,tunedProps);
disp(filter.ProcessNoise);
    0.0000    0.0001    0.0000
    0.0001    0.0149    0.0007
    0.0000    0.0007    0.0002

Plot the filter estimation error after tuning by using the plotFilterErrors object function.

plotFilterErrors(tuner)

Figure Filter estimate error contains 6 axes objects. Axes object 1 contains 30 objects of type line. Axes object 2 contains 30 objects of type line. Axes object 3 contains 30 objects of type line. Axes object 4 contains 30 objects of type line. Axes object 5 contains 30 objects of type line. Axes object 6 contains 30 objects of type line.

Load the tuning data containing the truth and detection data. The truth data has the position and velocity of one target for a duration of 9.5 seconds. The detection data has object detections of ten Monte-Carlo runs for the same period.

load("filterTuningData.mat","truth","detlog");

Create a trackingFilterTuner object. Specify the FilterInitializationFcn property as "initcvkf" that corresponds to a trackingKF filter object with a constant velocity model.

tuner = trackingFilterTuner(FilterInitializationFcn ="initcvkf");

You can obtain the filter by evaluating the initialization function on an object detection.

filter = feval(tuner.FilterInitializationFcn,detlog{1})
filter = 
  trackingKF with properties:

               State: [6×1 double]
     StateCovariance: [6×6 double]

         MotionModel: '3D Constant Velocity'
        ProcessNoise: [3×3 double]

    MeasurementModel: [3×6 double]
    MeasurementNoise: [3×3 double]

     MaxNumOOSMSteps: 0

     EnableSmoothing: 0

To customize the tunable properties of the filter, first get the default tunable properties of the filter.

tps = tunableProperties(filter)
tps = 
Tunable properties for object of type: trackingKF

Property:      ProcessNoise
   PropertyValue:   [1 0 0;0 1 0;0 0 1]
   TunedQuantity:   Square root
   IsTuned:         true
       TunedQuantityValue:  [1 0 0;0 1 0;0 0 1]
       TunableElements:     [1 4 5 7 8 9]
       LowerBound:          [0 0 0 0 0 0]
       UpperBound:          [10 10 10 10 10 10]
Property:      StateCovariance
   PropertyValue:   [3.53553390593274 0 0 0 0 0;0 100 0 0 0 0;0 0 3.53553390593274 0 0 0;0 0 0 100 0 0;0 0 0 0 3.53553390593274 0;0 0 0 0 0 100]
   TunedQuantity:   Square root of initial value
   IsTuned:         false

Based on the display, the tuner tunes only the ProcessNoise property, which is a 3-by-3 matrix. Change the tunable elements to be only the diagonal elements by using the setPropertyTunability object function. Set the lower and upper bounds for tuning the diagonal elements.

setPropertyTunability(tps,"ProcessNoise",TunableElements=[1 5 9], ...
    LowerBound=[0.01 0.01 0.01],UpperBound = [20 20 20])

To enable custom tunable properties, set the TunablePropertiesSource and CustomTunable properties to "Custom" and tps, respectively.

tuner.TunablePropertiesSource = "Custom";
tuner.CustomTunableProperties = tps;

Using the tune object function, tune the filter with the detection log and the truth data.

tune(tuner,detlog,truth);
Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.

<stopping criteria details>

Generate the filter initialization function after tuning by using the exportToFunction object function.

exportToFunction(tuner,"tunedInitFcn")

Obtain the tuned filter by evaluating the tuned initialization function on an object detection. Show the tuned process noise.

tunedFilter = tunedInitFcn(detlog{1})
tunedFilter = 
  trackingKF with properties:

               State: [6×1 double]
     StateCovariance: [6×6 double]

         MotionModel: '3D Constant Velocity'
        ProcessNoise: [3×3 double]

    MeasurementModel: [3×6 double]
    MeasurementNoise: [3×3 double]

     MaxNumOOSMSteps: 0

     EnableSmoothing: 0

tunedFilter.ProcessNoise
ans = 3×3

    0.0001         0         0
         0    0.0149         0
         0         0    0.0001

Algorithms

expand all

References

[1] Chen, Zhaozhong, et al. “Time Dependence in Kalman Filter Tuning.” IEEE 24th International Conference on Information Fusion , IEEE, 2021, pp. 1–8.

Version History

Introduced in R2022b