laneBoundaryTracker

Track lane boundaries

Since R2023a

Description

The laneBoundaryTracker System object™ tracks lane boundary detections. It can track multiple lane boundary detections in the form of parabolicLaneBoundary, cubicLaneBoundary, and clothoidLaneBoundary objects.

A lane boundary tracker confirms a track when the laneBoundaryTracker System object has enough evidence to determine that the track is an actual lane and its status is set to confirmed. For more information, see Confirmation Threshold property.

You can initialize and configure the tracker with an external Sensor Fusion and Tracking Toolbox™ tracker. Additionally, you can customize the preprocessing and postprocessing functions by using the PreProcessingFcn and PostProcessingFcn properties, respectively.

To use laneBoundaryTracker:

1. Create the laneBoundaryTracker 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?

Note

This object requires the Scenario Builder for Automated Driving Toolbox™ support package and Sensor Fusion and Tracking Toolbox. You can install Scenario Builder for Automated Driving Toolbox from the Add-On Explorer. For more information about installing add-ons, see Get and Manage Add-Ons.

Creation

Syntax

tracker = laneBoundaryTracker

tracker = laneBoundaryTracker(customTracker)

tracker = laneBoundaryTracker(Name=Value)

Description

tracker = laneBoundaryTracker creates a laneBoundaryTracker System object, tracker, with default property values.

tracker = laneBoundaryTracker(customTracker) creates a laneBoundaryTracker System object, tracker, initialized with an external Sensor Fusion and Tracking Toolbox tracker, customTracker.

tracker = laneBoundaryTracker(Name=Value) sets properties for the laneBoundaryTracker object using one or more name-value arguments. For example, AssignmentThreshold=2 creates a laneBoundaryTracker object with an AssignmentThreshold value of 2.

Input Arguments

customTracker — External custom tracker

multiObjectTracker object | trackerGNN object | trackerJPDA object | trackerTOMHT object

External custom tracker, specified as a multiObjectTracker, trackerGNN (Sensor Fusion and Tracking Toolbox), trackerJPDA (Sensor Fusion and Tracking Toolbox), or trackerTOMHT (Sensor Fusion and Tracking Toolbox) object. The external tracker specified when you construct the laneBoundaryTracker object must be compatible with the input lane boundary detection objects detections.

For example,

customTracker = trackerGNN(...
                        FilterInitializationFcn=@initLaneTrackingFilter, ...
                        AssignmentThreshold=[8 50], ...
                        ConfirmationThreshold=[6 8], ...
                        DeletionThreshold=[8 10]);
tracker = laneBoundaryTracker(customTracker)

initializes the laneBoundaryTracker object with the external Sensor Fusion and Tracking Toolbox tracker trackerGNN.

When using the initialized laneBoundaryTracker object, if you specify the UseSmoother name-value argument as true, then the external custom tracker customTracker must be a trackerJPDA (Sensor Fusion and Tracking Toolbox) System object with its TrackLogic property set to "Integrated". This configuration enables a joint integrated data association (JIPDA) smoother for smoothing lane boundaries offline.

Note

If you specify an external tracker, the laneBoundaryTracker object does not use the AssignmentThreshold, ConfirmationThreshold, and DeletionThreshold properties.

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.

LaneBoundaryModel — Lane boundary model

"Parabolic" (default) | "Cubic" | "Clothoid"

Lane boundary model, specified as "Parabolic", "Cubic", or "Clothoid".

• "Parabolic" — Use when specifying lane detections as parabolicLaneBoundary objects.

• "Cubic" — Use when specifying lane detections as cubicLaneBoundary objects.

• "Clothoid" — Use when specifying lane detections as clothoidLaneBoundary objects.

Example: "Parabolic"

Data Types: char | string

AssignmentThreshold — Detection assignment threshold

20 (default) | real positive scalar

Detection assignment threshold, specified as a real positive scalar. Specify this threshold value to assign lane boundary detections to a track.

Increase the threshold value if the object does not assign detections to tracks that it should be. Decrease this value if the object assigns detections to tracks they must not be assigned to (too far away).

