# Optimal Subpattern Assignment Metric

**Libraries:**

Sensor Fusion and Tracking Toolbox /
Track Metrics

## Description

The Optimal Subpattern Assignment Metric block computes the optimal subpattern assignment metric between a set of tracks and known truths. You can enable different types of OSPA metrics by configuring these parameters:

Traditional OSPA — Specify the

**Metric**parameter as`OSPA`

and specify the**Labeling error**parameter, on the**Properties**tab, as`0`

. The traditional OSPA metric, which evaluates instantaneous tracking performance, contains two 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.

Labeled OSPA — Specify the

**Metric**parameter as`OSPA`

and specify the**Labeling error**parameter, on the**Properties**tab, as a positive scalar. The labeled OSPA (LOSPA) metric, which evaluates instantaneous tracking performance and includes penalties for incorrect assignments, 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 assignments.

OSPA

^{(2)}— Specify the**Metric**parameter as`OSPA(2)`

. The OSPA^{(2)}metric evaluates cumulative tracking performance for a duration of time.

You can output each component individually from the block. For more details on the algorithm, see Algorithm and References.

## Ports

### Input

**Tracks** — Track list

Simulink^{®} bus containing MATLAB^{®} structure

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:

Field | Description |
---|---|

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

Field | Definition |
---|---|

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

`StateCovariance` | Uncertainty covariance matrix, specified as an |

If you specify an NEES-based distance (`posnees`

or
`velnees`

) in the **Distance type** parameter,
then the structure must contain a `StateCovariance`

field.

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)

`trackInputFromBus`

is the input from the track bus and
`tracks`

must return as an array of structures with
`TrackID`

and `State`

fields. **Truths** — Truth list

Simulink bus containing MATLAB structure

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:

Field | Description |
---|---|

`NumPlatforms` | Number of truth platforms |

`Platforms` | Array of truth platform structures |

Each platform structure has these fields:

Field | Definition |
---|---|

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

`Position` | Position of the platform, specified as an |

`Velocity` | Velocity of the platform, specified as an |

If you specify the **Truth bus** parameter as
`Actor`

, the structure must
use this form:

Field | Description |
---|---|

`NumActors` | Number of truth actors |

`Actors` | Array of truth actor structures |

Each actor structure has these fields:

Field | Definition |
---|---|

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

`Position` | Position of the actor, specified as an |

`Velocity` | Velocity of the actor, specified as an |

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)

`truthInputFromBus`

is the input from the truth bus and
`truths`

must return as an array of structures with
`PlatformID`

, `Position`

, and `Velocity`

fields.**Assignments** — Known assignment

*K*-by-2 matrix of nonnegative integers

Known assignment, specified as a*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

**OSPA Metric** — OSPA metric

nonnegative real scalar

OSPA metric, returned as a nonnegative real scalar. Depending on the values of the
**Metric** and **Labeling error** parameters, the
block can output traditional OSPA, labeled OSPA (LOSPA), or
OSPA^{(2)}.

Metric Parameter Value | Labeling error Parameter Value | Metric |
---|---|---|

`OSPA` | `0` | OSPA |

`OSPA` | Positive scalar | LOSPA |

`OSPA(2)` | Not applicable | OSPA^{(2)} |

**Example: **10.1

**Localization Error** — Localization error component

nonnegative real scalar

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 ** — Cardinality error component

nonnegative real scalar

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** — Labeling error component

nonnegative real scalar

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

**Properties**

**Metric** — Metric option

`OPSA`

(default) | `OSPA(2)`

Metric option, specified as `OSPA`

or `OSPA(2)`

.

`OSPA`

— Computes the traditional OSPA metric by default, or computes the labeled OSPA metric after additionally specifying the**Labeling error**parameter as a positive value.`OSPA(2)`

— Computes the OSPA^{(2)}metric, which evaluates cumulative tracking performance. Selecting this option enables these parameters for configuring the metric:**Window length****Window sum order (q)****Window weights****Window weight exponent (r)****Custom window weights**

Selecting this option also disables two parameters used to evaluate the labeling error component:

**Assignments****Labeling error**

**Cutoff distance** — Threshold for cutoff distance between track and truth

`30`

(default) | real positive scalar

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** — Order of OSPA metric

`2`

(default) | positive integer

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

**Example: **
`3`

**Distance type** — Distance type

`posnees`

(default) | `velnees`

| `posabserr`

| `velabserr`

| `custom`

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** — Custom distance function

function handle

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

d = myCustomFcn(Track,Truth)

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

.

**Motion model** — 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 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.

**Labeling error** — Penalty for incorrect assignment

`0`

(default) | nonnegative scalar

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 assignment is assumed to be correct.

**Example: **
`5`

#### Dependencies

To enable this parameter, set the **Metric** parameter to
`OSPA`

.

**Window length** — Sliding window length for OSPA^{(2)} metric

`100`

(default) | positive integer

Sliding window length for the OSPA^{(2)} metric, specified
as a positive integer. The window length defines the number of time steps from a
previous time to the current time used to evaluate the metric. For more details, see
OSPA(2) Metric.

#### Dependencies

