Main Content

tune

Tune tracking filter

Since R2022b

collapse all in page

Syntax

tunedProperties = tune(tuner,detectionLog,truth)

Description

example

tunedProperties = tune(tuner,detectionLog,truth) runs the trackingFilterTuner object, tunes the filter based on the detection log and the truth data, and returns the tuned filter properties.

Examples

collapse all

Open Live Script

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

Input Arguments

collapse all

Tracking filter tuner, specified as a trackingFilterTuner object.

Detection log, specified as cell arrays of objectDetection objects.

Specify detectionLog based on the number of truth targets that you specify in the truth input argument.

  • One truth target — Specify detectionLog as a T-by-N cell array of objectDetection objects. N is the number of Monte-Carlo runs. The number of time steps T does not have to be equal to the number of rows in the truth table. The timestamp of each detection does not have to match the time in the truth table.

  • Multiple truth targets — Specify detectionLog as an M-element cells, where each cell contains a cell array of objectDetection objects for the corresponding truth timetable. M is the number of truth tables. Across the M cells, the detection time, the number of detections, and the number of Monte-Carlo runs do not have to be the same.

Truth data, specified as a timetable or a cell array of timetables.

You can specify truth for one or more truth targets.

  • One truth target — Specify truth as a truth timetable. Each timetable has these variables as columns:

    • Time — Time of the truth information, specified as a duration.

    • Position — Position of the target at the time, specified as a 1-by-3 real-valued vector.

    • Velocity — Velocity of the target at the time, specified as a 1-by-3 real-valued vector. This variable is optional.

  • Multiple truth targets — Specify truth as an M-element cell array of truth timetables. Each truth table can have different initial and end times compared to other truth time tables.

Output Arguments

collapse all

Tuned properties, returned as a structure. For different tracking filter objects, this structure can have different fields since the tunable properties of each tracking filter can be different. For example, for the trackingEKF object, this structure has two fields: ProcessNoise and StateCovariance.

You can use the setTunedProperties object function of each filter object to apply the tuned properties.

Version History

Introduced in R2022b

See Also

| | | |