Example: 20

Data Types: single | double

ConfirmationThreshold — Threshold for track confirmation

0.95 (default) | scalar in range (0, 1)

Threshold for track confirmation, specified as a scalar in the range (0, 1). The laneBoundaryTracker System object confirms a track if its probability of existence is higher than the specified threshold value.

Decrease the threshold value if the object fails to confirm tracks. Increase this value if the object confirms detections that it should not as tracks.

Example: 0.95

Data Types: single | double

DeletionThreshold — Threshold for track deletion

0.05 (default) | scalar in range (0, 1)

Threshold for track deletion, specified as a scalar in the range (0, 1). The laneBoundaryTracker System object deletes a track if its probability of existence is lower than the specified threshold value.

Example: 0.05

Data Types: single | double

DetectionProbability — Probability of lane detection

0.9 (default) | scalar in range (0, 1)

Probability of lane detection, specified as a scalar in the range (0, 1).

Example: 0.9

Data Types: single | double

FalseAlarmDensity — Spatial density of false positive lane boundary detections

1e-6 (default) | positive scalar

Spatial density of false positive lane boundary detections, specified as a positive scalar.

Increase this value if the tracker creates false tracks, and decrease this value if the tracker fails to confirm tracks.

Example: 1e-6

Data Types: single | double

InitialExistenceProbability — Initial probability of track existence

0.9 (default) | scalar in range [0, 1]

Initial probability of track existence, specified as a scalar in the range [0, 1].

Example: 0.9

Data Types: single | double

MeasurementNoise — Measurement noise covariance

0.01 (default) | scalar | 3-by-3 matrix | 4-by-4 matrix

Measurement noise covariance, specified as a scalar, 3-by-3 matrix, or 4-by-4 matrix.

• 3-by-3 matrix — Use when you model lane detections as parabolicLaneBoundary objects or clothoidLaneBoundary objects.

• 4-by-4 matrix — Use when you model lane detections as cubicLaneBoundary objects.

Example: 0.01

Data Types: single | double

ProcessNoise — Process noise covariance

1e-5 (default) | scalar | 6-by-6 matrix | 8-by-8 matrix

Process noise covariance, specified as a scalar or 6-by-6 matrix or 8-by-8 matrix.

• 3-by-3 matrix — Use when you model lane detections as parabolicLaneBoundary object or clothoidLaneBoundary object.

• 3-by-3 matrix — Use when you model lane detections as cubicLaneBoundary object.

Example: 1e-5

Data Types: single | double

PreProcessingFcn — Preprocessing function

@laneBoundaryTracker.preProcessParabolicLaneBoundaries (default) | function handle

Preprocessing function, specified as a function handle. The function preprocesses the lane boundary detections. By default, the object sets the preprocessing function based on the LaneBoundaryModel property.

The function must support this syntax:

[detectionsOut,time] = preProcessingFunction(detectionsIn,time,varargin)

where the input arguments specify:

• detectionsIn — Custom input detections to the tracker, specified as a cell array of parabolicLaneBoundary, clothoidLaneBoundary, or cubicLaneBoundary objects.

• time — Time to update, specified as a scalar or row vector. Units are in seconds.

• varargin — Optional inputs passed from the tracker, required for custom preprocessing.

and the output arguments return:

• detectionsOut — Preprocessed object detections, returned as a cell array of objectDetection objects.

• time — Time to update, returned as a scalar or row vector. Units are in seconds.

Example: @myPreProcessFn

PostProcessingFcn — Postprocessing function

@laneBoundaryTracker.postProcessParabolicLaneBoundaries (default) | function handle

Postprocessing function, specified as a function handle. The function postprocesses the lane boundary tracks. By default, the object sets the postprocessing function based on the LaneBoundaryModel property. The function must support this syntax:

trackedBoundaries = postProcessingFunction(confirmedTracks,varargin)

where the input arguments specify:

• confirmedTracks — Confirmed lane boundary tracks, specified as an array of objectTrack objects.

