# Optimal Subpattern Assignment Metric

Calculate Optimal Subpattern Assignment Metric

• Library:
• Sensor Fusion and Tracking Toolbox / Track Metrics

## Description

The Optimal Subpattern Assignment Metric block evaluates the performance of a tracking algorithm by computing the optimal subpattern assignment (OSPA) metric between tracks and known truths. The metric is comprised of the localization error, cardinality error, and labelling error components. You can select any of the error components as a block output.

## Ports

### Input

expand all

Track list, specified as a Simulink bus containing a MATLAB structure.

If you specify the Track bus parameter on the Port Setting tab to `objectTrack`, the structure must use this form:

FieldDescription
`NumTracks`Number of tracks
`Tracks`Array of track structures

Each track structure must contain `TrackID` and `State` fields. Additionally, if you specify an NEES-based distance (`posnees` or `velnees`) in the Distance type parameter, each structure must contain a `StateCovariance` field.

FieldDefinition
`TrackID`Unique track identifier used to distinguish multiple tracks, specified as a nonnegative integer.
`State`

Value of state vector at the update time, specified as an N-element vector, where N is the dimension of the state.

`StateCovariance`

Uncertainty covariance matrix, specified as an N-by-N matrix, where N is the dimension of the state.

If you specify the Track bus parameter to `custom`, then you can use your own track bus format. In this case, you must define a track extractor function using the Track extractor function parameter. The function must use this syntax:

`tracks = trackExtractorFcn(trackInputFromBus)`
where `trackInputFromBus` is the input from the track bus and `tracks` must return as an array of structures with `TrackID` and `State` fields. If you specify an NEES-based distance (`posnees` or `velnees`) in the Distance type parameter, then the structure must contain a `StateCovariance` field.

Truth list, specified as a Simulink bus containing a MATLAB structure.

If you specify the Truth bus parameter on the Port Setting tab to `Platform`, the structure must use this form:

FieldDescription
`NumPlatforms`Number of truth platforms
`Platforms`Array of truth platform structures

Each platform structure has these fields:

FieldDefinition
`PlatformID`Unique identifier used to distinguish platforms, specified as a nonnegative integer.
`Position`

Position of the platform, specified as an M-element vector, where M is the dimension of the position state. For example, M = 3 for 3-D position.

`Velocity`

Velocity of the platform, specified as an M-element vector, where M is the dimension of the velocity state. For example, M = 3 for 3-D velocity.

If you specify the Truth bus parameter as `Actor`, the structure must use this form:

FieldDescription
`NumActors`Number of truth actors
`Actors`Array of truth actor structures

Each actor structure has these fields:

FieldDefinition
`ActorID`Unique identifier used to distinguish actors, specified as a nonnegative integer.
`Position`

Position of the actor, specified as an M-element vector, where M is the dimension of the position state. For example, M = 3 for 3-D position.

`Velocity`

Velocity of the actor, specified as an M-element vector, where M is the dimension of the velocity state. For example, M = 3 for 3-D velocity.

If you specify the Truth bus parameter to`custom`, then you can define your own truth bus format. In this case, you must define a truth extractor function using the Truth extractor function parameter. The function must use this syntax:

` truths = truthExtractorFcn(truthInputFromBus)`
where `truthInputFromBus` is the input from the truth bus and `truths` must return as an array of structures with `PlatformID`, `Position`, and `Velocity` fields.

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

Assignments between tracks and truths must be unique. Redundant or false tracks should be treated as unassigned tracks by assigning them to the "`0`" `TruthID`.

#### Dependencies

To enable this port, on the Port Setting tab, select Assignments.

### Output

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

#### Dependencies

To enable this port, on the Port Setting tab, select Localization error.

Cardinality error component, returned as a nonnegative real scalar.

Example: 6

#### Dependencies

To enable this port, on the Port Setting tab, select Cardinality error.

Labeling error component, returned as a nonnegative real scalar.

Example: 7.5

#### Dependencies

To enable this port, on the Port Setting tab, select Labeling error.

## Parameters

expand all

Properties

Threshold for the 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`

Order of the OSPA metric, specified as a positive integer.

Example: `10`

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 select `custom`, you must also specify a distance function in the Custom distance function parameter.

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

`d = myCustomFcn(Track,Truth)`
where `Track` is a structure of track information, `Truth` is a structure 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 type parameter to `custom`.

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

The motion models expect the `State` field of the track structure 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 track structure 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 track structure.

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

Example: `5`

Select a simulation type from these options:

• `Interpreted execution` — Simulate the model using the MATLAB interpreter. This option shortens startup time. In `Interpreted execution` mode, you can debug the source code of the block.

• `Code generation` — Simulate the model using generated C code. The first time you run a simulation, Simulink generates C code for the block. The C code is reused for subsequent simulations as long as the model does not change. This option requires additional startup time.

Port Setting

Select this parameter to enable the input of known assignments through the Assignments input port.

Select this parameter to enable the output of the localization error component through the Localization Error output port.

Select this parameter to enable the output of the cardinality error component through the Cardinality Error output port.

Select this parameter to enable the output of the labeling error component through the Labeling Error output port.

Track bus selection, specified as `objectTrack` or `custom`. See the description of the Tracks input port for more details about each selection.

Truth bus selection, specified as `Platform`, `Actor`, or `custom`. See the description of the Truths input port for more details about each selection.

Track extractor function, specified as a function handle. The function must support this syntax:

`tracks = trackExtractorFcn(trackInputFromBus)`
where `trackInputFromBus` is the input from the track bus and `tracks` must return as an array of structures with `TrackID` and `State` fields. If you specify an NEES-based distance (`posnees` or `velnees`) in the Distance type parameter, then the structure must contain a `StateCovariance` field.

Example: `@myCustomFcn`

#### Dependencies

To enable this property, set the Track bus parameter to `custom`.

Truth extractor function, specified as a function handle. The function must support this syntax:

` truths = truthExtractorFcn(truthInputFromBus)`
where `truthInputFromBus` is the input from the track bus and `truths` must return as an array of structures with `PlatformID`, `Position`, and `Velocity` as field names.

Example: `@myCustomFcn`

#### Dependencies

To enable this property, set the Truth bus parameter to `custom`.

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 GenerationGenerate C and C++ code using Simulink® Coder™.

Introduced in R2021a