updateLaneSpec

Update lane specifications using sensor detections

Since R2022b

Syntax

rd = updateLaneSpec(laneDetections,roadProperties,refLaneSpec,egoTrajectory,initialEgoLaneIdx)

rd = updateLaneSpec(___,Name=Value)

Description

rd = updateLaneSpec(laneDetections,roadProperties,refLaneSpec,egoTrajectory,initialEgoLaneIdx) updates the reference lane specifications refLaneSpec using the recorded lane detection data laneDetections. For information on how to generate lane detections from camera data, see Extract Lane Information from Recorded Camera Data for Scene Generation example.

The function localizes the ego vehicle using the specified ego trajectory, road properties, and initial ego lane index, and then maps the lane boundary detections to update the lane markings and lane widths of the reference lane specifications. The function returns updated road properties, rd, that have the same data type as the input road properties roadProperties.

rd = updateLaneSpec(___,Name=Value) specifies options using one or more name-value arguments. For example, UpdateRefLaneMarking=false specifies not to update reference lane marking information.

Note

This function 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.

Examples

Update Lane Specifications Using Recorded Lane Detections

Load recorded sensor data that contains lane detections, ego trajectory, and road data, stored as a structure, into the workspace. For more information on generating lane detections from recorded camera data, see Extract Lane Information from Recorded Camera Data for Scene Generation.

data = load("recordedLaneDetections.mat");  

Extract the road data. The road data table contains these five road parameters: RoadID, RoadCenters, RoadWidth, LeftBoundary, and RightBoundary. Note that, because this road data has been generated from a standard definition (SD) map, it lacks lane information.

roadProperties = data.roadData

roadProperties=1×5 table
    RoadID     RoadCenters     RoadWidth     LeftBoundary     RightBoundary 
    ______    _____________    _________    ______________    ______________

      73      {23x3 double}        6        {406x3 double}    {406x3 double}

Extract the ego trajectory.

egoTrajectory = data.egoTrajectory;

Extract the lane detections. The lane detections have been preprocessed to organize them into a format that the updateLaneSpec function supports. For more information on organizing recorded lane detections, see Preprocess Lane Detections for Scenario Generation.

laneDetections = data.laneDets;

Create reference lane specifications for three lanes, with solid lane markings for each lane boundary. Note that each lane has a default width of 3.6 meters.

lm = laneMarking("Solid");
ls = lanespec(3,Marking=lm);

Map the reference lane specifications to the extracted road ID using a dictionary object.

refLanespec = dictionary(roadProperties.RoadID,{ls});

Update the lane specifications using the recorded lane detections. The updateLaneSpec function returns a table that contains the updated road properties and an additional Lanes column, which contains the lane specifications.

rd = updateLaneSpec(laneDetections,roadProperties, ...
     refLanespec,egoTrajectory,2)

rd=1×6 table
    RoadID     RoadCenters      RoadWidth      LeftBoundary     RightBoundary         Lanes     
    ______    _____________    ___________    ______________    ______________    ______________

      73      {23x3 double}    {[11.3091]}    {406x3 double}    {406x3 double}    {1x1 lanespec}

Display the updated lane widths. Notice that the function has updated the widths of the second and third lanes. By default, the function updates only those lanes that overlap with the ego trajectory. If you want to update all the lanes of a road, use the ReplicateUpdatedLaneWidth argument when specifying the updateLaneSpec function.

rd.Lanes{1,1}.Width

ans = 1×3

    3.6000    3.5824    3.9767

Display the updated lane markings for the third and fourth lane boundaries. Notice that the function has updated these lane markings from solid lines to dashed lines.

[rd.Lanes{1,1}.Marking(3).Type rd.Lanes{1,1}.Marking(4).Type]

ans = 
  1x2 LaneBoundaryType enumeration array

    Dashed    Dashed

Input Arguments

laneDetections — Recorded lane detection data

laneData object | M-by-N table

Recorded lane detection data, specified as a laneData object or an M-by-N table. M is the number of lane-detection samples and N–1 is the maximum number of detected lane boundaries across all samples. This table shows an example of the laneDetections data organized using an M-by-N table. For information about how to organize lane detection data using a laneData object, see Preprocess Lane Detections for Scenario Generation.

Time (s)	LaneBoundary1	LaneBoundary2	LaneBoundary3
0	1x1 parabolicLaneBoundary	1x1 parabolicLaneBoundary	1x1 parabolicLaneBoundary
0.05	1x1 parabolicLaneBoundary	1x1 parabolicLaneBoundary	[]
0.1	1x1 parabolicLaneBoundary	1x1 parabolicLaneBoundary	1x1 parabolicLaneBoundary

