Main Content

updateTracks

Update multi-object tracker with new detections

collapse all in page

Syntax

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

Description

confirmedTracks = updateTracks(tracker,detections,time) creates, updates, and deletes tracks in the multiObjectTracker System object™, tracker. Updates are based on the specified list of detections, and all tracks are updated to the specified time. Each element in the returned confirmedTracks corresponds to a single track.

[confirmedTracks,tentativeTracks] = updateTracks(tracker,detections,time) also returns tentativeTracks containing details about the tentative tracks.

[confirmedTracks,tentativeTracks,allTracks] = updateTracks(tracker,detections,time) also returns allTracks containing details about all confirmed and tentative tracks. The tracks are returned in the order by which the tracker internally maintains them. You can use this output to help you calculate the cost matrix, an optional input argument.

example

[___] = updateTracks(tracker,detections,time,costMatrix) specifies a cost matrix, returning any of the outputs from preceding syntaxes.

To specify a cost matrix, set the HasCostMatrixInput property of tracker to true.

[___] = updateTracks(___,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.

Examples

collapse all

Open Live Script

Create a multiObjectTracker System object™ using the default filter initialization function for a 2-D constant-velocity model. For this motion model, the state vector is [x;vx;y;vy].

tracker = multiObjectTracker('ConfirmationThreshold',[4 5], ...
    'DeletionThreshold',10);

Create a detection by specifying an objectDetection object. To use this detection with the multi-object tracker, enclose the detection in a cell array.

dettime = 1.0;
det = { ...
    objectDetection(dettime,[10; -1], ...
    'SensorIndex',1, ...
    'ObjectAttributes',{'ExampleObject',1}) ...
    };

Update the multi-object tracker with this detection by using the updateTracks function. The time at which you update the multi-object tracker must be greater than or equal to the time at which the object was detected.

updatetime = 1.25;
[confirmedTracks,tentativeTracks,allTracks] = updateTracks(tracker,det,updatetime);

Create another detection of the same object and update the multi-object tracker, this time by calling the tracker itself instead of using updateTracks. The tracker maintains only one track.

dettime = 1.5;
det = { ...
    objectDetection(dettime,[10.1; -1.1], ...
    'SensorIndex',1, ...
    'ObjectAttributes',{'ExampleObject',1}) ...
    };
updatetime = 1.75;
[confirmedTracks,tentativeTracks,allTracks] = tracker(det,updatetime);

Determine whether the track has been verified by checking the number of confirmed tracks.

numConfirmed = tracker.NumConfirmedTracks
numConfirmed = 
0

Examine the position and velocity of the tracked object. Because the track has not been confirmed, get the position and velocity from the tentativeTracks structure.

positionSelector = [1 0 0 0; 0 0 1 0];
velocitySelector = [0 1 0 0; 0 0 0 1];
position = getTrackPositions(tentativeTracks,positionSelector)
position = 1×2

   10.1426   -1.1426


velocity = getTrackVelocities(tentativeTracks,velocitySelector)
velocity = 1×2

    0.1852   -0.1852

Input Arguments

collapse all

Multi-object tracker, specified as a multiObjectTracker System object.

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 time of update, time, and greater than the previous time value used to update the multi-object tracker.

Time of update, specified as a real 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 multi-object tracker.

Data Types: double

Cost matrix, specified as a real-valued NT-by-ND matrix, where NT is the number of existing tracks, and ND is the number of current detections. The rows of the cost matrix correspond to the existing tracks. The columns correspond to the detections. Tracks are ordered as they appear in the list of tracks in the allTracks output argument of the previous update to the multi-object tracker.

In the first update to the multi-object tracker, or when the tracker has no previous tracks, assign the cost matrix a size of [0, ND]. The cost must be calculated so that lower costs indicate a higher likelihood that the tracker assigns a detection to a track. To prevent certain detections from being assigned to certain tracks, use Inf.

Dependencies

To enable specification of the cost matrix when updating tracks, set the HasCostMatrixInput property of the tracker to true

Data Types: double

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

collapse 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

Algorithms

When you pass detections into updateTracks, the function:

  • Attempts to assign the input detections to existing tracks, based on the AssignmentThreshold property of the multi-object tracker.

  • Creates new tracks from unassigned detections.

  • Updates already assigned tracks and possibly confirms them, based on the ConfirmationThreshold property of the tracker.

  • Deletes tracks that have no assigned detections, based on the DeletionThreshold property of the tracker.

Version History

Introduced in R2017a

See Also

Objects

Functions