# trackGOSPAMetric

Generalized optimal subpattern assignment (GOSPA) metric

## 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:

1. Create the `trackGOSPAMetric` object and set its properties.

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

## 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.

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 of GOSPA metric, specified as a positive integer.

Example: `1`

Data Types: `single` | `double`

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

Example: `1`

Data Types: `single` | `double`

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

Example: `1.2`

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.

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

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.

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`

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`

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

example

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

### Input Arguments

expand all

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`

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`

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

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

GOSPA metric, returned as a nonnegative real scalar.

Switching component, returned as a nonnegative real scalar.

Localization component, returned as a nonnegative real scalar.

Missed target component, returned as a 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

 `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

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

expand all

## 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.

## Version History

Introduced in R2020a