Main Content

trackerTOMHT

Multi-hypothesis, multi-sensor, multi-object tracker

Since R2018b

expand all in page

Description

The trackerTOMHT System object™ is a multi-hypothesis tracker capable of processing detections of many targets from multiple sensors. 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. The tracker assigns detections based on a track-oriented, multi-hypothesis approach. Each detection is assigned to at least one track. If the detection cannot be assigned to any track, the tracker creates a 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 multi-object 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. For an overview of how the tracker functions, see Algorithms.

To track objects using the multi-hypothesis tracker:

  1. Create the trackerTOMHT 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 = trackerTOMHT
tracker = trackerTOMHT(Name,Value)

Description

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

example

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

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

Maximum number of detections that the tracker can take as inputs, specified as a positive integer.

Data Types: single | double

Handle out-of-sequence measurement (OOSM), specified as 'Terminate' or 'Neglect'. Each detection has a timestamp associated with it, td, and the tracker has it own timestamp, tt, which is updated in each call. The tracker considers a measurement as an OOSM if td < tt.

When the property is specified as

  • 'Terminate' — The tracker stops running when it encounters any out-of-sequence measurements.

  • 'Neglect' — The tracker neglects any out-of-sequence measurements and continue to run.

To simulate out-of-sequence detections, use objectDetectionDelay.

Tunable: Yes

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 NameValue
Frame"Rectangular"
Position[10 10 0]
Velocity[2 -2 0]

Tunable: Yes

Data Types: struct

Maximum number of global assignment hypotheses maintained by the tracker at each step, specified as a positive integer. If the number of hypotheses is larger than the property value, the tracker prunes the hypotheses of lower likelihoods and its associated branches until the number of hypotheses reaches the property value. Larger values increase the computational load.

Example: 10

Data Types: single | double

Maximum number of track branches allowed for each track, specified as a positive integer. Larger values increase the computational load.

Data Types: single | double

Maximum number of scans maintained in the branch history, specified as a positive integer. The number of track history scans is typically from 2 through 6. Larger values increase the computational load.

Example: 6

Data Types: single | double

Detection assignment threshold, specified as a positive scalar, an 1-by-3 vector of non-decreasing positive values, [C1,C2,C3], or an1-by-4 vector of non-decreasing positive values, [C1,C2,C3,C4]. If specified as a scalar, the specified value, val, will be expanded to [0.3,0.7,1,Inf]*val. If specified as [C1,C2,C3], it will be expanded as [C1,C2,C3,Inf].

The thresholds control (1) the assignment of a detection to a track, (2) the creation of a new branch from a detection, and (3) the creation of a new branch from an unassigned track. The threshold values must satisfy: C1 <= C2 <= C3<=C4.

  • C1 defines a distance such that if a track has an assigned detection with lower distance than C1, the track is no longer considered unassigned and does not create an unassigned track branch.

  • C2 defines a distance that if a detection has been assigned to a track with lower distance than C2, the detection is no longer considered unassigned and does not create a new track branch.

  • C3 defines the maximum distance for assigning a detection to a track.

  • C4 defines combinations of track and detection for which an accurate normalized cost calculation is performed. 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 C4.

See Algorithms for an explanation of the normalized distance.

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

  • Increasing the values C1 and C2 helps control the number of track branches that are created. However, doing so reduces the number of branches (hypotheses) each track has.

  • Increase the value of C4 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.

Note

If the value of C4 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.

Data Types: single | double

Minimum score required to confirm a track, specified as a positive scalar. Any track with a score higher than this threshold is confirmed.

Example: 12

Data Types: single | double

The maximum score drop before a track is deleted, specified as a scalar. Any track with a score that falls by more than this parameter from the maximum score is deleted. Deletion threshold is affected by the probability of false alarm.

Example: 12

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

Minimum probability required to keep a track, specified as a positive scalar less than one. Any track with lower probability is pruned. Typical values are 0.001 to 0.005.

Example: .003

Data Types: single | double

N-scan pruning method, specified as 'None' or 'Hypothesis'. In N-scan pruning, branches that belong to the same track are pruned (deleted) if, in the N-scans history, they contradict the most likely branch for the same track. The most-likely branch is defined in one of two ways:

  • 'None' – No N-scan pruning is performed.

  • 'Hypothesis' – The chosen branch is in the most likely hypothesis.

