trackerGNN
Multi-sensor, multi-object tracker using GNN assignment
Description
The trackerGNN
System object™ is a tracker capable of processing detections of multiple targets from multiple
sensors using the 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
, fusionRadarSensor
,
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:
Create the
trackerGNN
object and set its properties.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
Description
creates a
tracker
= trackerGNNtrackerGNN
System object with default property values.
sets properties for the tracker using one or more name-value pairs. For example,
tracker
= trackerGNN(Name,Value
)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
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.
TrackerIndex
— Unique tracker identifier
0
(default) | nonnegative integer
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
FilterInitializationFcn
— Filter initialization function
@initcvekf
(default) | function handle | character vector
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 Function | Function Definition |
---|---|
initcvabf | Initialize constant-velocity alpha-beta filter |
initcaabf | Initialize constant-acceleration alpha-beta filter |
initcvekf | Initialize constant-velocity extended Kalman filter. |
initcackf | Initialize constant-acceleration cubature filter. |
initctckf | Initialize constant-turn-rate cubature filter. |
initcvckf | Initialize constant-velocity cubature filter. |
initcapf | Initialize constant-acceleration particle filter. |
initctpf | Initialize constant-turn-rate particle filter. |
initcvpf | Initialize constant-velocity particle filter. |
initcvkf | Initialize constant-velocity linear Kalman filter. |
initcvukf | Initialize constant-velocity unscented Kalman filter. |
initcaekf | Initialize constant-acceleration extended Kalman filter. |
initcakf | Initialize constant-acceleration linear Kalman filter. |
initcaukf | Initialize constant-acceleration unscented Kalman filter. |
initctekf | Initialize constant-turn-rate extended Kalman filter. |
initctukf | Initialize constant-turn-rate unscented Kalman filter. |
initctrvekf | Initialize constant-turn-rate and velocity magnitude extended Kalman filter. |
initctrvukf | Initialize constant-turn-rate and velocity magnitude unscented Kalman filter. |
initcvmscekf | Initialize constant-velocity modified spherical coordinates extended Kalman filter. |
initrpekf | Initialize constant-velocity range-parametrized extended Kalman filter. |
initapekf | Initialize constant-velocity angle-parametrized extended Kalman filter. |
initekfimm | Initialize tracking IMM filter. |
initsingerekf | Initialize singer acceleration extended Kalman filter. |
initvisionbboxkf | Initialize constant-velocity linear Kalman filter for 2-D axis-aligned bounding box. |
You can also write your own initialization function. The function must have the following syntax:
filter = filterInitializationFcn(detection)
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
— Assignment algorithm
'MatchPairs'
(default) | 'Munkres'
| 'Jonker-Volgenant'
| 'Auction'
| 'Custom'
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
CustomAssignmentFcn
— Custom assignment function
character vector
Custom assignment function name, specified as a character string. An assignment function must have the following syntax:
[assignment,unTrs,unDets] = f(cost,costNonAssignment)
assignmunkres
.
Dependencies
To enable this property, set the Assignment
property to
'Custom'
.
Data Types: char
AssignmentClustering
— Clustering of detections and tracks for assignment
'off'
(default) | 'on'
Clustering of detections and tracks for assignment, specified as
'off'
or 'on'
.
'off'
— The tracker solves the global nearest neighbor assignment problem per sensor using a cost matrix. The number of columns in the cost matrix is equal to the number of detections by the sensor, and the number of rows is equal to the number of tracks maintained by the tracker. Forbidden assignments (assignments with a cost greater than theAssignmentThreshold
) have an infinite cost of assignment.'on'
— The tracker creates a cluster after separating out the forbidden assignments (assignments with a cost greater than theAssignmentThreshold
) and uses the forbidden assignments to form new clusters based on theAssignmentThreshold
property. A cluster is a collection of detections and tracks considered to be assigned to each other. In this case, the tracker solves the global nearest neighbor assignment problem per cluster.When you both specify this property as
'on'
and specify theEnableMemoryManagement
property astrue
, you can use these three properties to specify bounds for certain variable-sized arrays in the tracker, as well as determine how the tracker handles cluster-size violations:MaxNumDetectionsPerCluster
MaxNumTracksPerCluster
ClusterViolationHandling
Specifying bounds for variable-sized arrays enables you to manage the memory footprint of the tracker, especially in the generated C/C++ code.
Data Types: char
| string
AssignmentThreshold
— Detection assignment threshold
30*[1 Inf]
(default) | positive scalar | 1-by-2 vector of positive values
Detection assignment threshold (or gating threshold), specified as a positive scalar
or a 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 Algorithms for an explanation of the normalized distance.
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).
Note
If the value of C2 is finite, the state transition function and measurement function, specified in the tracking filter used in the tracker, must be able to take an M-by-N matrix of states as input and output N predicted states and N measurements, respectively. M is the size of the state. N, the number of states, is an arbitrary nonnegative integer.
Tunable: Yes
TrackLogic
— Confirmation and deletion logic type
'History'
(default) | 'Score'
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.
ConfirmationThreshold
— Threshold for track confirmation
scalar | 1-by-2 vector
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 leastM
detections in the lastN
updates. The default value is[2,3]
.Score – Specify the confirmation threshold as a positive scalar. A track is confirmed if its score is at least as high as the confirmation threshold. The default value is
20
.
Note
This property is tunable only when you set the TrackLogic
property to 'Score'
.
Tunable: Yes
Data Types: single
| double
DeletionThreshold
— Minimum score required to delete track
[5 5]
or -7
(default) | scalar | real-valued 1-by-2 vector of positive values
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 detectionP
times in the lastR
tracker updates, then the track is deleted.Score – Specify the confirmation threshold as a negative scalar. A track is deleted if its score decreases by at least the threshold from the maximum track score.
Note
This property is tunable only when you set the TrackLogic
property to 'Score'
.
Example: 3
Tunable: Yes
Data Types: single
| double
DetectionProbability
— Probability of detection used for track score
0.9
(default) | positive scalar between 0 and 1
Probability of detection, specified as a positive scalar between 0 and 1. This property is used to compute track score.
Example: 0.5
Tunable: Yes
Data Types: single
| double
FalseAlarmRate
— Probability of false alarm used for track score
1e-6
(default) | scalar
The probability of false alarm, specified as a scalar. This property is used to compute track score.
Example: 1e-5
Tunable: Yes
Data Types: single
| double
Beta
— Rate of new tracks per unit volume
1
(default) | positive scalar
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
Tunable: Yes
Data Types: single
| double
Volume
— Volume of sensor measurement bin
1
(default) | positive scalar
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
Tunable: Yes
Data Types: single
| double
MaxNumTracks
— Maximum number of tracks
100
(default) | positive integer
Maximum number of tracks that the tracker can maintain, specified as a positive integer.
Data Types: single
| double
MaxNumSensors
— Maximum number of sensors
20
(default) | positive integer
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
MaxNumDetections
— Maximum number of detections
Inf
(default) | positive integer
Maximum number of detections that the tracker can take as inputs, specified as a positive integer.
Data Types: single
| double
OOSMHandling
— Handling of out-of-sequence measurement (OOSM)
'Terminate'
(default) | 'Neglect'
| 'Retrodiction'
Handling of out-of-sequence measurement (OOSM), specified as
'Terminate'
, 'Neglect'
, or
'Retrodiction'
. Each detection has an associated timestamp,
td, and the tracker has its own timestamp,
tt, which is updated in each call to the
tracker. The tracker considers a measurement as an OOSM if
td <
tt.
When you specify this property as
'Terminate'
— The tracker stops running when it encounters an out-of-sequence measurement.'Neglect'
— The tracker neglects any out-of-sequence measurements and continues to run.'Retrodiction'
— The tracker uses a retrodiction algorithm to update the tracker by either neglecting the OOSM, updating existing tracks, or creating new tracks using the OOSM. You must specify a filter initialization function that returns atrackingKF
,trackingEKF
, ortrackingIMM
object in theFilterInitializationFcn
property.
If you specify this property as 'Retrodiction'
, the
tracker follows these steps to handle the OOSM:
If the OOSM timestamp is beyond the oldest correction timestamp (specified by the
MaxNumOOSMSteps
property) maintained by the tracker, the tracker discards the OOSMs.If the OOSM timestamp is within the oldest correction timestamp maintained by the tracker, the tracker first retrodicts all the existing tracks to the time of the OOSM. Then, the tracker applies the global nearest neighbor algorithm to try to associate the OOSM to any of the retrodicted tracks.
If the tracker successfully associates the OOSM to a retrodicted track, then the tracker updates the retrodicted track using the OOSM by applying the retro-correction algorithm to obtain a current, corrected track.
If the tracker cannot associate the OOSM to any retrodicted track, then the tracker creates a new track based on the OOSM and predicts the track to the current time.
For more details on the retrodiction and retro-correction algorithms, see
Retrodiction and Retro-Correction. To simulate out-of-sequence detections, use objectDetectionDelay
.
Note
When you select
'Retrodiction'
, you cannot use the costMatrix input.
MaxNumOOSMSteps
— Maximum number of out-of-sequence measurement steps
3
(default) | positive integer
Maximum number of out-of-sequence measurement (OOSM) steps, specified as a positive integer.
Increasing the value of this property requires more memory, but enables you to call
the tracker with OOSMs that have a larger lag relative to the last timestamp. However,
as the lag increases, the impact of the OOSM on the current state of the track
diminishes. The recommended value for this property is 3
.
Dependencies
To enable this argument, set the OOSMHandling
property to
'Retrodiction'
.
StateParameters
— Parameters of track state reference frame
struct([])
(default) | struct array
Parameters of the track state reference frame, specified as a structure or a structure
array. The tracker passes its StateParameters
property values to
the StateParameters
property of the generated tracks. You can use
these parameters to define the reference frame in which the track is reported or other
desirable attributes of the generated tracks.
For example, you can use the following structure to define a rectangular reference
frame whose origin position is at [10 10 0]
meters and whose origin
velocity is [2 -2 0] meters per second with respect to the scenario frame.
Field Name | Value |
---|---|
Frame | "Rectangular" |
Position | [10 10 0] |
Velocity | [2 -2 0] |
Tunable: Yes
Data Types: struct
HasDetectableTrackIDsInput
— Enable input of detectable track IDs
false
(default) | true
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
HasCostMatrixInput
— Enable cost matrix input
false
(default) | true
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
NumTracks
— Number of tracks maintained by tracker
nonnegative integer
This property is read-only.
Number of tracks maintained by the tracker, returned as a nonnegative integer.
Data Types: double
NumConfirmedTracks
— Number of confirmed tracks
nonnegative integer
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
EnableMemoryManagement
— Enable memory management properties
false
or 0
(default) | true
or 1
Enable memory management properties, specified as a logical 1
(true
) or false
(0
).
Setting this property to true
enables you to use the
MaxNumDetectionsPerSensor
property to specify the maximum number
of detections that each sensor can pass to the tracker during one call of the
tracker.
Additionally, if the AssignmentClustering
property is
specified as 'on'
, you can use three more properties to specify
bounds for certain variable-sized arrays in the tracker as well as determine how the
tracker handles cluster-size violations:
MaxNumDetectionsPerCluster
MaxNumTracksPerCluster
ClusterViolationHandling
Specifying bounds for variable-sized arrays enables you to manage the memory footprint of the tracker in the generated C/C++ code.
Data Types: logical
MaxNumDetectionsPerSensor
— Maximum number of detections per sensor
100
(default) | positive integer
Maximum number of detections per sensor, specified as a positive integer. This property determines the maximum number of detections that each sensor can pass to the tracker in each call of the tracker.
Set this property to a finite value if you want the tracker to establish efficient
bounds on local variables for C/C++ code generation. Set this property to
Inf
if you do not want to bound the maximum number of detections
per sensor.
Dependencies
To enable this property, set the EnableMemoryManagement
property to true
.
Data Types: single
| double
MaxNumDetectionsPerCluster
— Maximum number of detections per cluster
5
(default) | positive integer
Maximum number of detections per cluster during the run-time of the tracker, specified as a positive integer.
Setting this property to a finite value enables the tracker to bound cluster sizes
and reduces the memory footprint of the tracker in generated C/C++ code. Set this
property to Inf
if you do not want to bound the maximum number of
detections per cluster.
If, during run-time, the number of detections in a cluster exceeds the specified
MaxNumDetectionsPerCluster
, the tracker reacts based on the
ClusterViolationHandling
property.
Dependencies
To enable this property, specify the AssignmentClustering
property as 'on'
and set the
EnableMemoryManagement
property to
true
.
Data Types: single
| double
MaxNumTracksPerCluster
— Maximum number of tracks per cluster
5
(default) | positive integer
Maximum number of tracks per cluster during the run-time of the tracker, specified as a positive integer.
Setting this property to a finite value enables the tracker to bound cluster sizes
and reduces the memory footprint of the tracker in generated C/C++ code. Set this
property to Inf
if you do not want to bound the maximum number of
tracks per cluster.
If, during run-time, the number of tracks in a cluster exceeds the specified
MaxNumTracksPerCluster
, the tracker reacts based on the
ClusterViolationHandling
property.
Dependencies
To enable this argument, specify the AssignmentClustering
property as 'on'
and set the
EnableMemoryManagement
property to
true
.
Data Types: single
| double
ClusterViolationHandling
— Handling of run-time violation of cluster bounds
'Split and warn'
(default) | 'Terminate'
| 'Split'
Handling of a run-time violation of cluster bounds, specified as one of these options:
'Teminate'
— The tracker reports an error if, during run-time, any cluster violates the cluster bounds specified in theMaxNumDetectionsPerCluster
andMaxNumTracksPerCluster
properties.'Split and warn'
— The tracker splits the size-violating cluster into smaller clusters using a suboptimal approach. The tracker also reports a warning to indicate the violation.'Split'
— The tracker splits the size-violating cluster into smaller clusters by using a suboptimal approach. The tracker does not report a warning.
In the suboptimal approach, the tracker separates out detections or tacks that have
the smallest likelihoods of association to other tracks or detections until the cluster
bounds are satisfied. These separated-out detections or tracks can form one or many new
clusters depends on their association likelihoods with each other and the
AssignmentThreshold
property.
Dependencies
To enable this property, specify the AssignmentClustering
property as 'on'
and set the
EnableMemoryManagement
property to
true
.
Data Types: char
| string
ClassFusionMethod
— Class fusion method
"None"
(default) | "Bayes"
Class fusion method, specified as:
"None"
— The tracker does not fuse classification information from detections. When the tracker initializes a track from a detection that has a nonzero class ID, the tracker immediately confirms the track and assigns the class ID of the detection to the track. In the subsequent updates to the track, the tracker assigns only detections with the same class ID or a class ID of 0 to the track. As a result, the track classification cannot change once established."Bayes"
— The tracker fuses classification information from detections. When the tracker initializes a tentative track from a detection, the tracker determines the class probability of the track based on the a priori class distribution and the class information of the detection. In the subsequent updates to the track, the tracker considers all possible detections for association with the track regardless of their classifications. The tracker uses the kinematic state as well as class information of the detection to calculate the detection-track assignment cost. Once the tracker assigns a detection to the track, the tracker uses the classification information of the detection to update the classification of the track.See Detection Class Fusion, [2], and [3] for details.
Data Types: char
| string
InitialClassProbabilities
— Prior class probability distribution for new tracks
1
(default) | N-element vector of nonnegative scalars that sum to
1
Prior class probability distribution for new tracks, specified as an
N-element vector of nonnegative scalars that sum to
1
. The number of vector elements must be equal to the total number
of classes.
For each objectDetection
object specified through
the detections
input, the ObjectClassID
property of the
objectDetection
object must be less than or equal to
N.
Example: [0.2 0.8]
Tunable: Yes
Data Types: single
| double
ClassFusionWeight
— Weight factor of class cost
0.7
(default) | scalar in range [0,1]
Weight factor of class cost in overall assignment cost, specified as a scalar in the
range [0,1]
. When you set the ClassFusionMethod
property to "Bayes"
, the tracker calculates the overall assignment
cost as:
where:
α — Weight factor of the class fusion cost
Ck — Kinematic assignment cost matrix obtained from the kinematic states of the tracks and detections
Cc — Class fusion assignment cost matrix obtained from the class information of tracks and detections
Tunable: Yes
Data Types: single
| double
Usage
To process detections and update tracks, call the tracker with arguments, as if it were a function (described here).
Syntax
Description
returns a list of confirmed tracks that are updated from a list of detections,
confirmedTracks
= tracker(detections
,time
)detections
, at the update time, time
.
Confirmed tracks are corrected and predicted to the update time.
also specifies a cost matrix, confirmedTracks
= tracker(detections
,time
,costMatrix
)costMatrix
.
To enable this syntax, set the HasCostMatrixInput
property to
true
.
also specifies a list of expected detectable tracks,
confirmedTracks
= tracker(___,detectableTrackIDs
)detectableTrackIDs
.
To enable this syntax, set the HasDetectableTrackIDsInput
property to true
.
[
also returns a list of tentative tracks, confirmedTracks
,tentativeTracks
,allTracks
] = tracker(___)tentativeTracks
, and a list
of all tracks, allTracks
.
[
also returns information, confirmedTracks
,tentativeTracks
,allTracks
,analysisInformation
] = tracker(___)analysisInformation
, which can be used for
track analysis.
Input Arguments
detections
— Detection list
cell array of objectDetection
objects
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
— Time of update
scalar
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
costMatrix
— Cost matrix
real-valued N-by-M matrix
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
detectableTrackIDs
— Detectable track IDs
real-valued M-by-1 vector | real-valued M-by-2 matrix
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
confirmedTracks
— Confirmed tracks
array of objectTrack
objects | array of structures
Confirmed tracks, returned as an array of objectTrack
objects in MATLAB or as an array of structures in code generation. In code
generation, the field names of the returned structure are identical to the
property names of objectTrack
.
The tracker confirms a track 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
tentativeTracks
— Tentative tracks
array of objectTrack
objects | array of structures
Tentative tracks, returned as an array of objectTrack
objects in
MATLAB or as an array of structures in code generation. In code generation, the
field names of the returned structure are identical to 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
allTracks
— All tracks
array of objectTrack
objects | array of structures
All tracks, returned as an array of objectTrack
objects in
MATLAB or as an array of structures in code generation. In code generation, the
field names of the returned structure are identical to the property names of
objectTrack
. allTracks
consists of confirmed
and tentative tracks.
Data Types: struct
| object
analysisInformation
— Additional information for analyzing track updates
structure
Additional information for analyzing track updates, returned as a structure. The fields of this structure are:
Field | Description |
OOSMDetectionIndices | Indices of out-of-sequence measurements at the current step of the tracker |
TrackIDsAtStepBeginning | Track IDs when step began |
CostMatrix | Cost matrix for kinematic assignment in which the (i, j) element denotes the kinematic cost of assigning track i to detection j. |
Assignments | Assignments from the assignment function, returned as an integer-valued L-by-2 matrix, where L is the number of assignments. The first column of the matrix contains the track IDs and the second column contains the indices of assigned detections. The detection indices are the array-indices of the detections that you used to update the tracker. |
UnassignedTracks | IDs of unassigned tracks returned from the tracker |
UnassignedDetections | Indices of unassigned detections in the
|
InitiatedTrackIDs | IDs of tracks initiated during the step |
DeletedTrackIDs | IDs of tracks deleted during the step |
TrackIDsAtStepEnd | Track IDs when the step ended |
MaxNumDetectionsPerCluster | The maximum number of detections in all the clusters generated during the
step. The structure has this field only when you set both the
AssignmentClustering and
EnableMemoryManagement properties to
'on' . |
MaxNumTracksPerCluster | The maximum number of tracks in all the clusters generated during the
step. The structure has this field only when you set both the
AssignmentClustering and
EnableMemoryManagement properties to
'on' . |
OOSMHandling | Analysis information for out-of-sequence measurements handling,
returned as a structure. The structure has this field only when the
|
ClassCostMatrix | Cost matrix for classification assignment, in which the
(i, j) elements denotes the
classification cost of assigning track i to detection
j. The structure only has this field when the
|
The OOSMHandling
structure contains these fields:
Field | Description |
---|---|
DiscardedDetections | Indices of discarded out-of-sequence detections. An OOSM is discarded
if it is not covered by the saved state history specified by the
MaxNumOOSMSteps property. |
CostMatrix | Cost of assignment matrix for the out-of-sequence measurements |
Assignments | Assignments between the out-of-sequence detections and the maintained tracks |
UnassignedDetections | Indices of unassigned out-of-sequence detections. The tracker creates new tracks for unassigned out-of-sequence detections. |
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)
Specific to trackerGNN
getTrackFilterProperties | Obtain track filter properties |
setTrackFilterProperties | Set track filter properties |
predictTracksToTime | Predict track state |
initializeTrack | Initialize new track |
confirmTrack | Confirm tentative track |
deleteTrack | Delete existing track |
generateCode | Generate code for tracker object and object functions |
exportToSimulink | Export tracker or track fuser to Simulink model |
Examples
Track Two Objects Using trackerGNN
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
Detection Class Fusion Using trackerGNN
Create two objectDetection
objects at time = 0 and = 1, respectively. The ObjectClassID
of the two detections is 1
. Specify the confusion matrix for each detection.
detection0 = objectDetection(0,[0 0 0],... ObjectClassID=1,... ObjectClassParameters=struct("ConfusionMatrix",[0.6 0.2 0.2; 0.2 0.6 0.2; 0.2 0.2 0.6])); detection1 = objectDetection(1,[0 0 0],... ObjectClassID=1,... ObjectClassParameters=struct("ConfusionMatrix",[0.5 0.3 0.2; 0.3 0.5 0.2; 0.2 0.2 0.6]));
Create a trackerGNN
object. Specify the class fusion method as "Bayes"
and specify the initial probability of each class as 1/3
.
tracker = trackerGNN(ClassFusionMethod="Bayes",InitialClassProbabilities=[1/3 1/3 1/3])
tracker = trackerGNN with properties: TrackerIndex: 0 FilterInitializationFcn: 'initcvekf' MaxNumTracks: 100 MaxNumDetections: Inf MaxNumSensors: 20 Assignment: 'MatchPairs' AssignmentThreshold: [30 Inf] AssignmentClustering: 'off' OOSMHandling: 'Terminate' TrackLogic: 'History' ConfirmationThreshold: [2 3] DeletionThreshold: [5 5] HasCostMatrixInput: false HasDetectableTrackIDsInput: false StateParameters: [1x1 struct] ClassFusionMethod: 'Bayes' InitialClassProbabilities: [0.3333 0.3333 0.3333] ClassFusionWeight: 0.7000 NumTracks: 0 NumConfirmedTracks: 0 EnableMemoryManagement: false
Update the track with the first and second detections sequentially.
tracker(detection0,0); [tracks,~,~,info] = tracker(detection1,1);
Show the maintained tracks and analysis information.
disp(tracks)
objectTrack with properties: TrackID: 1 BranchID: 0 SourceIndex: 0 UpdateTime: 1 Age: 2 State: [6x1 double] StateCovariance: [6x6 double] StateParameters: [1x1 struct] ObjectClassID: 1 ObjectClassProbabilities: [0.7500 0.1500 0.1000] TrackLogic: 'History' TrackLogicState: [1 1 0 0 0] IsConfirmed: 1 IsCoasted: 0 IsSelfReported: 1 ObjectAttributes: [1x1 struct]
disp(info)
OOSMDetectionIndices: [1x0 uint32] TrackIDsAtStepBeginning: 1 CostMatrix: 13.8823 Assignments: [1 1] UnassignedTracks: [1x0 uint32] UnassignedDetections: [0x1 uint32] InitiatedTrackIDs: [1x0 uint32] DeletedTrackIDs: [1x0 uint32] TrackIDsAtStepEnd: 1 ClassCostMatrix: -0.1823
Algorithms
Tracker Logic Flow
When a GNN tracker processes detections, track creation and management follow these steps.
The tracker divides detections by originating sensor.
For each sensor:
The tracker calculates the distances from detections to existing tracks and forms a cost matrix. The cost matrix accounts for the class fusion cost if enabled.
Based on the costs, the tracker performs global nearest neighbor assignment using the algorithm specified in the
Assignment
property.The assignment algorithm divides the detections and tracks into three groups:
Assigned one-to-one detection and track pairs
Unassigned detections
Unassigned tracks
Unassigned detections initialize new tracks. Using the unassigned detection, the tracker initializes a new track filter specified by the
FilterInitializationFcn
property. The track logic for the new track is initialized as well.The tracker checks if any of the unassigned detections from other sensors can be assigned to the new track. If so, the tracker updates the new track with the assigned detections from the other sensors. As a result, these detections no longer initialize new tracks.
The pairs of assigned tracks and detections are used to update each track. The track filter is updated using the
correct
method provided by the specified tracking filter. Also, the track logic is updated with a 'hit'. The tracker checks if the track meets the criteria for confirmation. If so, the tracker confirms the track and sets theIsCoasted
property tofalse
.Unassigned tracks are updated with a ‘miss’ and their
IsCoasted
flag is set totrue
. The tracker checks if the track meets the criteria for deletion. If so, the tracker removes the track from the maintained track list.All tracks are predicted to the latest time value (either the time input if provided, or the latest mean cluster time stamp).
Detection Class Fusion
Single Sensor Class Probability Update
First, consider the class information association between one detection and one track. Assume the confusion matrix of the detection is
where cij denotes the likelihood that the classifier outputs the classification as j if the truth class of the target is i. Here, i, j = 1,…, N, and N is the total number of possible classes.
At time k-1, the probability distribution of a track is given as
where μi is the probability that the classification of the track is i.
If the tracker associates the detection to the track at time k, then the updated value of μi using Bayes' theorem is
Write this equation in a vector form for all possible classifications as
In the above equation, cj is the j-th column of the confusion matrix and ⊗ represents element-wise multiplication. This equation represents the updated class probability of a track if the track is associated with the detection of classification j.
Data Association for Classified Detections
In each update, the tracker considers the possible associations between all the tracks and detections and calculates their association likelihoods Λ(m,t), where m is the index of detections and t is the index of tracks. See [2] and [3] for the details of the likelihood calculation. The tracker then obtains the class fusion cost matrix Cc in the form of negative log-likelihood as:
The overall assignment cost matrix is the weighted sum of the kinematic cost matrix and the class fusion cost matrix.
where,
α — Weight factor of the class fusion cost
Ck — Kinematic assignment cost obtained from the kinematic states of tracks and detections
Cc — Class fusion assignment cost
Multi-Sensor Class Fusion
In each update, the tracker can assign at most one detection from a sensor to one track and obtain class probabilities of the track based on the sensor. If there are multiple sensors, the class fusion algorithm first obtains the local track class probabilities based on each sensor as μs(k), where s = 1,…, S, and S is the total number of sensors that report detections with classification information. The tracker then uses the Bayesian Probabilistic Class Fusion equation to derive the global class probabilities of the track at time step k as:
References
[1] Blackman, S., and R. Popoli. Design and Analysis of Modern Tracking Systems. Artech House Radar Library, Boston, 1999.
[2] Bar-Shalom, Y., et al. “Tracking with Classification-Aided Multiframe Data Association.” IEEE Transactions on Aerospace and Electronic Systems, vol. 41, no. 3, July 2005, pp. 868–78.
[3] Kuncheva, Ludmila I., et al. “Decision Templates for Multiple Classifier Fusion: An Experimental Comparison.” Pattern Recognition, vol. 34, no. 2, Feb. 2001, pp. 299–314.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
See System Objects in MATLAB Code Generation (MATLAB Coder).
All the detections used with a multi-object tracker must have properties with the same sizes and types.
If you use the
ObjectAttributes
field within anobjectDetection
object, you must specify this field as a cell containing a structure. The structure for all detections must have the same fields, and the values in these fields must always have the same size and type. The form of the structure cannot change during simulation.If
ObjectAttributes
are contained in the detection, theSensorIndex
value of the detection cannot be greater than 10.The first update to the multi-object tracker must contain at least one detection.
The tracker supports strict single-precision code generation with these restrictions:
You must specify the assignment algorithm as
'Jonker-Volgenant'
.You must specify the filter initialization function to return a
trackingEKF
,trackingUKF
,trackingCKF
, ortrackingIMM
object configured with single-precision.
For details, see Generate Code with Strict Single-Precision and Non-Dynamic Memory Allocation.
The tracker supports non-dynamic memory allocation code generation with these restrictions:
You must specify the assignment algorithm as
'Jonker-Volgenant'
or'MatchPairs'
.You must specify the filter initialization function to return a
trackingEKF
,trackingUKF
,trackingCKF
, ortrackingIMM
object.You must specify the
MaxNumDetections
property as a finite integer.You cannot specify the
ClassFuionMethod
property as"Bayes"
.
For details, see Generate Code with Strict Single-Precision and Non-Dynamic Memory Allocation.
After enabling non-dynamic memory allocation code generation, consider using these properties to set bounds on the local variables in the tracker:
AssignmentClustering
EnableMemoryManagement
MaxNumDetectionsPerSensor
MaxNumDetectionsPerCluster
MaxNumTracksPerCluster
ClusterViolationHandling
Version History
Introduced in R2018bR2024a: Tune additional properties
You can tune the following properties:
AssignmentThreshold
ConfirmationThreshold
DeletionThreshold
DetectionProbability
FalseAlarmRate
Volume
Beta
InitialClassProbabilities
R2024a: Generate code automatically
You can generate C/C++ code automatically by using the generateCode
object function.
R2022b: Fuse detection classification information
Using the trackerGNN
System object, you can fuse detection
classification information by specifying the ClassFusionMethod
property
of the object as "Bayes"
. With this specification, the tracker uses the
detection classification information to assign tracks based on the Bayesian Product Class
Fusion algorithm.
Additionally, you can use these two properties to adjust the class fusion algorithm:
InitialClassProbabilities
— A priori class probability of new tracks.ClassFusionWeight
— The weight of class fusion cost in the overall assignment cost.
See Also
Blocks
Functions
assignauction
|assignjv
|assignkbest
|assignkbestsd
|assignmunkres
|assignsd
|assignTOMHT
|getTrackPositions
|getTrackVelocities
|fusecovint
|fusecovunion
|fusexcov
|clusterTrackBranches
|compatibleTrackBranches
|pruneTrackBranches
|triangulateLOS
Objects
MATLAB 명령
다음 MATLAB 명령에 해당하는 링크를 클릭했습니다.
명령을 실행하려면 MATLAB 명령 창에 입력하십시오. 웹 브라우저는 MATLAB 명령을 지원하지 않습니다.
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)