trackOSPAMetric

Optimal subpattern assignment (OSPA) metric

expand all in page

Description

trackOSPAMetric System object™ computes the optimal subpattern assignment metric between a set of tracks and the known truths. An OSPA metric contains three components:

  • Localization error component — Accounts for state estimation errors between assigned tracks and truths

  • Cardinality error component— Accounts for the number of unassigned tracks and truths

  • Labelling error component — Accounts for the error of incorrect assignment

For more details, see OSPA Metric and [2].

To use trackOSPAMetric:

  1. Create the trackOSPAMetric object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?.

Creation

Syntax

OSPAMetric = trackOSPAMetric
OSPAMetric = trackOSPAMetric(Name,Value)

Description

OSPAMetric = trackOSPAMetric creates a trackOSPAMetric System object, OSPAMetric, with default property values.

OSPAMetric = trackOSPAMetric(Name,Value) sets properties for the trackOSPAMetric object using one or more name-value pairs. For example, OSPAMetric = trackOSPAMetric('CutoffDistance',5) creates a trackOSPAMetric object with the cut off distance equal to 5. Enclose property names in single quotes.

Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Threshold for cutoff distance between track and truth, specified as a real positive scalar. If the computed distance between a track and the assigned truth is higher than the threshold, the actual distance incorporated in the metric is reduced to the threshold.

Example: 40

Data Types: single | double

Order of OSPA metric, specified as a positive integer.

Example: 10

Data Types: single | double

Penalty for incorrect assignment of track to truth, specified as a real positive scalar. The function decides if an assignment is correct based on the provided known assignment input. If the assignment is not provided as an input, the last known "optimal" assignment is assumed to be correct.

Example: 5

Data Types: single | double

Distance type, specified as 'posnees', 'velnees', 'posabserr', or 'velabserr'. The distance type specifies the physical quantity used for distance calculations:

  • 'posnees' – Normalized estimation error squared (NEES) of track position

  • 'velnees' – NEES error of track velocity

  • 'posabserr' – Absolute error of track position

  • 'velabserr' – Absolute error of track velocity

  • 'custom' – Custom distance error

If you specify the Distance property as 'custom', you must also specify the distance function in the DistanceFcn property.

Custom distance function, specified as a function handle. The function must support the following syntax:

d = myCustomFcn(Track,Truth)
where Track is a structure or an object of track information, Truth is a structure or an object of truth information, and d is the distance between the truth and the track. See objectTrack for an example on how to organize track information.

Example: @myCustomFcn

Dependencies

To enable this property, set the Distance property to 'custom'.

Desired platform motion model, specified as 'constvel', 'constacc', 'constturn', or 'singer'. This property selects the motion model used by the tracks input.

The motion models expect the 'State' field of the tracks to have a column vector containing these values:

  • 'constvel' — Position is in elements [1 3 5], and velocity is in elements [2 4 6].

  • 'constacc' — Position is in elements [1 4 7], velocity is in elements [2 5 8], and acceleration is in elements [3 6 9].

  • 'constturn' — Position is in elements [1 3 6], velocity is in elements [2 4 7], and yaw rate is in element 5.

  • 'singer' — Position is in elements [1 4 7], velocity is in elements [2 5 8], and acceleration is in elements [3 6 9].

The 'StateCovariance' field of the tracks input must have position, velocity, and turn-rate covariances in the rows and columns corresponding to the position, velocity, and turn-rate of the 'State' field of the tracks input.

Track identifier function, specified as a function handle. The function extracts track ID from the track input. The function must support the following syntax:

Trackids = trackIdentifier(Tracks)
where Tracks is an array of structures or objects containing the information of tracks, and Trackids is a numeric array of the same size as Tracks. For an example of track object, see objectTrack. For the default identifier function, defaultTrackIdentifier, the track ID must be contained in Tracks as the value of the TrackID field or property.

Example: @myTrackIdetifier

Truth identifier function, specified as a function handle. The function extracts truth ID from truth input. The function must support the following syntax:

TruthIDs = truthIdentifier(Truths)
where Truths is an array of structures or objects containing the information of truths, and TruthIDs is a numeric array of the same size as Truths. For the use of the default identifier function, defaultTruthIdentifier, the truth ID must be contained in Truth as a value of the PlatformID field or property.