• varargin — Optional inputs passed from the tracker, required for custom postprocessing.

and the trackedBoundaries output argument returns the tracked lane boundaries in the format specified by the LaneBoundaryModel property.

Example: @myPostProcessFn

Usage

Syntax

confirmedTracks = tracker(detections,time)

confirmedTracks = tracker(detections,time,varargin)

confirmedTracks = tracker(___,Name=Value)

Description

confirmedTracks = tracker(detections,time) returns a list of confirmed lane boundary tracks that are updated from a list of detections at the update time. Confirmed tracks are corrected and predicted to the update time, time.

confirmedTracks = tracker(detections,time,varargin) specifies a variable-length argument list as input arguments to the custom preprocessing and postprocessing functions.

confirmedTracks = tracker(___,Name=Value) specifies options using one or more name-value arguments. For example, ShowProgress=true displays a progress bar when using the tracker object.

Note

You can run the tracker in offline mode. For more information on offline mode tracking, see the detections, time and confirmedTracks argument descriptions.

Input Arguments

detections — Lane boundary detections

cell array of lane boundary objects

Lane boundary detections, specified as a cell array of lane boundary objects. Each lane detection must be a parabolicLaneBoundary object, cubicLaneBoundary object, or clothoidLaneBoundary object.

Note

In offline mode, you must specify detections as a cell array of lane boundary detections for each time step.

time — Time to update

scalar | row vector

Time to update, specified as a scalar or row vector. Units are in seconds.

If specified as a scalar, the tracker updates all tracks to this time. time must increase in value with each update to the tracker.

If specified as a row vector of times, the tracker runs in offline mode.

varargin — Variable-length input argument list

comma-separated list

Variable-length input argument list, specified as a comma-separated list. The object passes this input as input arguments to the custom preprocessing and postprocessing functions specified by the PreProcessingFcn and PostProcessingFcn properties, respectively.

For example, if you specify the function syntax as:

confirmedTracks = tracker(detections,time,arg1,arg2)

MATLAB^® calls the preprocessing function as:

[detectionsOut,time] = preProcessingFunction(detectionsIn,time,arg1,arg2)

and the postprocessing function as:

trackedBoundaries = postProcessingFunction(confirmedTracks,arg1,arg2)

.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: confirmedTracks = tracker(detections,time,ShowProgress=true) displays a progress bar when using the tracker object.

ShowProgress — Show progress bar status

false or 0 (default) | true or 1

Show progress bar status, specified as a logical 1 (true) or 0 (false). Specify true to display a progress bar in offline mode. Otherwise, specify this value as false.

UseSmoother — Smooth lane boundary detection status

false or 0 (default) | true or 1

Smooth lane boundary detection status, specified as a logical 1 (true) or 0 (false). Specify true to smooth lane boundary detections in offline mode. Otherwise, specify this value as false.

If you specify the UseSmoother name-value argument as true and you use a default laneBoundaryTracker System object, then the function uses a smootherJIPDA (Sensor Fusion and Tracking Toolbox) object for smoothing lane boundaries offline.

If you specify the UseSmoother name-value argument as true and you use an external custom laneBoundaryTracker System object, then you must specify the external custom tracker customTracker as a trackerJPDA (Sensor Fusion and Tracking Toolbox) System object with its TrackLogic property set to "Integrated". This configuration enables a joint integrated data association (JIPDA) smoother for smoothing lane boundaries offline.

Output Arguments

confirmedTracks — Confirmed lane boundary tracks

cell array of structures

Confirmed lane boundary tracks, returned as a cell array of structures. Each cell contains an array of structures, and each structure contains these fields:

• TrackID — Lane boundary track ID, returned as a nonnegative integer.

• UpdateTime — Time at which the lane boundary track was updated by a tracker, returned as a nonnegative real scalar.

• LaneBoundary — Confirmed lane boundary tracks, returned as a parabolicLaneBoundary, cubicLaneBoundary, or clothoidLaneBoundary object.

Note

In offline mode, confirmedTracks is returned as a cell array of structures for each specified time step.

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)

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
isLocked	Determine if System object is in use
clone	Create duplicate System object
reset	Reset internal states of System object

