Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

# trackerJPDA

Joint probabilistic data association tracker

## Description

The `trackerJPDA` System object™ is a tracker capable of processing detections of multiple targets from multiple sensors. The tracker uses Joint probabilistic data association to assign detections to each track. The tracker applies a soft assignment where multiple detections can contribute to each track. The tracker initializes, confirms, corrects, predicts (performs coasting), and deletes tracks. Inputs to the tracker are detection reports generated by `objectDetection`, `radarSensor`, `monostaticRadarSensor`, `irSensor`, or `sonarSensor` objects. The tracker estimates the state vector and state estimate error covariance matrix for each track. Each detection is assigned to at least one track. If the detection cannot be assigned to any existing track, the tracker creates a new track.

Any new track starts in a tentative state. If enough detections are assigned to a tentative track, its status changes to confirmed (see the `ConfirmationThreshold` property). If the detection already has a known classification (i.e., the `ObjectClassID` field of the returned track is nonzero), that corresponding track is confirmed immediately. When a track is confirmed, the tracker considers the track to represent a physical object. If detections are not assigned to the track within a specifiable number of updates, the track is deleted.

To track targets using this object:

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

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

## Creation

### Syntax

``tracker = trackerJPDA``
``tracker = trackerJPDA(Name,Value)``

### Description

````tracker = trackerJPDA` creates a `trackerJPDA` System object with default property values.```

example

