trackGOSPAMetric

Generalized optimal subpattern assignment (GOSPA) metric

Since R2020a

Description

trackGOSPAMetric System object™ computes the generalized optimal subpattern assignment metric between a set of tracks and the known truths.

For more details, see GOSPA Metric and [1].

To compute the generalized subpattern alignment metric:

Create the trackGOSPAMetric object and set its properties.
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

GOSPAMetric = trackGOSPAMetric

GOSPAMetric = trackGOSPAMetric(Name,Value)

Description

GOSPAMetric = trackGOSPAMetric creates a trackGOSPAMetric System object with default property values.

GOSPAMetric = trackGOSPAMetric(Name,Value) sets properties for the trackGOSPAMetric object using one or more name-value pairs. For example, GOSPAMetric = trackGOSPAMetric('CutoffDistance',5) creates a trackGOSPAMetric object with the cutoff distance equal to 5. Enclose property names in 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.

`CutoffDistance` — Threshold for cutoff distance between track and truth
`30` (default) | real positive scalar

Threshold for cutoff distance between track and truth, specified as a real positive scalar. A truth is assigned to a track only if the distance between the track and the known truth is less than this distance.

Example: 40

Data Types: single | double

`Order` — Order of GOSPA metric
`2` (default) | positive integer

Order of GOSPA metric, specified as a positive integer.

Example: 1

Data Types: single | double

`Alpha` — Alpha parameter of GOSPA metric
`2` (default) | positive scalar in range [0, 2]

Alpha parameter of GOSPA metric, specified as a positive scalar in the range [0, 2].

Example: 1

Data Types: single | double

`SwitchingPenalty` — Penalty for assignment switching
`0` | nonnegative real scalar

Penalty for assignment switching, specified as a nonnegative real scalar.

Example: 1.2

`Distance` — Distance type
`'posnees'` (default) | `'velnees'` | `'posabserr'` | `'velabserr'` | `'custom'`

Distance type, specified as 'posnees', 'velnees', 'posabserr', 'velabserr', or 'custom'. This property 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.

`DistanceFcn` — Custom distance function
function handle

Custom distance function, specified as a function handle. The function must support this 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 information for estimated tracks and truth tracks.

Example: @myCustomFcn

Dependencies

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

`MotionModel` — Desired platform motion model
`'constvel'` (default) | `'constacc'` | `'constturn'` | `'singer'`

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 input to have a column vector containing these values:

'constvel' — Constant velocity motion model of the form [x;vx;y;vy;z;vz], where x, y, and z are position coordinates and vx, vy, vz are velocity coordinates.
'constacc' — Constant acceleration motion model of the form [x;vx;ax;y;vy;ay;z;vz;az], where x, y, and z are position coordinates, vx, vy, vz are velocity coordinates, and ax, ay, az are acceleration coordinates.
'constturn' — Constant turn motion model of the form [x;vx;y;vy;theta;z;vz], where x, y, and z are position coordinates, vx, vy, vz are velocity coordinates, and theta is the yaw rate.
'singer' — Singer acceleration motion model of the form [x;vx;ax;y;vy;ay;z;vz;az], where x, y, and z are position coordinates, vx, vy, vz are velocity coordinates, and ax, ay, az are acceleration coordinates.

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. 'StateCovariance' is required only if 'posnees' or 'velnees' is selected in the Distance property.

`TrackIdentifierFcn` — Track identifier function
`@defaultTrackIdentifier` (default) | function handle

Track identifier function, specified as a function handle. The function extracts track ID from the tracks 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.
trackids is a numeric array of the same size as tracks.

For an example of a track object, see objectTrack. If you use the default identifier function, defaultTrackIdentifier, you must include track ID in tracks as the value of the TrackID field or property.

Example: @myTrackIdetifier

`TruthIdentifierFcn` — Truth identifier function
`@defaultTruthIdentifier` (default) | function handle

Truth identifier function, specified as a function handle. The function extracts truth ID from truths 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.
truthIDs is a numeric array of the same size as truths.

If you the use of the default identifier function, defaultTruthIdentifier, you must include the truth ID in truths as a value of the PlatformID field or property.

Example: @myTruthIdetifier

`HasAssignmentInput` — Enable assignment input
`false` (default) | `true`

Enable assignment input, specified as true or false. This property enables providing the assignment input at each time step. The computed GOSPA metric uses the input assignment to compute the localization component.

Data Types: logical

Usage

Syntax

sGOSPA = GOSPAMetric(tracks,truths)

[sGOSPA,GOSPA,switching] = OSPAMetric(tracks,truths)

[___] = GOSPAMetric(tracks,truths,assignment)

[sGOSPA,GOSPA,switching,localization,missTarget,falseTrack] = GOSPAMetric(___)

Description