Example: @myTruthIdetifier

Enable assignment input, specified as true or false.

Data Types: logical

Usage

Syntax

OSPA = OSPAMetric(tracks,truths)
OSPA = OSPAMetric(tracks,truths,assignment)
[OSPA,localOSPA] = OSPAMetric(___)
[OSPA,localOSPA,cardOSPA] = OSPAMetric(___)
[OSPA,localOSPA,cardOSPA,labelOSPA] = OSPAMetric(___)

Description

OSPA = OSPAMetric(tracks,truths) returns the OSPA metric between the set of tracks and truths.

OSPA = OSPAMetric(tracks,truths,assignment) allows you to specify the known assignment between tracks and truths at the current time step. To use this syntax, specify the HasAssignmentInput property as true.

[OSPA,localOSPA] = OSPAMetric(___) also returns the localization error component of the OSPA metric. You can use any of the input combinations in the previous syntaxes as the input.

example

[OSPA,localOSPA,cardOSPA] = OSPAMetric(___) also returns the cardinality error component of the OSPA metric.

[OSPA,localOSPA,cardOSPA,labelOSPA] = OSPAMetric(___) also returns the labeling error component of the OSPA metric.

Input Arguments

expand all

Track information, specified as an array of structures or objects for noncustomized (built-in) distance functions. Each structure or object must contain State as a field or property. Additionally, if an NEES-based distance (posnees or velnees) is specified in the Distance property, each structure or object must also contain StateCovariance as a field or property. Moreover, if the default track identifier function is used in the TrackIdentifierFcn property, then each structure or object must also contain TrackID as a field or property.

Data Types: struct | object

Truth information, specified as an array of structures or objects for noncustomized (built-in) distance functions. Each structure or object must contain Position and velocity as fields or properties. If the default truth identifier function is used in the TruthIdentifierFcn property, then each structure or object must also contain PlatformID as a field or property.

Data Types: struct | object

Known assignment, specified as an N-by-2 matrix of nonnegative integers. The first column elements are track IDs, and the second column elements are truth IDs. The IDs in the same row are assigned to each other. If a track or truth is not assigned, specify 0 as the same row element.

Note that the assignment must be a unique assignment between tracks and truths. Redundant or false tracks should be treated as unassigned tracks by assigning them to the "0" TruthID.

Data Types: single | double

Output Arguments

expand all

OSPA metric, returned as a nonnegative real scalar.

Example: 10.1

Localization error component, returned as a nonnegative real scalar.

Example: 8.5

Cardinality error component, returned as a nonnegative real scalar.

Example: 6

Labeling error component, returned as a nonnegative real scalar.

Example: 7.5

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

expand all

stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object
cloneCreate duplicate System object

Examples

collapse all

Open Live Script

Load prerecorded track data and truth data.

load trackmetricex tracklog truthlog

Construct a trackOSPAMetric object.

tom = trackOSPAMetric;

Initialize output variables.

ospa = zeros(numel(tracklog),1);
cardOspa = zeros(numel(tracklog),1);
locOspa = zeros(numel(tracklog),1);

Calculate three OSPA components in a loop.

for i = 1:numel(tracklog)
    tracks = tracklog{i};
    truths = truthlog{i};
    [ospa(i), locOspa(i), cardOspa(i)] = tom(tracks, truths);
end

Visualize the results.

figure()
plot(ospa,'g');
hold on;
plot(locOspa,'r:');
plot(cardOspa,'b--');
legend('OSPA','Localization OSPA','Cardinality OSPA');

More About

expand all

References

[1] Schuhmacher, B., B. -T. Vo, and B. -N. Vo. "A Consistent Metric for Performance Evaluation of Multi-Object Filters." IEEE Transactions on Signal Processing, Vol, 56, No, 8, pp. 3447–3457, 2008.

[2] Ristic, B., B. -N. Vo, D. Clark, and B. -T. Vo. "A Metric for Performance Evaluation of Multi-Target Tracking Algorithms." IEEE Transactions on Signal Processing, Vol, 59, No, 7, pp. 3452–3457, 2011.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

See Also

|

Introduced in R2019b

Sensor Fusion and Tracking Toolbox Documentation

Support