• The first column of the table specifies the recorded time stamp, in seconds, for each detection. Other columns contain data for the detected lane boundaries specified as parabolicLaneBoundary objects, cubicLaneBoundary objects, or clothoidLaneBoundary objects. You must specify all lane boundaries using the same type of object.

• Empty cells represent missing lane boundary detections.

• The table must specify at least three columns: the first column for timestamps, and the remaining columns for two lane boundaries. The table must not have any empty cell in the first three columns.

• The detected lane boundaries must be in left-to-right order with respect to the travel direction of the ego vehicle.

roadProperties — Road properties

P-by-Q table

Road properties, specified as a P-by-Q table. P is the number of roads and Q is the number of road properties. Q must be greater than 4. You can specify any number of road properties in any order, but the table must contain these five properties, which the function requires for updating lane specifications:

• RoadID — Identifier of road, specified as a positive integer.

• RoadCenters — Road centers used to define road, specified as a real-valued K-by-3 matrix, where K is the number of road centers. Each matrix row represents the (x, y, z) coordinates of a road center. Units are in meters.

• RoadWidth — Width of road, specified as a real positive scalar or vector. Units are in meters.

• LeftBoundary — Left boundary of road, specified as a real-valued L-by-3 matrix, where L is the number of left boundary points. Each matrix row represents the (x, y, z) coordinates of a left boundary point. Units are in meters.

• RightBoundary — Right boundary of road, specified as a real-valued R-by-3 matrix, where R is the number of right boundary points. Each matrix row represents the (x, y, z) coordinates of a right boundary point. Units are in meters.

Tip

For the automatic scene generation workflow, use the actorRoadProperties output of the selectActorRoads function to specify road properties. For more information, see Generate High Definition Scene from Lane Detections and OpenStreetMap.

Data Types: table

refLaneSpec — Reference lane specifications

dictionary object | lanespec object | compositeLaneSpec object | P-by-1 cell array of lanespec objects | P-by-1 cell array of compositeLaneSpec objects

Reference lane specifications, specified as a dictionary object, or a scalar or P-by-1 cell array of lanespec objects or compositeLaneSpec objects. P is the number of roads specified using the roadProperties input.

When you specify the reference lane specifications as a dictionary object, the data types of keys and values of a dictionary must be double and cell, respectively. The keys must correspond to road IDs in the roadProperties input and the values must contain a lanespec or a compositeLaneSpec object for the corresponding road IDs. The number of keys and values of a dictionary must match the number of roads specified using the roadProperties input.

egoTrajectory — Trajectory information of ego vehicle

waypointTrajectory object

Trajectory information of the ego vehicle, specified as a waypointTrajectory (Sensor Fusion and Tracking Toolbox) object.

initialEgoLaneIdx — Starting lane index of ego vehicle

positive integer

Starting lane index of the ego vehicle, specified as a positive integer. You must number the lanes in left-to-right order along the travel direction of the ego vehicle.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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: updateLaneSpec(laneDetections,roadProperties,refLaneSpec,egoTrajectory,initialEgoLaneIdx,UpdateRefLaneMarking=false) specifies not to update reference lane marking information.

UpdateRefLaneMarking — Reference lane markings update flag

true or 1 (default) | false or 0

Reference lane markings update flag, specified as a logical 1 (true) or 0 (false).

• true or 1 — Update the input lane markings information using the specified lane detection information.

• false or 0 — Do not update the input lane markings. The function updates only lane widths using the specified lane detection information.

Data Types: logical

ReplicateUpdatedLaneWidth — Non-detected lane width update flag

false or 0 (default) | true or 1

Non-detected lane width update flag, specified as a logical 1 (true) or 0 (false).

• false or 0 — Do not update the widths of non-detected lanes. The function updates the lane widths of only detected lanes.

• true or 1 — Update the widths of all lanes whether they are detected or not. For this option, the function computes the mean of the widths of the detected lanes, and then replaces the widths of all lanes with the computed mean value.

Data Types: logical

Output Arguments

rd — Updated road properties

table

Updated road properties, returned as a table. If the roadProperties input contains a Lanes column, then the function returns the updated road properties as a table with the same size as the roadProperties input. Otherwise, the function returns the updated road properties table by appending a Lanes column to the roadProperties input table. The Lanes column describes lane specifications for each road in the table.

Data Types: table

Version History

Introduced in R2022b

R2023a: Specify recorded lane detections using laneData object

The updateLaneSpec function supports the laneData object to specify the laneDetections input. The object provides efficient data structure to store lane detections with timestamps. You can add or remove data from the object and find lane information nearest to the specified timestamp.

R2023a: Specify reference lane specifications using dictionary object

The updateLaneSpec function supports the dictionary object to specify the refLaneSpec input. The object makes it easier to define mapping between lane specifications and extracted road IDs.