Examples

Track Parabolic Lane Boundaries Using laneBoundaryTracker

Model lane boundary detections using parabolicLaneBoundary objects.

llane=parabolicLaneBoundary([-0.001 0.01 0.5]);
rlane=parabolicLaneBoundary([-0.001 0.01 -0.5]);

Specify the size of the time steps.

dt=0.1;

Initialize a laneBoundaryTracker for tracking parabolicLaneBoundary objects.

tracker=laneBoundaryTracker(LaneBoundaryModel="Parabolic");

Update the tracker with the lane detections.

for i=1:2
    laneTracks=tracker({llane,rlane},i*dt)
end

laneTracks =

  0x1 empty cell array

laneTracks=2×1 cell array
    {1x1 struct}
    {1x1 struct}

Visualize the tracked lane boundaries.

bep=birdsEyePlot(XLimits=[0 30],YLimits=[-5 5]);
lbPlotter=laneBoundaryPlotter(bep,DisplayName="Laneboundaries");
plotLaneBoundary(lbPlotter,[laneTracks{1}.LaneBoundary laneTracks{2}.LaneBoundary])

Track Lane Boundaries in Offline Mode Using laneBoundaryTracker

Specify the number of steps across which to track lane boundaries in offline mode.

numFrames = 10;

Initialize a cell array and numeric array for storing lane detections and time for offline processing, respectively.

laneDets = cell(1,numFrames);
time = zeros(1,numFrames);

Define the sample time.

dt = 0.1;

Create a sequence of lane boundary detections using parabolicLaneBoundary objects. To use these detections with the laneBoundaryTracker object for offline processing, enclose the detections for each time step in a single cell of the cell array.

for i = 1:numFrames
    a = -0.0015 - 0.0005*i;
    b = 0.01;
    c = 0.5;
    llane = parabolicLaneBoundary([a b c]);
    rlane = parabolicLaneBoundary([a b -c]);
    laneDets{i}= [llane, rlane];
    time(i) = dt*i;
end

Initialize a lane boundary tracker.

tracker = laneBoundaryTracker(AssignmentThreshold=2,MeasurementNoise=5e-3);

Track and smooth the lane boundaries in offline mode.

laneTracks = tracker(laneDets,time,UseSmoother=true);

Create a bird's-eye plot and lane boundary plotter.

bep = birdsEyePlot(XLimits=[0 30],YLimits=[-5 5]);
lbDetPlotter = laneBoundaryPlotter(bep,DisplayName="Lane boundary detections");
lbTrackPlotter = laneBoundaryPlotter(bep,DisplayName="Lane boundary tracks",LineStyle="--",Color="b");
tIds = {text(0,0,''),text(0,0,'')};

Plot the tracked lane boundaries and lane tracks.

for i = 1:numFrames
    plotLaneBoundary(lbDetPlotter,laneDets{i})
    if ~isempty(laneTracks{i})
        for j = 1:numel(laneTracks{i})
            boundaries(j) = laneTracks{i}{j}.LaneBoundary; 
            tIds{j}.String = laneTracks{i}{j}.TrackID;
            tIds{j}.Position = [25 computeBoundaryModel(laneTracks{i}{j}.LaneBoundary,25)];
        end
        plotLaneBoundary(lbTrackPlotter,boundaries)
    end
    drawnow
    pause(0.2)
end

Algorithms

The laneBoundaryTracker System object uses a combination of the joint probabilistic data association tracker and extended Kalman filter. For more information on the joint probabilistic data association tracker, see the Algorithms (Sensor Fusion and Tracking Toolbox) section of the trackerJPDA System object. For more information on the extended Kalman filter, see the Algorithms (Sensor Fusion and Tracking Toolbox) section of the trackingEKF object.

Version History

Introduced in R2023a

R2023b_plus: Additional name-value argument UseSmoother

You can now specify the additional name-value argument UseSmoother, when using the initialized laneBoundaryTracker object, to smooth lane boundary detections.