To enable this parameter, set the **Metric** parameter to
`OSPA(2)`

.

**Data Types: **`single`

| `double`

**Window sum order (q)** — Order of weighted sum for track and truth history

`2`

(default) | positive scalar

Order of weighted sum for the track and truth history, specified as a positive scalar. For more details, see OSPA(2) Metric.

#### Dependencies

To enable this parameter, set the **Metric** parameter to
`OSPA(2)`

.

**Data Types: **`single`

| `double`

**Window weights** — Options for window weights

`auto`

(default) | `custom`

Options for window weights, specified as `auto`

or
`custom`

.

`auto`

— Automatically generates the window weights using the algorithm given in OSPA(2) Metric.`custom`

— Customizes the window weights using the**Custom window weights**parameter.

#### Dependencies

To enable this parameter, set the **Metric** parameter to
`OSPA(2)`

.

**Data Types: **`single`

| `double`

**Window weight exponent (r)** — Exponent for automatic weight calculation

`1`

(default) | nonnegative scalar

Exponent for automatic weight calculation, specified as a nonnegative scalar. An
exponent value, *r*, of `0`

represents equal weights
in the window. A higher value of *r* assigns more weights on recent
data. For more details, see OSPA(2) Metric.

#### Dependencies

To enable this parameter, set the **Window weights** parameter to
`auto`

.

**Data Types: **`single`

| `double`

**Custom window weights** — Custom weights in time window

*N*-element of vector of nonnegative values

Custom weights in the time window, specified as an *N*-element of
vector of nonnegative values, when *N* is the window length, specified
in the **Window length** parameter.

#### Dependencies

To enable this parameter, set the **Window weights** parameter to
`custom`

.

**Data Types: **`single`

| `double`

**Simulate using** — Type of simulation to run

`Interpreted execution`

(default) | `Code Generation`

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**

**Assignments** — Enable assignment input

`off`

(default) | `on`

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

#### Dependencies

To enable this parameter, set the **Metric** parameter to
`OSPA`

.

**Localization error** — Enable localization error component output

`off`

(default) | `on`

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

**Cardinality error** — Enable cardinality error component output

`off`

(default) | `on`

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

**Labeling error** — Enable labeling error component output

`off`

(default) | `on`

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

#### Dependencies

To enable this parameter, set the **Metric** parameter to
`OSPA`

.

**Track bus** — Track bus selection

`objectTrack`

(default) | `custom`

Track bus selection, specified as `objectTrack`

or
`custom`

. See the description of the **Tracks**
input port for more details about each selection.

**Truth bus** — Truth bus selection

`Platform`

(default) | `Actor`

| `custom`

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** — Track extractor function

function handle

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

tracks = trackExtractorFcn(trackInputFromBus)