````tracker = trackerJPDA(Name,Value)` sets properties for the tracker using one or more name-value pairs. For example, `trackerJPDA('FilterInitializationFcn',@initcvukf,'MaxNumTracks',100)` creates a multi-object tracker that uses a constant-velocity, unscented Kalman filter and allows a maximum of 100 tracks. Enclose each property name 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.

Filter initialization function, specified as a function handle or as a character vector containing the name of a valid filter initialization function. The tracker uses a filter initialization function when creating new tracks.

Sensor Fusion and Tracking Toolbox™ supplies many initialization functions that you can use to specify `FilterInitializationFcn` for a `trackerJPDA` object.

Initialization FunctionFunction Definition
`initcvkf`Initialize constant-velocity linear Kalman filter.
`initcakf`Initialize constant-acceleration linear Kalman filter.
`initcvabf`Initialize constant-velocity alpha-beta filter
`initcaabf`Initialize constant-acceleration alpha-beta filter
`initcvekf`Initialize constant-velocity extended Kalman filter.
`initcaekf`Initialize constant-acceleration extended Kalman filter.
`initrpekf`Initialize constant-velocity range-parametrized extended Kalman filter.
`initapekf`Initialize constant-velocity angle-parametrized extended Kalman filter.
`initctekf `Initialize constant-turn-rate extended Kalman filter.
`initcackf`Initialize constant-acceleration cubature filter.
`initctckf`Initialize constant-turn-rate cubature filter.
`initcvckf`Initialize constant-velocity cubature filter.
`initcvukf`Initialize constant-velocity unscented Kalman filter.
`initcaukf `Initialize constant-acceleration unscented Kalman filter.
`initctukf`Initialize constant-turn-rate unscented Kalman filter.
`initcvmscekf`Initialize constant-velocity extended Kalman filter in modified spherical coordinates.
`initekfimm`Initialize tracking IMM filter.

You can also write your own initialization function using the following syntax:

`filter = filterInitializationFcn(detection)`
The input to this function is a detection report like those created by `objectDetection`. The output of this function must be an object belonging to one of the filter classes: `trackingKF`, `trackingEKF`, `trackingUKF`, `trackingCKF`, `trackingGSF`, `trackingIMM`, `trackingMSCEKF`, or `trackingABF`.

For guidance in writing this function, use the `type` command to examine the details of built-in MATLAB® functions. For example:

``type` `initcvekf``

### Note

`trackerJPDA` does not accept all filter initialization functions in Sensor Fusion and Tracking Toolbox. The full list of filter initialization functions available in Sensor Fusion and Tracking Toolbox are given in Initialization.

Data Types: `function_handle` | `char`

Feasible joint events generation function, specified as a function handle or as a character vector containing the name of a feasible joint events generation function. A generation function generates feasible joint event matrices from admissible events (usually given by a validation matrix) of a tracking scenario. A validation matrix is a binary matrix listing all possible detections-to-track associations. For details, see `jpadEvents`.

You can also write your own generation function. The function must have the following syntax:

`FJE = myfunction(ValidationMatrix)`
The input and out of this function must exactly follow the formats used in `jpdaEvents`. For guidance in writing this function, use the `type` command to examine the details of `jpdaEvents`:

`type jpdaEvents`

Example: `@myfunction` or `'myfunction'`

Data Types: `function_handle` | `char`

Maximum number of tracks that the tracker can maintain, specified as a positive integer.

Data Types: `single` | `double`

Maximum number of sensors that can be connected to the tracker, specified as a positive integer. `MaxNumSensors` must be greater than or equal to the largest value of `SensorIndex` found in all the detections used to update the tracker. `SensorIndex` is a property of an `objectDetection` object. The `MaxNumSensors` property determines how many sets of `ObjectAttributes` each track can have.

Data Types: `single` | `double`

Detection assignment threshold (or gating threshold), specified as a positive scalar or 1-by-2 vector of [C1,C2], where C1C2. If specified as a scalar, the specified value, val, is expanded to [val, `Inf`].

Initially, the tracker executes a coarse estimation for the normalized distance between all the tracks and detections. The tracker only calculates the accurate normalized distance for the combinations whose coarse normalized distance is less than C2. Also, the tracker can only assign a detection to a track if the accurate normalized distance between them is less than C1. See the `distance` method of each tracking filter (such as `trackingCKF` and `trackingEKF`) for explanation of the distance calculation.

Tips:

• Increase the value of C2 if there are track and detection combinations that should be calculated for assignment but are not. Decrease this value if cost calculation takes too much time.

• Increase the value of C1 if there are detections that should be assigned to tracks but are not. Decrease this value if there are detections that are assigned to tracks they should not be assigned to (too far away).

Probability of detection, specified as a scalar in the range [0,1]. This property is used in calculations of the marginal posterior probabilities of association and the probability of track existence when initializing and updating a track.

Example: `0.85`

Data Types: `single` | `double`

The probability threshold to initialize a new track, specified as a scalar in the range [0,1]. If the probabilities of associating a detection with any of the existing tracks are all smaller than `InitializationThreshold`, the detection will be used to initialize a new track. This allows detections that are within the validation gate of a track but have an association probability lower than the initialization threshold to spawn a new track.

Example: `0.1`

Data Types: `single` | `double`

Confirmation and deletion logic type, specified as:

• `'History'` – Track confirmation and deletion is based on the number of times the track has been assigned to a detection in the latest tracker updates.

• `'Integrated'` – Track confirmation and deletion is based on the probability of track existence, which is integrated in the assignment function.

Threshold for track confirmation, specified as a scalar or a 1-by-2 vector. The threshold depends on the type of track confirmation and deletion logic you set with the `TrackLogic` property:

• `'History'` – Specify the confirmation threshold as 1-by-2 vector [M N]. A track is confirmed if it recorded at least M hits in the last N updates. The `trackerJPDA` registers a hit on a track’s history logic according to the `HitMissThrehold`. The default value is `[2 3]`.

• `'Integrated'` – Specify the confirmation threshold as a scalar. A track is confirmed if its probability of existence is greater than or equal to the confirmation threshold. The default value is `0.95`.

Data Types: `single` | `double`

Threshold for track deletion, specified as a scalar or a real-valued 1-by-2 vector. The threshold depends on the type of track confirmation and deletion logic you set with the `TrackLogic` property:

• `'History'` – Specify the confirmation threshold as [P R]. A track is deleted if it recorded at least P misses in the last R updates. The `trackerJPDA` will register a miss on a track’s history logic according to the `HitMissThrehold` property. The default value is `[5,5]`.

• `'Integrated'` – Specify the deletion threshold as a scalar. A track is deleted if its probability of existence drops below the threshold. The default value is `0.1`.

Example: `0.2` or `[5,6]`

Data Types: `single` | `double`

Threshold for registering a hit or miss, specified as a scalar in the range [0,1]. The track history logic will register a miss and the track will be coasted if the sum of the marginal probabilities of assignments is below the `HitMissThreshold`. Otherwise, the track history logic will register a hit.

Example: `0.3`

#### Dependencies

To enable this argument, set the `TrackLogic` property to `'History'`.

Data Types: `single` | `double`

Spatial density of clutter measurements, specified as a positive scalar. The clutter density describes the expected number of false positive detections per unit volume. It is used as the parameter of a Poisson clutter model. When `TrackLogic` is set to `'Integrated'`, `ClutterDensity` is also used in calculating the initial probability of track existence.

Example: `1e-5`

Data Types: `single` | `double`

Spatial density of new targets, specified as a positive scalar. The new target density describes the expected number of new tracks per unit volume in the measurement space. It is used in calculating the probability of track existence during track initialization.

Example: `1e-3`

#### Dependencies

To enable this argument, set the `TrackLogic` property to `'Integrated'`.

Data Types: `single` | `double`

Time rate of target deaths, specified as a scalar in the range [0,1]. `DeathRate` describes the probability with which true targets disappear. It is related to the propagation of the probability of track existence (PTE) :

where δt is the time interval since the previous update time t.

#### Dependencies

To enable this argument, set the `TrackLogic` property to `'Integrated'`.

Data Types: `single` | `double`

Initial probability of track existence, specified as a scalar in the range [0,1] and calculated as ```InitialExistenceProbability = NewTargetDensity*DetectionProbability/(ClutterDensity + NewTargetDensity*DetectionProbability)```.

#### Dependencies

To enable this property, set the `TrackLogic` property to `'Integrated'`. When the `TrackLogic` property is set to `'History'`, this property is not available.

Data Types: `single` | `double`

Enable a cost matrix, specified as `false` or `true`. If `true`, you can provide an assignment cost matrix as an input argument when calling the object.

Data Types: `logical`

Enable the input of detectable track IDs at each object update, specified as `false` or `true`. Set this property to `true` if you want to provide a list of detectable track IDs. This list informs the tracker of all tracks that the sensors are expected to detect and, optionally, the probability of detection for each track.

Data Types: `logical`

Number of tracks maintained by the tracker, returned as a nonnegative integer.

Data Types: `single` | `double`

Number of confirmed tracks, returned as a nonnegative integer. If the `IsConfirmed` field of an output track structure is `true`, the track is confirmed.

Data Types: `single` | `double`

Absolute time tolerance between detections for the same sensor, specified as a positive scalar. Ideally, `trackerJPDA` expects detections from a sensor to have identical time stamps. However, if the time stamps differences between detections of a sensor are within the margin specified by `TimeTolerance`, these detections will be used to update the track estimate based on the average time of these detections.

Data Types: `double`

## Usage

To process detections and update tracks, call the tracker with arguments, as if it were a function (described here).

### Syntax

``confirmedTracks = tracker(detections,time)``
``confirmedTracks = tracker(detections,time,costMatrix)``
``confirmedTracks = tracker(___,detectableTrackIDs)``
``[confirmedTracks,tentativeTracks,allTracks] = tracker(___)``
``[confirmedTracks,tentativeTracks,allTracks,analysisInformation] = tracker(___)``

### Description

````confirmedTracks = tracker(detections,time)` returns a list of confirmed tracks that are updated from a list of detections at the update time. Confirmed tracks are corrected and predicted to the update time.```
````confirmedTracks = tracker(detections,time,costMatrix)` also specifies a cost matrix. To enable this syntax, set the `HasCostMatrixInput` property to `true`.```
````confirmedTracks = tracker(___,detectableTrackIDs)` also specifies a list of expected detectable tracks given by `detectableTrackIDs`. This argument can be used with any of the previous input syntaxes.To enable this syntax, set the `HasDetectableTrackIDsInput` property to `true`.```
````[confirmedTracks,tentativeTracks,allTracks] = tracker(___)` also returns a list of tentative tracks and a list of all tracks. You can use any of the input arguments in the previous syntaxes.```
````[confirmedTracks,tentativeTracks,allTracks,analysisInformation] = tracker(___)` also returns analysis information that can be used for track analysis. You can use any of the input arguments in the previous syntaxes.```

### Input Arguments

expand all

Detection list, specified as a cell array of `objectDetection` objects. The `Time` property value of each `objectDetection` object must be less than or equal to the current update time, `time`, and greater than the previous time value used to update the tracker.

Time of update, specified as a scalar. The tracker updates all tracks to this time. Units are in seconds.

`time` must be greater than or equal to the largest `Time` property value of the `objectDetection` objects in the input `detections` list. `time` must increase in value with each update to the tracker.

Data Types: `single` | `double`

Cost matrix, specified as a real-valued M-by-N matrix, where M is the number of existing tracks in the previous update, and N is the number of current detections. The cost matrix rows must be in the same order as the list of tracks, and the columns must be in the same order as the list of detections. Obtain the correct order of the list of tracks from the third output argument, `allTracks`, when the tracker is updated.

At the first update of the tracker or when the tracker has no previous tracks, specify the cost matrix to be empty with a size of `[0,numDetections]`. Note that the cost must be given so that lower costs indicate a higher likelihood of assigning a detection to a track. To prevent certain detections from being assigned to certain tracks, you can set the appropriate cost matrix entry to `Inf`.

#### Dependencies

To enable this argument, set the `HasCostMatrixInput` property to `true`.

Data Types: `double` | `single`

Detectable track IDs, specified as a real-valued M-by-1 vector or M-by-2 matrix. Detectable tracks are tracks that the sensors expect to detect. The first column of the matrix contains a list of track IDs that the sensors report as detectable. The optional second column contains the corresponding detection probability for the track. The detection probability is either reported by a sensor or, if not reported, obtained from the `DetectionProbability` property.

Tracks whose identifiers are not included in `detectableTrackIDs` are considered undetectable. In this case, the track deletion logic does not count the lack of detection for that track as a missed detection for track deletion purposes.

#### Dependencies

To enable this input argument, set the `detectableTrackIDs` property to `true`.

Data Types: `single` | `double`

### Output Arguments

expand all

Confirmed tracks updated to the current time, returned as a structure or array of structures. Each structure corresponds to a track. The confirmation of a track depends on the track logic.

• `'History'`– A track is confirmed if it recorded enough hits during the last few updates to satisfy the `ConfirmationThreshold`.

• `'Integrated'`– A track is confirmed if its probability of existence is higher than the `ConfirmationThreshold` property value.

If a track is confirmed, the `IsConfirmed` field of the structure is `true`. The fields of the confirmed tracks structure are defined in Track Structure.

Data Types: `struct`

Tentative tracks, returned as a structure or array of structures. Each structure corresponds to a track. A track is tentative if the track is not assigned to enough detections and the track cannot be associated with any classified object given by the `ObjectClassID`. In that case, the `IsConfirmed` field of the structure is `false`. The fields of the structure are defined in Track Structure.

Data Types: `struct`

All tracks, returned as a structure or array of structures. Each structure corresponds to a track. The set of all tracks consists of confirmed and tentative tracks. The fields of the structure are defined in Track Structure.

Data Types: `struct`

Additional information for analyzing track updates, returned as a structure. The fields of this structure are:

 Field Description `TrackIDsAtStepBeginning` Track IDs when step began. `CostMatrix` Cost matrix for assignment. `Clusters` Cell array of cluster reports. `InitiatedTrackIDs` IDs of tracks initiated during the step. `DeletedTrackIDs` IDs of tracks deleted during the step. `TrackIDsAtStepEnd` Track IDs when the step ended.

The `Clusters` field can include multiple cluster reports. Each cluster report is a structure containing:

 Field Description `DetectionIndices` Indices of clustered detections. `TrackIDs` Track IDs of clustered tracks. `ValidationMatrix` Validation matrix of the cluster. See `jpadEvents` for more details. `SensorIndex` Index of the originating sensor of the clustered detections. `TimeStamp` Mean time stamp of clustered detections. `MarginalProbabilities` Matrix of marginal posterior joint association probabilities.

Data Types: `struct`

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

 `predictTracksToTime` Predict track state `getTrackFilterProperties` Obtain track filter properties `setTrackFilterProperties` Set track filter properties
 `step` Run System object algorithm `release` Release resources and allow changes to System object property values and input characteristics `isLocked` Determine if System object is in use `clone` Create duplicate System object `reset` Reset internal states of System object

## Examples

expand all

Construct a trackerJPDA object with a default constant velocity Extended Kalman Filter and 'History' track logic. Set AssignmentThreshold to 100 to allow tracks to be jointly associated.

```tracker = trackerJPDA('TrackLogic','History', 'AssignmentThreshold',100,... 'ConfirmationThreshold', [4 5], ... 'DeletionThreshold', [10 10]); ```

Specify the true initial positions and velocities of the two objects.

```pos_true = [0 0 ; 40 -40 ; 0 0]; V_true = 5*[cosd(-30) cosd(30) ; sind(-30) sind(30) ;0 0]; ```

Create a theater plot to visualize tracks and detections.

```tp = theaterPlot('XLimits',[-1 150],'YLimits',[-50 50]); trackP = trackPlotter(tp,'DisplayName','Tracks','MarkerFaceColor','g','HistoryDepth',0); detectionP = detectionPlotter(tp,'DisplayName','Detections','MarkerFaceColor','r'); ```

To obtain the position and velocity, create position and velocity selectors.

```positionSelector = [1 0 0 0 0 0; 0 0 1 0 0 0; 0 0 0 0 0 0]; % [x, y, 0] velocitySelector = [0 1 0 0 0 0; 0 0 0 1 0 0; 0 0 0 0 0 0 ]; % [vx, vy, 0] ```

Update the tracker with detections, display cost and marginal probability of association information, and visualize tracks with detections.

```dt = 0.2; for time = 0:dt:30 % Update the true positions of objects. pos_true = pos_true + V_true*dt; % Create detections of the two objects with noise. detection(1) = objectDetection(time,pos_true(:,1)+1*randn(3,1)); detection(2) = objectDetection(time,pos_true(:,2)+1*randn(3,1)); % Step the tracker through time with the detections. [confirmed,tentative,alltracks,info] = tracker(detection,time); % Extract position, velocity and label info. [pos,cov] = getTrackPositions(confirmed,positionSelector); vel = getTrackVelocities(confirmed,velocitySelector); meas = cat(2,detection.Measurement); measCov = cat(3,detection.MeasurementNoise); % Update the plot if there are any tracks. if numel(confirmed)>0 labels = arrayfun(@(x)num2str([x.TrackID]),confirmed,'UniformOutput',false); trackP.plotTrack(pos,vel,cov,labels); end detectionP.plotDetection(meas',measCov); drawnow; % Display the cost and marginal probability of distribution every eight % seconds. if time>0 && mod(time,8) == 0 disp(['At time t = ' num2str(time) ' seconds,']); disp('The cost of assignment was: ') disp(info.CostMatrix); disp(['Number of clusters: ' num2str(numel(info.Clusters))]); if numel(info.Clusters) == 1 disp('The two tracks were in the same cluster.') disp('Marginal probabilities of association:') disp(info.Clusters{1}.MarginalProbabilities) end disp('-----------------------------') end end ```
```At time t = 8 seconds, The cost of assignment was: 1.0e+03 * 0.0020 1.1523 1.2277 0.0053 Number of clusters: 2 ----------------------------- At time t = 16 seconds, The cost of assignment was: 1.3968 4.5123 2.0747 1.9558 Number of clusters: 1 The two tracks were in the same cluster. Marginal probabilities of association: 0.8344 0.1656 0.1656 0.8344 0.0000 0.0000 ----------------------------- At time t = 24 seconds, The cost of assignment was: 1.0e+03 * 0.0018 1.2962 1.2664 0.0013 Number of clusters: 2 ----------------------------- ```

expand all

expand all

## References

[1] Fortmann, T., Y. Bar-Shalom, and M. Scheffe. "Sonar Tracking of Multiple Targets Using Joint Probabilistic Data Association." IEEE Journal of Ocean Engineering. Vol. 8, Number 3, 1983, pp. 173-184.

[2] Musicki, D., and R. Evans. "Joint Integrated Probabilistic Data Association: JIPDA." IEEE transactions on Aerospace and Electronic Systems . Vol. 40, Number 3, 2004, pp 1093-1099.

Get trial now