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

Syntax

``tuner = trackingFilterTuner``
``tuner = trackingFilterTuner(Name=Value)``

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:

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)`

• `trackHistory`N-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

 `tune` Tune tracking filter `exportToFunction` Export filter initialization function `plotFilterErrors` Plot 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)`

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 ```

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