sGOSPA = GOSPAMetric(tracks,truths) returns the GOSPA metric between the set of tracks and truths, including the switching penalty. The value of the switching penalty included in the metric depends on the SwitchingPenalty property. By default, the metric uses the global nearest neighbor (GNN) assignments at the current and the previous step to decide if the tracks are switched.

[sGOSPA,GOSPA,switching] = OSPAMetric(tracks,truths) also returns the GOSPA component and the switching component.

[___] = GOSPAMetric(tracks,truths,assignment) allows you the specify the current assignments between tracks and truths used in the metric evaluation. You can return outputs as any of the previous syntaxes.

To use this syntax, set the HasAssignmentInput property to true.

[sGOSPA,GOSPA,switching,localization,missTarget,falseTrack] = GOSPAMetric(___) also returns the localization component, missed target component, and the false track component. You can use any of the input combinations in the previous syntaxes.

To use this syntax, set the value of the Alpha property to 2.

example

Input Arguments

expand all

`tracks` — Track information
array of structures | array of objects

Track information, specified as an array of structures or objects for built-in distance functions. Each structure or object must contain State as a field or property. Additionally, if a 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. See objectTrack for an example of track object.

Data Types: struct | object

`truths` — Truth information
array of structures | array of objects

Truth information, specified as an array of structures or objects for 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

`assignment` — Known current assignment
N-by-2 matrix of nonnegative integers

Known current 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 tracks and truths assigned to each other. If a track (or a truth) is not assigned, specify 0 as the same row element for the truth (or the track).

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

`sGOSPA` — GOSPA metric including switching component
nonnegative real scalar

GOSPA metric including switching component, returned as a nonnegative real scalar.

`GOSPA` — GOSPA metric
nonnegative real scalar

GOSPA metric, returned as a nonnegative real scalar.

`switching` — Switching component
nonnegative real scalar

Switching component, returned as a nonnegative real scalar.

`localization` — Localization component
nonnegative real scalar

Localization component, returned as a nonnegative real scalar.

`missTarget` — Missed target component
nonnegative real scalar

Missed target component, returned as a nonnegative real scalar.

`falseTrack` — False track component
nonnegative real scalar

False track component, returned as a nonnegative real scalar.

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

Common to All System Objects

`step`	Run System object algorithm
`release`	Release resources and allow changes to System object property values and input characteristics
`reset`	Reset internal states of System object
`clone`	Create duplicate System object
`isLocked`	Determine if System object is in use

Examples

collapse all

Evaluate Tracking Results Using GOSPA Metric

Open Live Script

Load prerecorded data.

load trackmetricex tracklog truthlog;

Create a trackGOSPAMetric object and set the SwitchingPenalty to 5.

tgm = trackGOSPAMetric('SwitchingPenalty',5);

Create output variables.

lgospa = zeros(numel(tracklog),1);
gospa = zeros(numel(tracklog),1);
switching = zeros(numel(tracklog),1);
localization = zeros(numel(tracklog),1);
missTarget = zeros(numel(tracklog),1);
falseTracks = zeros(numel(tracklog),1);

After extracting the tracks and ground truths, run the GOSPA metric.

for i = 1:numel(tracklog)
    tracks = tracklog{i};
    truths = truthlog{i};
    [lgospa(i),gospa(i),switching(i),localization(i),missTarget(i),falseTracks(i)] = tgm(tracks,truths);
end

Visualize the results.

plot([lgospa gospa switching localization missTarget falseTracks])
legend('Labeled GOSPA','GOSPA','Switching Component',...
    'Localization Component','Missed Target Component','False Tracks Component')

Figure contains an axes object. The axes object contains 6 objects of type line. These objects represent Labeled GOSPA, GOSPA, Switching Component, Localization Component, Missed Target Component, False Tracks Component.

Algorithms

expand all

GOSPA Metric

At time t_k, a list of truths is:

$X = [x_{1}, x_{2}, \dots, x_{m}]$

At time t_k, a tracker obtains a list of tracks:

$Y = [y_{1}, y_{2}, \dots, y_{n}]$

In general, the GOSPA metric including the switching component (SGOSPA) is:

$S G O S P A = {(G O S P A^{p} + S C^{p})}^{1 / p}$

where p is the order of the metric, SC is the switching component, and GOSPA is the basic GOSPA metric.

Assuming m ≤ n, GOSPA is:

$G O S P A = {[\sum_{i = 1}^{m} d_{c}^{p} (x_{i}, y_{π (i)}) + \frac{c^{p}}{α} (n - m)]}^{1 / p}$

where d_c is the cutoff-based distance and y_π(i) represents the track assigned to truth x_i. The cutoff-based distance d_c is defined as:

$d_{c} (x, y) = \min {d_{b} (x, y), c}$

where c is the cutoff distance threshold, and d_b(x,y) is the base distance between track x and truth y calculated by the distance function. The cutoff based distance d_c is the smaller value of d_b and c. α is the alpha parameter.

The switching component SC is:

$S C = S P \times n_{s}^{1 / p}$