Example: 'Hypothesis'

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 branch IDs at each object update, specified as false or true. Set this property to true if you want to provide a list of detectable branch IDs. This list tells the tracker of all branches that the sensors are expected to detect and, optionally, the probability of detection for each branch.

Data Types: logical

Track output method, specified as 'Tracks', 'Hypothesis', or 'Clusters'.

  • 'Tracks' – Output the centroid of each track based on its track branches.

  • 'Hypothesis' – Output branches that are in certain hypotheses. If you choose this option, list the hypotheses to output using the HypothesesToOutput property.

  • 'Clusters' – Output the centroid of each cluster. Similar to 'Tracks' output, but includes all tracks within a cluster.

Data Types: char

Indices of hypotheses to output, specified as an array of positive integers. The indices must all be less than or equal to the maximum number of hypotheses provided by the tracker.

Tunable: Yes

Data Types: single | double

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(___,detectableBranchIDs)
[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(___,detectableBranchIDs) also specifies a list of expected detectable branches, detectableBranchIDs.

To enable this syntax, set the HasDetectableBranchIDsInput 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, useful 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 branches, and M is the number of current detections. The cost matrix rows must be in the same order as the list of branches. The columns must be in the same order as the list of detections. Obtain the correct order of the list of branches using the getBranches object function. Matrix columns correspond to the detections.

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 branch IDs, specified as a real-valued M-by-1 vector or M-by-2 matrix. Detectable branches are branches that the sensors expect to detect. The first column of the matrix contains a list of branch IDs of tracks reported in the branchID field of the track output arguments. The second column contains the detection probability for the branch. Sensors can report detection probability, but if not reported, detection probabilities are obtained from the DetectionProbability property.

Branches whose identifiers are not included in detectableBranchIDs are considered as undetectable. The track deletion logic does not count the lack of detection as a 'miss' for branch deletion purposes.

Dependencies

To enable this input argument, set the HasDetectableBranchIDs 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
OOSMDetectionIndices

Indices of out-of-sequence measurements

BranchIDsAtStepBeginning

Branch IDs when update began.

CostMatrix

Cost of kinematic assignment matrix, in which the (i, j) element denotes the cost of assigning track i to detection j.

Assignments

Assignments returned from assignTOMHT.

UnassignedTracks

IDs of unassigned branches returned from the tracker

UnassignedDetections

Indices of unassigned detections in the detections input.

InitialBranchHistory

Branch history after branching and before pruning.

InitialBranchScores

Branch scores before pruning.

KeptBranchHistory

Branch history after initial pruning.

KeptBranchScores

Branch scores after initial pruning.

Clusters

Logical array mapping branches to clusters. Branches belong in the same cluster if they share detections in their history or belong to the same track, either directly or through other branches. Such branches are incompatible.

TrackIncompatibility

Branch incompatibility matrix. The (i,j) element is true if the i-th and j-th branches have shared detections in their history or belong to the same track.

GlobalHypotheses

Logical matrix mapping branches to global hypotheses. Compatible branches can belong in the same hypotheses.

GlobalHypScoresTotal score of global hypotheses.
PrunedBranches

Logical array of branches that the pruneTrackBranches function determines to be pruned.

GlobalBranchProbabilities

Global probability of each branch existing in the global hypotheses.

BranchesDeletedByPruning

Branches deleted by the tracker.

BranchIDsAtStepEnd

Branch IDs when the update 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
getBranchesLists track branches
predictTrackToTimePredict track state
initializeTrackInitialize new track
deleteTrackDelete existing track
initializeBranchInitialize new track branch
confirmBranchConfirm track branch
deleteBranchDelete existing track branch
exportToSimulinkExport tracker or track fuser to Simulink model
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

Create the trackerTOMHT System object with a constant-velocity Kalman filter initialization function, initcvkf.

tracker = trackerTOMHT('FilterInitializationFcn',@initcvkf, ...
    'ConfirmationThreshold',20, ...
    'DeletionThreshold',-7, ...
    'MaxNumHypotheses',10);

Update the tracker with two detections having nonzero ObjectClassID. The 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 and display 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.0000         0
         0   10.0000


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

     0     0
     0     0

Algorithms

expand all

References

[1] Werthmann, J. R.. "Step-by-Step Description of a Computationally Efficient Version of Multiple Hypothesis Tracking." In International Society for Optics and Photonics, Vol. 1698, pp. 228-301, 1992.

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

Extended Capabilities

Version History

Introduced in R2018b

See Also

Functions

Objects

Blocks