trackerGNN

Multi-sensor, multi-object tracker using GNN assignment

expand all in page

Description

The trackerGNN System object™ is a tracker capable of processing detections of many targets from multiple sensors. The tracker uses a global nearest-neighbor (GNN) assignment algorithm. The tracker initializes, confirms, predicts, corrects, 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 vector covariance matrix for each track. Each detection is assigned to at most one track. If the detection cannot be assigned to any track, the tracker initializes 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. If the detection already has a known classification (the ObjectClassID field of the returned track is nonzero), that 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 objects using this object:

  1. Create the trackerGNN object and set its properties.

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

To learn more about how System objects work, see What Are System Objects?.

Creation

Syntax

tracker = trackerGNN
tracker = trackerGNN(Name,Value)

Description

tracker = trackerGNN creates a trackerGNN System object with default property values.

example

tracker = trackerGNN(Name,Value) sets properties for the tracker using one or more name-value pairs. For example, trackerGNN('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.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Unique tracker identifier, specified as a nonnegative integer. This property is used as the SourceIndex in the tracker outputs, and distinguishes tracks that come from different trackers in a multiple-tracker system. You must specify this property as a positive integer to use the track outputs as inputs to a track fuser.

Example: 1

Filter initialization function, specified as a function handle or as a character vector containing the name of a 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.

Initialization FunctionFunction Definition
initcvabfInitialize constant-velocity alpha-beta filter
initcaabfInitialize constant-acceleration alpha-beta filter
initcvekfInitialize constant-velocity extended Kalman filter.
initcackfInitialize constant-acceleration cubature filter.
initctckfInitialize constant-turn-rate cubature filter.
initcvckfInitialize constant-velocity cubature filter.
initcapfInitialize constant-acceleration particle filter.
initctpfInitialize constant-turn-rate particle filter.
initcvpfInitialize constant-velocity particle filter.
initcvkfInitialize constant-velocity linear Kalman filter.
initcvukfInitialize constant-velocity unscented Kalman filter.
initcaekfInitialize constant-acceleration extended Kalman filter.
initcakfInitialize constant-acceleration linear Kalman filter.
initcaukf Initialize constant-acceleration unscented Kalman filter.
initctekf Initialize constant-turn-rate extended Kalman filter.
initctukfInitialize constant-turn-rate unscented Kalman filter.
initcvmscekfInitialize constant-velocity modified spherical coordinates extended Kalman filter.
initrpekfInitialize constant-velocity range-parametrized extended Kalman filter.
initapekfInitialize constant-velocity angle-parametrized extended Kalman filter.
initekfimmInitialize tracking IMM filter.
initsingerekfInitialize singer acceleration extended Kalman filter.

You can also write your own initialization function. The function must have 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 a filter object: trackingKF, trackingEKF, trackingUKF, trackingCKF, trackingPF, trackingMSCEKF, trackingGSF, trackingIMM, or trackingABF.

To guide you in writing this function, you can examine the details of the supplied functions from within MATLAB®. For example:

type initcvekf

Data Types: function_handle | char

Assignment algorithm, specified as 'MatchPairs', 'Munkres', 'Jonker-Volgenant', 'Auction', or 'Custom'. Munkres is the only assignment algorithm that guarantees an optimal solution, but it is also the slowest, especially for large numbers of detections and tracks. The other algorithms do not guarantee an optimal solution but can be faster for problems with 20 or more tracks and detections. Use'Custom' to define your own assignment function and specify its name in the CustomAssignmentFcn property.

Example: 'Custom'

Data Types: char

Custom assignment function name, specified as a character string. An assignment function must have the following syntax:

 [assignment,unTrs,unDets] = f(cost,costNonAssignment)
For an example of an assignment function and a description of its arguments, see assignmunkres.

Dependencies

To enable this property, set the Assignment property to 'Custom'.

Data Types: char

Detection assignment threshold (or gating threshold), specified as a positive scalar or an 1-by-2 vector of [C1,C2], where C1≤C2. If specified as a scalar, the specified value, val, will be 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 their accurate normalized distance is less than C1. See the distance function used with tracking filters (for example, trackingCKF and trackingEKF) for an explanation of the distance calculation.

Tips:

  • Increase the value of C2 if there are combinations of track and detection that should be calculated for assignment but are not. Decrease it 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 it if there are detections that are assigned to tracks they should not be assigned to (too far away).

Confirmation and deletion logic type, specified as 'History' or 'Score'.

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

  • 'Score' – Track confirmation and deletion is based on a log-likelihood track score. A high score means that the track is more likely to be valid. A low score means that the track is more likely to be a false alarm.

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 using the TrackLogic property.

  • History – Specify the confirmation threshold as 1-by-2 vector [M N]. A track is confirmed if it receives at least M detections in the last N updates. The default value is [2,3].

  • Score – Specify the confirmation threshold as a scalar. A track is confirmed if its score is at least as high as the confirmation threshold. The default value is 20.

Data Types: single | double

Minimum score required to delete track, 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 using the TrackLogic property:

  • History – Specify the confirmation threshold as [P R]. If a confirmed track is not assigned to any detection P times in the last R tracker updates, then the track is deleted.

  • Score – A track is deleted if its score decreases by at least the threshold from the maximum track score.

Example: 3

Data Types: single | double

Probability of detection, specified as a positive scalar between 0 and 1. This property is used to compute track score.

Example: 0.5

Data Types: single | double

The probability of false alarm, specified as a scalar. This property is used to compute track score.

Example: 1e-5

Data Types: single | double

The rate of new tracks per unit volume, specified as a positive scalar. The rate of new tracks is used in calculating the track score during track initialization.

Example: 2.5

Data Types: single | double

The volume of a sensor measurement bin, specified as a positive scalar. For example, if a radar produces a 4-D measurement, which includes azimuth, elevation, range, and range rate, the 4-D volume is defined by the radar angular beam width, the range bin width and the range-rate bin width. Volume is used in calculating the track score when initializing and updating a track.

Example: 1.5

Data Types: single | double

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 fields each output track can have.

Data Types: single | double

Parameters of the track state reference frame, specified as a structure array. Use this property to define the track state reference frame and how to transform the track from the tracker coordinate system, the source system, to the fuser coordinate system.

Tunable: Yes

Data Types: struct

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 tells the tracker of all tracks that the sensors are expected to detect and, optionally, the probability of detection for each track.

Data Types: logical

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

This property is read-only.

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

Data Types: double

This property is read-only.

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: 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, detections, at the update time, time. Confirmed tracks are corrected and predicted to the update time.

confirmedTracks = tracker(detections,time,costMatrix) also specifies a cost matrix, costMatrix.

To enable this syntax, set the HasCostMatrixInput property to true.

confirmedTracks = tracker(___,detectableTrackIDs) also specifies a list of expected detectable tracks, detectableTrackIDs.

To enable this syntax, set the HasDetectableTrackIDsInput property to true.

[confirmedTracks,tentativeTracks,allTracks] = tracker(___) also returns a list of tentative tracks, tentativeTracks, and a list of all tracks, allTracks.

[confirmedTracks,tentativeTracks,allTracks,analysisInformation] = tracker(___) also returns information, analysisInformation, which can be used for track analysis.

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. Also, the Time differences between different objectDetection objects in the cell array do not need to be equal.

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 N-by-M matrix, where N is the number of existing tracks, and M is the number of current detections. The cost matrix rows must be in the same order as the list of tracks. 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 is the tracker is updated.

At the first update of the object or when the tracker has no previous tracks, specify the cost matrix to have a size of [0,numDetections]. Note that the cost must be calculated 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, 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 second column contains the 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 as undetectable. The track deletion logic does not count the lack of detection 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, returned as an array of objectTrack objects in MATLAB, and returned as an array of structures in code generation. In code generation, the field names of the returned structure are same with the property names of objectTrack.

A track is confirmed if it satisfies the confirmation threshold specified in the ConfirmationThreshold property. In that case, the IsConfirmed property of the object or field of the structure is true.

Data Types: struct | object

Tentative tracks, returned as an array of objectTrack objects in MATLAB, and returned as an array of structures in code generation. In code generation, the field names of the returned structure are same with the property names of objectTrack.

A track is tentative if it does not satisfy the confirmation threshold specified in the ConfirmationThreshold property. In that case, the IsConfirmed property of the object or field of the structure is false.

Data Types: struct | object

All tracks, returned as an array of objectTrack objects in MATLAB, and returned as an array of structures in code generation. In code generation, the field names of the returned structure are same with the property names of objectTrack. All tracks consists of confirmed and tentative tracks.

Data Types: struct | object

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

FieldDescription
TrackIDsAtStepBeginning

Track IDs when step began

CostMatrix

Cost of assignment matrix

Assignments

Assignments returned from the assignment function.

UnassignedTracks

IDs of unassigned tracks returned from the tracker

UnassignedDetections

Indices of unassigned detections in the detections input.

InitiatedTrackIDs

IDs of tracks initiated during the step

DeletedTrackIDs

IDs of tracks deleted during the step

TrackIDsAtStepEnd

Track IDs when the step ended

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

getTrackFilterPropertiesObtain track filter properties
setTrackFilterPropertiesSet track filter properties
predictTrackToTimePredict track state
initializeTrackInitialize new track
deleteTrackDelete existing track
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object
isLockedDetermine if System object is in use
cloneCreate duplicate System object

Examples

collapse all

Open Live Script

Construct a trackerGNN object with the default 2-D constant-velocity Kalman filter initialization function, initcvkf.

tracker = trackerGNN('FilterInitializationFcn', @initcvkf, ...
    'ConfirmationThreshold', [4 5], ...
    'DeletionThreshold', 10);

Update the tracker with two detections both having nonzero ObjectClassID. These detections immediately create confirmed tracks.

detections = {objectDetection(1,[10;0],'SensorIndex',1, ...
    'ObjectClassID',5,'ObjectAttributes',{struct('ID',1)}); ...
    objectDetection(1,[0;10],'SensorIndex',1, ...
    'ObjectClassID',2,'ObjectAttributes',{struct('ID',2)})};
time = 2;
tracks = tracker(detections,time);

Find the positions and velocities.

positionSelector = [1 0 0 0; 0 0 1 0];
velocitySelector = [0 1 0 0; 0 0 0 1];

positions = getTrackPositions(tracks,positionSelector)
positions = 2×2

    10     0
     0    10


velocities = getTrackVelocities(tracks,velocitySelector)
velocities = 2×2

     0     0
     0     0

Algorithms

expand all

References

[1] Blackman, S., and R. Popoli. Design and Analysis of Modern Tracking Systems. Artech House Radar Library, Boston, 1999.

Extended Capabilities

See Also

Functions

Objects

System Objects

Topics

Introduced in R2018b

Sensor Fusion and Tracking Toolbox Documentation

Support