where SP is the switching penalty and n_s is the number of switches. When a track switches assignment from one truth to another truth, the number of switching is counted as 1. When a track switches from assigned to unassigned or switches from unassigned to assigned, the number of switching is counted as 0.5. For example, as shown in the table, Tracks 1 and 2 both switched to different truths, whereas Track 3 switched from assigned to unassigned. Therefore, the total number of switching is 2.5.

Track Switching Scenario

Previous		Current
Tracks	Truths	Tracks	Truths
1	3	1	7
2	5	2	3
3	7	3	0

When α = 2, the GOSPA metric can reduce to three components:

$G O S P A = {[l o c^{p} + m i s s^{p} + f a l s e^{p}]}^{1 / p}$

The localization component (loc) is calculated as:

$l o c = {[\sum_{i = 1}^{h} d_{b}^{p} (x_{i}, y_{π (i)})]}^{1 / p}$

where h is the number of nontrivial assignments. A trivial assignment is when a track is assigned to no truth. The missed target component is calculated as:

$m i s s = \frac{c}{2^{1 / p}} {(n_{m i s s})}^{1 / p}$

where n_miss is the number of missed targets. The false track component is calculated as:

$f a l s e = \frac{c}{2^{1 / p}} {(n_{f a l s e})}^{1 / p}$

where n_false is the number of false tracks.

If m > n, simply exchange m and n in the formulation to obtain the GOSPA metric.

References

[1] Rahmathullash, A. S., A. F. García-Fernández, and L. Svensson. "Generalized Optimal Sub-Pattern Assignment Metric." 20th International Conference on Information Fusion (Fusion), pp. 1–8, 2017.

Extended Capabilities

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

Version History

Introduced in R2020a

trackGOSPAMetric

Description

Creation

Syntax

Description

Properties

CutoffDistance — Threshold for cutoff distance between track and truth 30 (default) | real positive scalar

Order — Order of GOSPA metric 2 (default) | positive integer

Alpha — Alpha parameter of GOSPA metric 2 (default) | positive scalar in range [0, 2]

SwitchingPenalty — Penalty for assignment switching 0 | nonnegative real scalar

Distance — Distance type 'posnees' (default) | 'velnees' | 'posabserr' | 'velabserr' | 'custom'

DistanceFcn — Custom distance function function handle

Dependencies

MotionModel — Desired platform motion model 'constvel' (default) | 'constacc' | 'constturn' | 'singer'

TrackIdentifierFcn — Track identifier function @defaultTrackIdentifier (default) | function handle

TruthIdentifierFcn — Truth identifier function @defaultTruthIdentifier (default) | function handle

HasAssignmentInput — Enable assignment input false (default) | true

Usage

Syntax

Description

Input Arguments

tracks — Track information array of structures | array of objects

truths — Truth information array of structures | array of objects

assignment — Known current assignment N-by-2 matrix of nonnegative integers

Output Arguments

sGOSPA — GOSPA metric including switching component nonnegative real scalar

GOSPA — GOSPA metric nonnegative real scalar

switching — Switching component nonnegative real scalar

localization — Localization component nonnegative real scalar

missTarget — Missed target component nonnegative real scalar

falseTrack — False track component nonnegative real scalar

Object Functions

Common to All System Objects

Examples

Evaluate Tracking Results Using GOSPA Metric

Algorithms

GOSPA Metric

References

Extended Capabilities

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

Version History

See Also

`CutoffDistance` — Threshold for cutoff distance between track and truth
`30` (default) | real positive scalar

`Order` — Order of GOSPA metric
`2` (default) | positive integer

`Alpha` — Alpha parameter of GOSPA metric
`2` (default) | positive scalar in range [0, 2]

`SwitchingPenalty` — Penalty for assignment switching
`0` | nonnegative real scalar

`Distance` — Distance type
`'posnees'` (default) | `'velnees'` | `'posabserr'` | `'velabserr'` | `'custom'`

`DistanceFcn` — Custom distance function
function handle

`MotionModel` — Desired platform motion model
`'constvel'` (default) | `'constacc'` | `'constturn'` | `'singer'`

`TrackIdentifierFcn` — Track identifier function
`@defaultTrackIdentifier` (default) | function handle

`TruthIdentifierFcn` — Truth identifier function
`@defaultTruthIdentifier` (default) | function handle

`HasAssignmentInput` — Enable assignment input
`false` (default) | `true`

`tracks` — Track information
array of structures | array of objects

`truths` — Truth information
array of structures | array of objects

`assignment` — Known current assignment
N-by-2 matrix of nonnegative integers

`sGOSPA` — GOSPA metric including switching component
nonnegative real scalar

`GOSPA` — GOSPA metric
nonnegative real scalar

`switching` — Switching component
nonnegative real scalar

`localization` — Localization component
nonnegative real scalar

`missTarget` — Missed target component
nonnegative real scalar

`falseTrack` — False track component
nonnegative real scalar

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