Main Content

updateTracks

Update multi-object tracker with new detections

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.

example

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

[___] = 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

Generate detections using a forward-facing automotive radar mounted on an ego vehicle. Assume that there are three targets:

  • Vehicle 1 is in the center lane, directly in front of the ego vehicle, and driving at the same speed.

  • Vehicle 2 is in the left lane and driving faster than the ego vehicle by 12 kilometers per hour.

  • Vehicle 3 is in the right lane and driving slower than the ego vehicle by 5 kilometers per hour.

All positions, velocities, and measurements are relative to the ego vehicle. Run the simulation for ten steps.

dt = 0.1;
pos1 = [150 0 0];
pos2 = [160 10 0];
pos3 = [130 -10 0];
vel1 = [0 0 0];
vel2 = [12*1000/3600 0 0];
vel3 = [-5*1000/3600 0 0];
car1 = struct('ActorID',1,'Position',pos1,'Velocity',vel1);
car2 = struct('ActorID',2,'Position',pos2,'Velocity',vel2);
car3 = struct('ActorID',3,'Position',pos3,'Velocity',vel3);

Create an automotive radar sensor that is offset from the ego vehicle. By default, the sensor location is at (3.4,0) meters from the vehicle center and 0.2 meters above the ground plane. Turn off the range rate computation so that the radar sensor measures position only.

radar = radarDetectionGenerator('DetectionCoordinates','Sensor Cartesian', ...
    'MaxRange',200,'RangeResolution',10,'AzimuthResolution',10, ...
    'FieldOfView',[40 15],'UpdateInterval',dt,'HasRangeRate',false);
tracker = multiObjectTracker('FilterInitializationFcn',@initcvkf, ...
    'ConfirmationThreshold',[3 4],'DeletionThreshold',[6 6]);

Generate detections with the radar from the non-ego vehicles. The output detections form a cell array and can be passed directly in to the multiObjectTracker.

simTime = 0;
nsteps = 10;
for k = 1:nsteps
    dets = radar([car1 car2 car3],simTime);
    [confirmedTracks,tentativeTracks,allTracks] = updateTracks(tracker,dets,simTime);

Move the cars one time step and update the multi-object tracker.

    simTime = simTime + dt;
    car1.Position = car1.Position + dt*car1.Velocity;
    car2.Position = car2.Position + dt*car2.Velocity;
    car3.Position = car3.Position + dt*car3.Velocity;
end

Use birdsEyePlot to create an overhead view of the detections. Plot the sensor coverage area. Extract the X and Y positions of the targets by converting the Measurement fields of the cell array into a MATLAB array. Display the detections on the bird's-eye plot.

BEplot = birdsEyePlot('XLim',[0 220],'YLim',[-75 75]);
caPlotter = coverageAreaPlotter(BEplot,'DisplayName','Radar coverage area');
plotCoverageArea(caPlotter,radar.SensorLocation,radar.MaxRange, ...
    radar.Yaw,radar.FieldOfView(1))
detPlotter = detectionPlotter(BEplot,'DisplayName','Radar detections');
detPos = cellfun(@(d)d.Measurement(1:2),dets,'UniformOutput',false);
detPos = cell2mat(detPos')';
if ~isempty(detPos)
    plotDetection(detPlotter,detPos)
end

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 multi-object 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 multi-object 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 multi-object 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 multi-object 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.

Introduced in R2017a