`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** — Truth extractor function

function handle

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

truths = truthExtractorFcn(truthInputFromBus)

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

.

## Algorithms

### OSPA Metric

At time *t*_{k}, a list of truths is:

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

At the same time, a tracker obtains a list of tracks:

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

The traditional OSPA metric is:

$$OSPA={({d}_{loc}^{p}+{d}_{card}^{p})}^{1/p}$$

Assuming *m* ≤ *n*, the two components,
*d*_{loc} and
*d*_{card} are calculated using
these equations. The *localization error* component
*d*_{loc} is computed as:

$${d}_{loc}={\left\{\frac{1}{n}{\displaystyle \sum _{i=1}^{m}{d}_{c}^{p}\left({x}_{i},{y}_{\pi (i)}\right)}\right\}}^{1/p}$$

where *p* is the order of the OSPA metric,
*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)=\mathrm{min}\left\{{d}_{b}(x,y),c\right\}$$

where *c* is the cutoff distance threshold, and
*d*_{b}(*x*,*y*)
is the distance between truth *x* and track *y* calculated
by the distance function. The cutoff-based distance
*d*_{c} takes the smaller
value of *d*_{b} and
*c*.

The *cardinality error* component
*d*_{card} is:

$${d}_{card}={\left\{\frac{n-m}{n}{c}^{p}\right\}}^{1/p}$$

The labeled OSPA (LOSPA) is:

$$OSPA={({d}_{loc}^{p}+{d}_{card}^{p}+{d}_{lab}^{p})}^{1/p}$$

Here, additionally, the labeling error component
*d*_{lab} is:

$${d}_{lab}={\left\{\frac{1}{n}{\displaystyle \sum _{i=1}^{m}{\alpha}^{p}\gamma \left(L({x}_{i}),L({y}_{\pi (i)})\right)}\right\}}^{1/p}$$

where *α* is the penalty for incorrect assignment in the
labeling error component,
*L*(*x*_{i})
represents the truth ID of *x*_{i},
and
*L*(*y*_{π(i)})
represents the track ID of
*y*_{π(i)}.
The function *γ* = 0 if the IDs of the truth and track pair agree with the
known assignment given by the `assignment`

input, or agree with the
assignment in the last update if the known assignment is not given. Otherwise,
*γ* = 1.

If *m* > *n*, exchange *m* and
*n* in the formulation to obtain the OSPA metric.

### OSPA^{(2)} Metric

Consider a time period of *N* time steps, from time
*t*_{k-N+1}
to time *t*_{k}. During this time
period, you have a list of *m* truth histories:

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

Each truth history *x*_{i}, is
composed of :

$${x}_{i}=[{x}_{i(k-N+1}),\dots ,{x}_{i(k)}]$$

where
*x*_{i(s)}
is the track history for *x*_{i} at
time step *t*_{s}, and
*x*_{i(s)}= ∅
if *x*_{i} does not exist at time
*t*_{s}. For the same time
period, you have a list of *n* track histories:

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

Each track history *y*_{i} is
composed of :

$${y}_{i}=[{y}_{i(k-N+1}),\dots ,{y}_{i(k)}]$$

where
*y*_{i(s)}
is the track history at time step
*t*_{s}, and
*y*_{i(s)}= ∅
if *y*_{i} does not exist at time
*t*_{s}.

Assuming *m* ≤ *n*, the OPSA^{(2)}
metric is calculated as:

$$OSP{A}^{(2)}={\left[{d}_{loc}^{p}+{d}_{card}^{p}\right]}^{1/p}$$

where the *cardinality error* component
*d*_{card} is:

$${d}_{card}={\left\{\frac{n-m}{n}{c}^{p}\right\}}^{1/p}$$

In this equation, *p* is the order of the OSPA metric,
and *c* is the cutoff distance threshold.

The *localization error* component
*d*_{loc} is computed as:

$${d}_{loc=}{\left\{\frac{1}{n}{\displaystyle \sum _{i=1}^{m}{d}_{q}({x}_{i},{y}_{\pi (i)})}\right\}}^{1/p}$$

where
*y*_{π(i)}
represents the track assigned to truth
*x*_{i}, and
*d*_{q} is the *base
distance* between a truth and a track, accounting for cumulative tracking
errors.

You can obtain *d*_{q} between a truth *x*_{i} and a track *y*_{j} as:

$${d}_{q}({x}_{i},{y}_{j})={\left[{\displaystyle \sum _{\tau =k-N+1}^{k}w(\tau ){d}^{*}{\left({x}_{i}(\tau ),{y}_{j}(\tau )\right)}^{q}}\right]}^{1/q}$$

where *N* is the *window length*,
*w*(*τ*) is the *window weight*
at time step *τ*, and *q* is the *window sum
order*. *d** is defined as:

$${d}^{*}\left({x}_{i}(\tau ),{y}_{j}(\tau )\right)=\{\begin{array}{l}{d}_{c}\left({x}_{i}(\tau ),{y}_{j}(\tau )\right)=\mathrm{min}\left\{{d}_{b}\left({x}_{i}(\tau ),{y}_{j}(\tau )\right),c\right\},\text{\hspace{1em}}if\text{\hspace{0.17em}}{x}_{i}(\tau )\ne \varnothing \text{\hspace{0.17em}}and\text{\hspace{0.17em}}{y}_{i}(\tau )\text{\hspace{0.17em}}\ne \varnothing \text{\hspace{0.17em}}\\ c,\text{\hspace{1em}}if\text{\hspace{0.17em}}{x}_{i}(\tau )=\varnothing \text{\hspace{0.17em}}and\text{\hspace{0.17em}}{y}_{i}(\tau )\text{\hspace{0.17em}}\ne \varnothing ,\text{\hspace{0.17em}}or\text{\hspace{0.17em}}{x}_{i}(\tau )\ne \varnothing \text{\hspace{0.17em}}and\text{\hspace{0.17em}}\text{\hspace{0.17em}}{y}_{i}(\tau )\text{\hspace{0.17em}}=\varnothing \\ 0,\text{\hspace{1em}}if\text{\hspace{0.17em}}{x}_{i}(\tau )={y}_{i}(\tau )=\varnothing \text{\hspace{0.17em}}\end{array}$$

From the equation, the cutoff-based distance
*d*_{c} takes the smaller
value of *d*_{b} and
*c*, where
*d*_{b}(*x*_{i}(*τ*),*y*_{j}(*τ*)
) is the distance between truth
*x*_{i} and track
*y*_{j} at time
*τ*, calculated by the distance function.

If you do not customize the window weights, the object assigns the *window
weights* as:

$$w(\tau )=\frac{{(N-k+\tau )}^{r}}{{\displaystyle \sum _{\tau =k-N+1}^{k}{(N-k+\tau )}^{r}}}$$

where *r* is the *window weight
component*.

If *m* > *n*, exchange *m* and
*n* in the formulation to obtain the OSPA^{(2)}
metric.

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

[3] M. Beard, B. -T. Vo, and B. -N.
Vo. “OSPA (2) : Using the OSPA Metric to Evaluate Multi-Target Tracking Performance.”
*2017 International Conference on Control, Automation and Information
Sciences*, IEEE, 2017, pp. 86–91.

## Extended Capabilities

### C/C++ Code Generation

Generate C and C++ code using Simulink® Coder™.

## Version History

**Introduced in R2021a**

### R2023a: Simulink buses do not show in workspace

As of R2023a, the Simulink buses created by this block no longer show in MATLAB workspace.

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)