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
creates a
tracking filter tuner with default property values.tuner
= trackingFilterTuner
specifies properties using one or more name-value arguments. For example,
tuner
= trackingFilterTuner(Name=Value)trackingFilterTuner(Solver="patternsearch")
specifies the pattern
search algorithm as the solver algorithm.
Properties
FilterInitializationFcn
— Filter initialization function
"initcvekf"
(default) | string scalar | charter array
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
TunablePropertiesSource
— Source of filter tunable properties
"Default"
(default) | "Custom"
Source of filter tunable properties, specified as:
"Default"
— The filter object specified in theFilterInitializationFcn
property defines the properties to be tuned, the tuned elements, and the tuning bounds. To get the tunable properties of the filter, use thetunableProperties
object function of the tunable filter object."Custom"
— Specify the tunable properties as atunableFilterProperties
object in theCustomTunableProperties
property.
Note
If you set the UseMex
property to true
,
changing the value of the TunablePropertiesSource
property
triggers code generation.
Data Types: char
| string
CustomTunableProperties
— Custom tunable properties
tunableFilterProperties
object
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
Cost
— Tuning cost
"RMSE"
(default) | "NEES"
| "Custom"
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 theFilterInitialization
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 theCustomCostFcn
property. Use a custom cost function if any of these conditions is true:
Data Types: char
| string
CustomCostFcn
— Custom cost function
string scalar | character vector | function handle
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 thetruth
time table and M is the number of Monte-Carlo runs specified in the detection log input of thetune
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 thetune
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
Solver
— Optimization solver
"fmincon"
(default) | "patternsearch"
| "particleswarm"
Optimization solver, specified as one of these options:
"fmincon"
— This option requires Optimization Toolbox. Seefmincon
(Optimization Toolbox) for details."patternsearch"
— This option requires Global Optimization Toolbox. Seepatternsearch
(Global Optimization Toolbox) for details."particleswarm"
— This option requires Global Optimization Toolbox. Seeparticleswarm
(Global Optimization Toolbox) for details.
Data Types: char
| string
UseMex
— Enable using code generation
false
or 0
(default) | true
or 1
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
UseParallel
— Enable using parallel processing
false
or 0
(default) | true
or 1
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
SolverOptions
— Options to control solver
[]
(default) | optimoptions
object
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
Tune trackingEKF
Using Tracking Filter 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.
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)
Customize Tunable Properties and Tune Tracking Filter
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
Objective Function for RMSE
The state estimate error between the truth state xk and the estimated state at time step k is defined as:
The square error between the truth state and the corresponding estimated state is defined as:
Furthermore, for measurement data from multiple Monte Carlo runs, define the averaged square error at time k as:
where M is the number of Monte Carlo runs. Then the objective function for RMSE-based filter tuning is:
where T is the number of time steps. If multiple truth tables are provided, the object function is averaged as:
where Nt is the number of truth tables and JjRMSE is the RMSE object function for the j-th truth table.
Objective Function for NEES
The state estimate error between the truth state xk and the estimated state at time step k is defined as:
The normalized estimate error squared (NEES) between the truth state and the corresponding estimated state is defined as:
where Pk is the state estimate error covariance matrix at time step k.
Furthermore, for measurement data from multiple Monte Carlo runs, define the averaged NEES at time k as:
where M is the number of Monte Carlo runs. Then the objective function for NEES-based filter tuning is:
where T is the number of time steps and nx is the dimension of the state vector x.
If multiple truth tables are provided, the object function is averaged as:
where Nt is the number of truth tables and JjNEES is the NEES object function for the j-th truth table.
For a consistent filter, a filter that is neither overconfident or underconfident, the overall NEES value should be equal or close to nx. As a result, the value of JNEES should be close to 0 and the optimization algorithm penalizes any JNEES value that is larger than 0.
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
Ouvrir l'exemple
Vous possédez une version modifiée de cet exemple. Souhaitez-vous ouvrir cet exemple avec vos modifications ?
Commande MATLAB
Vous avez cliqué sur un lien qui correspond à cette commande MATLAB :
Pour exécuter la commande, saisissez-la dans la fenêtre de commande de MATLAB. Les navigateurs web ne supportent pas les commandes MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)