# distance

Distances between current and predicted measurements of tracking filter

## Syntax

``dist = distance(filter,zmeas)``
``dist = distance(filter,zmeas,measparams)``

## Description

````dist = distance(filter,zmeas)` computes the normalized distances between one or more current object measurements, `zmeas`, and the corresponding predicted measurements computed by the input `filter`. Use this function to assign measurements to tracks.This distance computation takes into account the covariance of the predicted state and the measurement noise.```
````dist = distance(filter,zmeas,measparams)` specifies additional parameters that are used by the `MeasurementFcn` of the filter.If filter is a `trackingKF` or `trackingABF` object, then you cannot use this syntax.```

## Input Arguments

collapse all

Filter for object tracking, specified as one of these objects:

Measurements of tracked objects, specified as a matrix. Each row of the matrix contains a measurement vector.

Parameters for measurement function, specified as a cell array. The parameters are passed to the measurement function that is defined in the `MeasurementFcn` property of the `filter`. If `filter` is a `trackingKF` or `trackingABF` object, then you cannot specify `measparams`.

Suppose you set the `MeasurementFcn` property of `filter` to `@cameas`, and then set these values:

`measurementParams = {frame,sensorpos,sensorpos}`

The `distance` function internally calls the following:

`cameas(state,frame,sensorpos,sensorvel)`

## Output Arguments

collapse all

Distances between measurements, returned as a row vector. Each element corresponds to a distance between the predicted measurement in the input `filter` and a measurement contained in a row of `zmeas`.

## Algorithms

The `distance` function computes the normalized distance between the filter object and a set of measurements. This distance computation is a variant of the Mahalanobis distance and takes into account the residual (the difference between the object measurement and the value predicted by the filter), the residual covariance, and the measurement noise.

Consider an extended Kalman filter with state x and measurement z. The equations used to compute the residual, zres, and the residual covariance, S, are

zres = zh(x),

S = R + HPHT,

where:

• h is the measurement function defined in the `MeasurementFcn` property of the filter.

• R is the measurement noise covariance defined in the `MeasurementNoise` property of the filter.

• H is the Jacobian of the measurement function defined in the `MeasurementJacobianFcn` property of the filter.

The residual covariance calculation for other filters can vary slightly from the one shown because tracking filters have different ways of propagating the covariance to the measurement space. For example, instead of using the Jacobian of the measurement function to propagate the covariance, unscented Kalman filters sample the covariance, and then propagate the sampled points.

The equation for the Mahalanobis distance, d2, is

d2 = zresTS–1z,

The distance function computes the normalized distance, dn, as

dn = d2 + log(|S|),

where log(|S|) is the logarithm of the determinant of residual covariance S.

The log(|S|) term accounts for tracks that are coasted, meaning that they are predicted but have not had an update for a long time. Tracks in this state can make S very large, resulting in a smaller Mahalanobis distance relative to the updated tracks. This difference in distance values can cause the coasted tracks to incorrectly take detections from the updated tracks. The log(|S|) term compensates for this effect by penalizing such tracks, whose predictions are highly uncertain.