Detailed Description

Lane Planner module to compute which lanes to follow based on HD maps.

Note: SW Release Applicability: These APIs are available in NVIDIA DRIVE Software releases.

The Lane Planner takes a list of gps points as input, and computes a path along HD maps lanes from the first to the last of the gps points, minimizing time by using distance and speed limit, minimizing the number of lane changes, and following the input gps points. The module does a dijkstra search through the lane graph to compute the optimal lane plan. A custom cost function can be provided to run the dijkstra search with a different optimum criterion.

The lane plan will start at the closest lane to the first of the input gps points. The target is any lane that is on the road segment closest to the last of the input gps points.

Data Structures
struct	dwLanePlan
	A lane plan consist of a list of segments that describe how to get from a source lane to a target lane, following a squence of connected lanes, including information about lane changes, lane splits and lane merges. More...

struct	dwLanePlanActions
	Structure that packages lane change, lane split, and lane merge info together. More...

struct	dwLanePlanIndex
	Index defining a point in the lane plan. More...

struct	dwLanePlanLane
	A lane plan lane is a sequence of dwMapsLane's, with additional information per dwMapsLane about moving direction and estimated time of arrival. More...

struct	dwLanePlanLaneChange
	Lane change state on the lane plan. More...

struct	dwLanePlanSegment
	A lane plan segment is a segment along the lane plan with a consistent lane change situation. More...

Typedefs
typedef struct dwLanePlanObject const *	dwConstLanePlanHandle_t

typedef struct dwLanePlannerObject const *	dwConstLanePlannerHandle_t

typedef struct dwLanePlanObject *	dwLanePlanHandle_t

typedef float32_t(*	dwLanePlannerCostFunction_t) (const dwMapsLane lane, bool forward, float32_t length, uint32_t laneChangeCount, dwMapsSide laneChangeSide, const dwMapsGeoPoint gpsPathPoint, uint32_t gpsPathPointCount, bool ignoreHeight, const dwMapsLane neighborLane, void context)
	Cost function that allows to implement a custom cost calculation in the dijkstra algorithm that calculates the optimal lane plan. More...

typedef struct dwLanePlannerObject *	dwLanePlannerHandle_t

Functions
DW_API_PUBLIC dwStatus	dwLanePlan_computeDistance (float32_t distance, const dwLanePlanIndex index1, const dwLanePlanIndex *index2, dwConstLanePlanHandle_t lanePlan)

DW_API_PUBLIC dwStatus	dwLanePlan_containsLane (bool isOnLanePlan, const dwMapsLane lane, dwConstLanePlanHandle_t lanePlan)
	Check whether a given dwMapsLane is part of the lane plan. More...

DW_API_PUBLIC dwStatus	dwLanePlan_decreaseIndex (dwLanePlanIndex *lanePlanIndex, uint32_t decreaseCount, dwConstLanePlanHandle_t lanePlan)
	Helper function to compute the previous lane plan point on a lane plan. More...

DW_API_PUBLIC dwStatus	dwLanePlan_findClosestPoint (dwMapsGeoPoint closestPoint, dwLanePlanIndex lanePlanIndex, const dwMapsGeoPoint *gps, bool ignoreHeight, dwLanePlanHandle_t lanePlan)
	Helper function to find the closest line segment on the lane plan to a given gps location, together with the corresponding closest lane plan point (the closer of the two lane plan points on the line segment that contains the closest geometric point). More...

DW_API_PUBLIC dwStatus	dwLanePlan_get (dwLanePlan *lanePlan, dwConstLanePlanHandle_t lanePlanHandle)
	Retrieve the result of a previous 'dwLanePlanner_run' call. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getComplexity (uint32_t totalLaneChangeCount, uint32_t totalLaneSplitCount, uint32_t *totalLaneMergeCount, dwLanePlanHandle_t lanePlan)
	Returns some numbers that indicate how complex it is to autonomously drive a given lane plan. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getCurrentGeoPoint (dwMapsGeoPoint *pointOnLanePlan, dwConstLanePlanHandle_t lanePlan)
	Get current point on the lane plan in gps coordinates. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getCurrentIndex (dwLanePlanIndex *lanePlanIndex, dwConstLanePlanHandle_t lanePlan)
	Get the index to the current point on the lane plan. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getCurrentPoint (const dwMapsRoadSegment *referenceRoadSegment, dwVector3f pointOnLanePlan, dwConstLanePlanHandle_t lanePlan)
	Get current point on the lane plan in coordinates relative to a reference road segment. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getEstimatedArrivalInfo (float32_t distToDestination, float32_t timeToDestination, dwConstLanePlanHandle_t lanePlanHandle)
	Get estimated time and distance to reach the end of the lane plan from current position. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getLanePlanActions (dwLanePlanIndex laneChangePointIndex, dwLanePlanIndex laneSplitPointIndex, dwLanePlanActions *lanePlanActionInfo, dwLanePlanHandle_t lanePlan)
	Get information about the next lane change and lane split. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getLanePlanActionsNew (dwLanePlanIndex laneChangePointIndex, dwLanePlanIndex laneSplitPointIndex, dwLanePlanIndex laneMergePointIndex, dwLanePlanActions lanePlanActionInfo, dwLanePlanHandle_t lanePlan)
	Get information about the next lane change, lane split, and lane merge. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getLanePlanSplitMergeDetails (dwMapsLaneSplitDetails laneSplit, dwMapsLaneMergeDetails laneMerge, dwLanePlanHandle_t lanePlan)
	Get information about the next lane change, lane split, and lane merge. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getNextLaneChange (dwLanePlanIndex laneChangePointIndex, dwLanePlanLaneChange laneChange, float32_t *distance, dwLanePlanHandle_t lanePlan)
	Get next lane change. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getNextLaneChangeAt (dwLanePlanIndex laneChangePointIndex, dwLanePlanLaneChange laneChange, const dwLanePlanIndex *queryPointIndex, dwConstLanePlanHandle_t lanePlan)
	Get the next lane change happening on the lane plan at or after given lane plan index. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getNextLaneMerge (dwLanePlanIndex laneMergePointIndex, dwMapsLaneMergeDetails laneMerge, float32_t *distance, dwLanePlanHandle_t lanePlan)
	Get next lane merge. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getNextLaneMergeAt (dwLanePlanIndex laneMergePointIndex, dwMapsLaneMergeDetails laneMerge, const dwLanePlanIndex *queryPointIndex, dwLanePlanHandle_t lanePlan)
	Get the next lane merge happening on the lane plan at or after given lane plan index. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getNextLaneSplit (dwLanePlanIndex laneSplitPointIndex, dwMapsLaneSplitDetails laneSplit, float32_t *distance, dwLanePlanHandle_t lanePlan)
	Get next lane split. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getNextLaneSplitAt (dwLanePlanIndex laneSplitPointIndex, dwMapsLaneSplitDetails laneSplit, const dwLanePlanIndex *queryPointIndex, dwLanePlanHandle_t lanePlan)
	Get the next lane split happening on the lane plan at or after given lane plan index. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getPoint (dwMapsGeoPoint pointWGS84, dwVector3f pointLocal, const dwMapsLane *lane, dwTime_t time, const dwLanePlanIndex *index, dwConstLanePlanHandle_t lanePlan)
	Get point data from lane plan at given index. More...

DW_API_PUBLIC dwStatus	dwLanePlan_getTargetLanes (dwMapsLanePtrBuffer lanes, uint32_t laneChangeIndex, float32_t distance, dwLanePlanHandle_t lanePlan)
	Get target lane ptrs e.g. More...

DW_API_PUBLIC dwStatus	dwLanePlan_increaseIndex (dwLanePlanIndex *lanePlanIndex, uint32_t increaseCount, dwConstLanePlanHandle_t lanePlan)
	Helper function to compute the next lane plan point along a lane plan. More...

DW_API_PUBLIC dwStatus	dwLanePlan_initialize (dwLanePlanHandle_t *lanePlan, dwConstLanePlannerHandle_t lanePlanner)
	Creates a lane plan object and returns a handle to it. More...

DW_API_PUBLIC dwStatus	dwLanePlan_initializeLanePlanActions (dwLanePlanActions *lpActions)
	Default initialize a dwLanePlanActions object. More...

DW_API_PUBLIC dwStatus	dwLanePlan_release (dwLanePlanHandle_t lanePlan)
	Release a lane plan object. More...

DW_API_PUBLIC dwStatus	dwLanePlan_updateCurrentPointWithCurrentRoadSegment (const dwMapsRoadSegment currentRoadSegment, const dwVector3f position, const dwMatrix3d *localToENURotation33, dwTime_t timestamp, dwLanePlanHandle_t lanePlan)
	Update the current point on the lane plan based on a pose defined in relative coordinates. More...

DW_API_PUBLIC dwStatus	dwLanePlan_updateCurrentPointWithGlobalPose (const dwMapsGeoPoint gps, const dwMatrix3d localToENURotation33, dwTime_t timestamp, bool ignoreHeight, dwLanePlanHandle_t lanePlan)
	Update the current point on the lane plan based on a pose defined in absolute coordinates. More...

DW_API_PUBLIC dwStatus	dwLanePlan_updateCurrentPointWithLocalPose (const dwMapsRoadSegment referenceRoadSegment, const dwVector3f position, const dwMatrix3d *localToENURotation33, dwTime_t timestamp, dwLanePlanHandle_t lanePlan)
	Update the current point on the lane plan based on a pose defined in relative coordinates. More...

DW_API_PUBLIC dwStatus	dwLanePlanner_initialize (dwLanePlannerHandle_t *lanePlanner, float32_t maxPlanLengthMeters, dwConstMapHandle_t map)
	Creates a lane planner object and returns a handle to it. More...

DW_API_PUBLIC dwStatus	dwLanePlanner_release (dwLanePlannerHandle_t lanePlanner)
	Release a lane planner object. More...

DW_API_PUBLIC dwStatus	dwLanePlanner_run (const dwMapsLane startLane, const dwMapsLane const targetLanes, uint32_t targetLaneCount, const dwMapsGeoPoint gpsPathPoints, uint32_t gpsPathPointCount, bool ignoreHeight, dwLanePlannerCostFunction_t costFn, void *costFnContext, dwLanePlanHandle_t lanePlan, dwLanePlannerHandle_t lanePlanner)
	Create a lane plan along the provided gps path points, based on the map that is given at initialization. More...

Data Structure Documentation

◆ dwLanePlan

struct dwLanePlan

Data Fields
uint32_t	segmentCount	Number segments in lane plan.
const dwLanePlanSegment *	segments	List of segments along the lane plan.

◆ dwLanePlanActions

struct dwLanePlanActions

Data Fields
float32_t	distToDestination	distance to reach destination on the lane plan
bool	hasLaneChange	true only if a valid lane change ahead is detected
bool	hasLaneMerge	true only if a valid lane merge ahead is detected
bool	hasLaneSplit	true only if a valid lane split ahead is detected
dwLanePlanLaneChange	laneChange
float32_t	laneChangeDist	distance to where the next lane change action takes place (start of the next lane change, or 0.0f if the lane change should happen now)
dwMapsLaneMerge	laneMerge
float32_t	laneMergeDist	distance to the next lane merge point
dwMapsLaneSplit	laneSplit
float32_t	laneSplitDist	distance to the next lane split point
float32_t	timeToDestination	estimated time to reach destination on the lane plan

◆ dwLanePlanIndex

struct dwLanePlanIndex

Data Fields
uint32_t	lanePlanLaneIndex	index of a dwLanePlanLane in the dwLanePlanSegment
uint32_t	mapsLaneIndex	index of a dwMapsLane in the dwLanePlanLane
uint32_t	pointIndex	index of a point in the dwMapsLane geometry
uint32_t	segmentIndex	index of a dwLanePlanSegment in the dwLanePlan

◆ dwLanePlanLane

struct dwLanePlanLane

Data Fields
const float32_t *	distances	Distance in [m] to beginning of each dwMapsLane. Relative to beginning of the first lane of the lane plan.
uint32_t	laneCount	Number of dwMapsLanes.
const bool *	laneForward	Whether to move forward on lane geometry, per dwMapsLane.
const dwMapsLane **	lanes	Pointers to the sequential dwMapsLane's.
const dwTime_t *	times	Estimated time of arrival in [us] per dwMapsLane. Relative to beginning of the first lane of the lane plan. Computed based on lane speed limits. 50 km/h assumed if no speedLimit is defined for a lane.

◆ dwLanePlanLaneChange

struct dwLanePlanLaneChange

Data Fields
uint32_t	laneChangeCount	number of lanes that need to be changed
float32_t	laneChangeLength	available distance to do the lane change. so this is the distance to the end of the lane change, starting at the current position if it is on the lane change, or starting at the lane change start if current position is not on the lane change yet.
dwMapsSide	laneChangeSide	side towards the lane change is going

◆ dwLanePlanSegment

struct dwLanePlanSegment

Data Fields
dwMapsSide	laneChangeSide	left, right, none
uint32_t	laneCount	Number of lanes in this segment. If there is more than one it is a lane change segment.
const dwLanePlanLane *	lanes	List of parallel lanes. The first lane in the list is the lane where the lane plan segment is entered, the last one is where the lane plan segment is exited. If there is more than one lane, lane changes need to be done from the first to the last lane, traversing in all in-between lanes in sequential order.

Typedef Documentation

◆ dwConstLanePlanHandle_t

typedef struct dwLanePlanObject const* dwConstLanePlanHandle_t

Definition at line 74 of file LanePlanner.h.

◆ dwConstLanePlannerHandle_t

typedef struct dwLanePlannerObject const* dwConstLanePlannerHandle_t

Definition at line 71 of file LanePlanner.h.

◆ dwLanePlanHandle_t

typedef struct dwLanePlanObject* dwLanePlanHandle_t

Definition at line 73 of file LanePlanner.h.

◆ dwLanePlannerCostFunction_t

typedef float32_t(* dwLanePlannerCostFunction_t) (const dwMapsLane *lane, bool forward, float32_t length, uint32_t laneChangeCount, dwMapsSide laneChangeSide, const dwMapsGeoPoint *gpsPathPoint, uint32_t gpsPathPointCount, bool ignoreHeight, const dwMapsLane *neighborLane, void *context)

Cost function that allows to implement a custom cost calculation in the dijkstra algorithm that calculates the optimal lane plan.

It has to return a value >= 0.

Parameters

[in]	lane	Source lane of the search node.
[in]	forward	True if moving direction is along the lane polyline direction. False if moving direction is opposite to the lane polyline direction.

Note: Check this direction when looking at the 'laneChangeSide' argument, as the side here is relative to the polyline direction.

Parameters

[in]	length	Length of the source lane.
[in]	laneChangeCount	Number of lane changes on this node.
[in]	laneChangeSide	The side towards which the lane change happens. Note that this is relative to the polyline direction, not the driving direction.
[in]	gpsPathPoint	Pointer to list of dwMapsGeoPoint gps waypoints
[in]	gpsPathPointCount	Number of gps waypoints
[in]	ignoreHeight	Flag to assume gps points have height of 0
[in]	neighborLane	Next lane after current lane plan segment. That is the lane that connects to the on one after the lane change (or to 'lane' is there is no lane change).
[in]	context	Pointer provided by the user in the call where the cost function is provided.

Returns: Cost calculated from input arguments.

Definition at line 216 of file LanePlanner.h.

◆ dwLanePlannerHandle_t

typedef struct dwLanePlannerObject* dwLanePlannerHandle_t

Definition at line 70 of file LanePlanner.h.

Function Documentation

◆ dwLanePlan_computeDistance()

DW_API_PUBLIC dwStatus dwLanePlan_computeDistance	(	float32_t *	distance,
		const dwLanePlanIndex *	index1,
		const dwLanePlanIndex *	index2,
		dwConstLanePlanHandle_t	lanePlan
	)

◆ dwLanePlan_containsLane()

DW_API_PUBLIC dwStatus dwLanePlan_containsLane	(	bool *	isOnLanePlan,
		const dwMapsLane *	lane,
		dwConstLanePlanHandle_t	lanePlan
	)

Check whether a given dwMapsLane is part of the lane plan.

Parameters

[out]	isOnLanePlan	Resulting boolean, indicating whether given dwMapsLane is part of the lane plan.
[in]	lane	dwMapsLane to be checked.
[in]	lanePlan	Lane plan to be checked.

Returns: DW_SUCCESS Successfully searched the lane plan for the dwMapsLane.
DW_INVALID_ARGUMENT At least one of the arguments is null

◆ dwLanePlan_decreaseIndex()

DW_API_PUBLIC dwStatus dwLanePlan_decreaseIndex	(	dwLanePlanIndex *	lanePlanIndex,
		uint32_t	decreaseCount,
		dwConstLanePlanHandle_t	lanePlan
	)

Helper function to compute the previous lane plan point on a lane plan.

At the beginning of a lane plan lane, the index will jump onto the connected lane of the previous lane plan segment.

Parameters

[in,out]	lanePlanIndex	Lane plan index to be decreased.
[in]	decreaseCount	Number of times the index is to be decreased.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully decreased given lane plan index.
DW_INVALID_ARGUMENT lanePlanIndex is a nullptr.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE Failed to decrease the lane point index.

◆ dwLanePlan_findClosestPoint()

DW_API_PUBLIC dwStatus dwLanePlan_findClosestPoint	(	dwMapsGeoPoint *	closestPoint,
		dwLanePlanIndex *	lanePlanIndex,
		const dwMapsGeoPoint *	gps,
		bool	ignoreHeight,
		dwLanePlanHandle_t	lanePlan
	)

Helper function to find the closest line segment on the lane plan to a given gps location, together with the corresponding closest lane plan point (the closer of the two lane plan points on the line segment that contains the closest geometric point).

Parameters

[out]	closestPoint	Closest point on lane plan (it can be between two lane plan points). nullptr allowed if this output is not needed.
[out]	lanePlanIndex	Lower index of line segment that contains the closest point. nullptr allowed if this output is not needed.
[in]	gps	Query point.
[in]	ignoreHeight	Defines whether distances are computed based on lat and lon only.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned closest point on lane plan.
DW_INVALID_ARGUMENT gps is a nullptr.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE Failed to return the closest point on given lane plan.

◆ dwLanePlan_get()

DW_API_PUBLIC dwStatus dwLanePlan_get	(	dwLanePlan *	lanePlan,
		dwConstLanePlanHandle_t	lanePlanHandle
	)

Retrieve the result of a previous 'dwLanePlanner_run' call.

Parameters

[out]	lanePlan	Lane plan contained in the lane plan object.
[in]	lanePlanHandle	Lane plan object handle.

Returns: DW_SUCCESS Successfully returned result.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_INVALID_ARGUMENT One or more arguments is a nullptr.

◆ dwLanePlan_getComplexity()

DW_API_PUBLIC dwStatus dwLanePlan_getComplexity	(	uint32_t *	totalLaneChangeCount,
		uint32_t *	totalLaneSplitCount,
		uint32_t *	totalLaneMergeCount,
		dwLanePlanHandle_t	lanePlan
	)

Returns some numbers that indicate how complex it is to autonomously drive a given lane plan.

Parameters

[out]	totalLaneChangeCount	Number of lane changes needed when following the lane plan by always changing to target lane immediately at each lane plan segment.
[out]	totalLaneSplitCount	Number of lane splits on all lanes of the lane plan. (

Note: only a subset of those lane splits will be encoutered while driving, as a car is always on only one lane of a lane plan segment.)

Parameters

[out] totalLaneMergeCount Number of lane merges on all lanes of the lane plan. (

Note: only a subset of those lane merges will be encoutered while driving, as a car is always on only one lane of a lane plan segment.)

Parameters

[in] lanePlan Lane plan.

Returns: DW_SUCCESS Successfully returned lane plan complexity.
DW_INVALID_ARGUMENT One or more arguments is a nullptr.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.

◆ dwLanePlan_getCurrentGeoPoint()

DW_API_PUBLIC dwStatus dwLanePlan_getCurrentGeoPoint	(	dwMapsGeoPoint *	pointOnLanePlan,
		dwConstLanePlanHandle_t	lanePlan
	)

Get current point on the lane plan in gps coordinates.

The current lane plan point is set in dwLanePlan_updateCurrentPoint.

Parameters

[out]	pointOnLanePlan	Current point the lane plan.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned index of current lane plan point.
DW_INVALID_ARGUMENT pointOnLanePlan or lanePlan is null
DW_NOT_AVAILABLE Failed to return the lane plan point index. A lane plan needs to be computed first.

◆ dwLanePlan_getCurrentIndex()

DW_API_PUBLIC dwStatus dwLanePlan_getCurrentIndex	(	dwLanePlanIndex *	lanePlanIndex,
		dwConstLanePlanHandle_t	lanePlan
	)

Get the index to the current point on the lane plan.

The current lane plan index is set in dwLanePlan_updateCurrentPoint.

Parameters

[out]	lanePlanIndex	Current lane plan point index.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned index of current lane plan point.
DW_INVALID_ARGUMENT lanePlanindex or lanePlan is null
DW_NOT_AVAILABLE Failed to return the lane plan point index. A lane plan needs to be computed first.

◆ dwLanePlan_getCurrentPoint()

DW_API_PUBLIC dwStatus dwLanePlan_getCurrentPoint	(	const dwMapsRoadSegment **	referenceRoadSegment,
		dwVector3f *	pointOnLanePlan,
		dwConstLanePlanHandle_t	lanePlan
	)

Get current point on the lane plan in coordinates relative to a reference road segment.

The current lane plan point is set in dwLanePlan_updateCurrentPoint.

Parameters

[out]	referenceRoadSegment	Reference road segment that defines the coordinate system of the returned point.
[out]	pointOnLanePlan	Current point the lane plan.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned index of current lane plan point.
DW_INVALID_ARGUMENT At least one of the arguments is null
DW_NOT_AVAILABLE Failed to return the lane plan point index. A lane plan needs to be computed first.

◆ dwLanePlan_getEstimatedArrivalInfo()

DW_API_PUBLIC dwStatus dwLanePlan_getEstimatedArrivalInfo	(	float32_t *	distToDestination,
		float32_t *	timeToDestination,
		dwConstLanePlanHandle_t	lanePlanHandle
	)

Get estimated time and distance to reach the end of the lane plan from current position.

Time of arrival is estimated with speed limits on map, instead of current vehicle speed.

Parameters

[out]	distToDestination	Distance to destination on current lane plan in meters.
[out]	timeToDestination	Estimated time of arrival on current lane plan in seconds.
[in]	lanePlanHandle	Current lane plan.

Returns: DW_SUCCESS Successfully returned estimated distance and time to destination.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_INVALID_ARGUMENT distToDestination or timeToDestination or lanePlanHandle is null.

◆ dwLanePlan_getLanePlanActions()

DW_API_PUBLIC dwStatus dwLanePlan_getLanePlanActions	(	dwLanePlanIndex *	laneChangePointIndex,
		dwLanePlanIndex *	laneSplitPointIndex,
		dwLanePlanActions *	lanePlanActionInfo,
		dwLanePlanHandle_t	lanePlan
	)

Get information about the next lane change and lane split.

Returns the next lane change and the next lane split on current lane. Current point is set by dwLanePlan_updateCurrentPoint.

Parameters

[out]	laneChangePointIndex	Index of point where the next lane change happens. nullptr allowed if this output is not needed.
[out]	laneSplitPointIndex	Index of point where the next lane split happens. nullptr allowed if this output is not needed.
[out]	lanePlanActionInfo	Description of possible actions (lane change and lane split) to take in the current lane, and distances to where the corresponding actions will take place. nullptr allowed if info of certain action is not needed.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned the next action(s) to take.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE No required action found after current point.

◆ dwLanePlan_getLanePlanActionsNew()

DW_API_PUBLIC dwStatus dwLanePlan_getLanePlanActionsNew	(	dwLanePlanIndex *	laneChangePointIndex,
		dwLanePlanIndex *	laneSplitPointIndex,
		dwLanePlanIndex *	laneMergePointIndex,
		dwLanePlanActions *	lanePlanActionInfo,
		dwLanePlanHandle_t	lanePlan
	)

Get information about the next lane change, lane split, and lane merge.

Returns the next lane change, next lane split and lane merge on current lane. Current point is set by dwLanePlan_updateCurrentPoint.

Parameters

[out]	laneChangePointIndex	Index of point where the next lane change happens. nullptr allowed if this output is not needed.
[out]	laneSplitPointIndex	Index of point where the next lane split happens. nullptr allowed if this output is not needed.
[out]	laneMergePointIndex	Index of point where the next lane merge ends. nullptr allowed if this output is not needed.
[out]	lanePlanActionInfo	Description of upcoming action (lane change, lane split, lane merge) on the current lane, and distances to where the corresponding actions should take place. nullptr allowed if this output is not needed.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned the next action(s) to take.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE No required action found after current point.

◆ dwLanePlan_getLanePlanSplitMergeDetails()

DW_API_PUBLIC dwStatus dwLanePlan_getLanePlanSplitMergeDetails	(	dwMapsLaneSplitDetails *	laneSplit,
		dwMapsLaneMergeDetails *	laneMerge,
		dwLanePlanHandle_t	lanePlan
	)

Get information about the next lane change, lane split, and lane merge.

Returns the details of lane split and merge from previous dwLanePlan_getLanePlanActionsNew call

Parameters

[out]	laneSplit	Index of point where the next lane merge ends. nullptr allowed if this output is not needed.
[out]	laneMerge	Description of upcoming action (lane change, lane split, lane merge) on the current lane, and distances to where the corresponding actions should take place. nullptr allowed if this output is not needed.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned the current lane split and merge details.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE dwLanePlan_getLanePlanActionsNew was not called before calling this API or the previous call to dwLanePlan_getLanePlanActionsNew failed

◆ dwLanePlan_getNextLaneChange()

DW_API_PUBLIC dwStatus dwLanePlan_getNextLaneChange	(	dwLanePlanIndex *	laneChangePointIndex,
		dwLanePlanLaneChange *	laneChange,
		float32_t *	distance,
		dwLanePlanHandle_t	lanePlan
	)

Get next lane change.

Returns the next lane change on current lane. Current point is set by dwLanePlan_updateCurrentPoint.

Parameters

[out]	laneChangePointIndex	Index of point where the next lane change happens. nullptr allowed if this output is not needed.
[out]	laneChange	Description of the lane change. nullptr allowed if this output is not needed.
[out]	distance	Distance of the lane change start from current position. nullptr allowed if this output is not needed.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned lane change.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE No lane change found after current point.

◆ dwLanePlan_getNextLaneChangeAt()

DW_API_PUBLIC dwStatus dwLanePlan_getNextLaneChangeAt	(	dwLanePlanIndex *	laneChangePointIndex,
		dwLanePlanLaneChange *	laneChange,
		const dwLanePlanIndex *	queryPointIndex,
		dwConstLanePlanHandle_t	lanePlan
	)

Get the next lane change happening on the lane plan at or after given lane plan index.

To get the lane plan index of the point corresponding to a current vehicle pose, use dwLanePlan_updateCurrentPoint and dwLanePlan_getCurrentPoint.

Parameters

[out]	laneChangePointIndex	Lane plan index of the point where the next lane change happens. nullptr allowed if this output is not needed.
[out]	laneChange	Description of the next lane change. nullptr allowed if this output is not needed.
[in]	queryPointIndex	Lane plan index defining the query position on the lane plan.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned lane change.
DW_INVALID_PARAMETER lanePlanIndex is a nullptr.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE No lane change found after given lanePlanIndex.

◆ dwLanePlan_getNextLaneMerge()

DW_API_PUBLIC dwStatus dwLanePlan_getNextLaneMerge	(	dwLanePlanIndex *	laneMergePointIndex,
		dwMapsLaneMergeDetails *	laneMerge,
		float32_t *	distance,
		dwLanePlanHandle_t	lanePlan
	)

Get next lane merge.

Returns the next merge split on current lane. Current point is set by dwLanePlan_updateCurrentPoint.

Parameters

[out]	laneMergePointIndex	Index of point where the next lane merge ends. nullptr allowed if this output is not needed.
[out]	laneMerge	Description of the lane merge. nullptr allowed if this output is not needed.
[out]	distance	Distance of the lane merge from current position. nullptr allowed if this output is not needed.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned lane split.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE No lane merge found after current point.

◆ dwLanePlan_getNextLaneMergeAt()

DW_API_PUBLIC dwStatus dwLanePlan_getNextLaneMergeAt	(	dwLanePlanIndex *	laneMergePointIndex,
		dwMapsLaneMergeDetails *	laneMerge,
		const dwLanePlanIndex *	queryPointIndex,
		dwLanePlanHandle_t	lanePlan
	)

Get the next lane merge happening on the lane plan at or after given lane plan index.

To get the lane plan index of the point corresponding to a current vehicle pose, use dwLanePlan_updateCurrentPoint and dwLanePlan_getCurrentPoint.

Parameters

[out]	laneMergePointIndex	Lane plan index of the point where the next lane merge ends. nullptr allowed if this output is not needed.
[out]	laneMerge	Description of the next lane merge. nullptr allowed if this output is not needed.
[in]	queryPointIndex	Lane plan point index defining the query position on the lane plan.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned lane merge.
DW_INVALID_ARGUMENT One or more arguments is a nullptr.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE No lane merge found after given lanePlanIndex.
DW_INTERNAL_ERROR Unexpected internal error.

◆ dwLanePlan_getNextLaneSplit()

DW_API_PUBLIC dwStatus dwLanePlan_getNextLaneSplit	(	dwLanePlanIndex *	laneSplitPointIndex,
		dwMapsLaneSplitDetails *	laneSplit,
		float32_t *	distance,
		dwLanePlanHandle_t	lanePlan
	)

Get next lane split.

Returns the next lane split on current lane. Current point is set by dwLanePlan_updateCurrentPoint.

Parameters

[out]	laneSplitPointIndex	Index of point where the next lane split happens. nullptr allowed if this output is not needed.
[out]	laneSplit	Description of the lane split. nullptr allowed if this output is not needed.
[out]	distance	Distance of the lane split from current position. nullptr allowed if this output is not needed.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned lane split.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE No lane split found after current point.

◆ dwLanePlan_getNextLaneSplitAt()

DW_API_PUBLIC dwStatus dwLanePlan_getNextLaneSplitAt	(	dwLanePlanIndex *	laneSplitPointIndex,
		dwMapsLaneSplitDetails *	laneSplit,
		const dwLanePlanIndex *	queryPointIndex,
		dwLanePlanHandle_t	lanePlan
	)

Get the next lane split happening on the lane plan at or after given lane plan index.

To get the lane plan index of the point corresponding to a current vehicle pose, use dwLanePlan_updateCurrentPoint and dwLanePlan_getCurrentPoint.

Parameters

[out]	laneSplitPointIndex	Lane plan index of the point where the next lane split starts. nullptr allowed if this output is not needed.
[out]	laneSplit	Description of the next lane split. nullptr allowed if this output is not needed.
[in]	queryPointIndex	Lane plan point index defining the query position on the lane plan.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned lane split.
DW_INVALID_PARAMETER One or more arguments is a nullptr.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE No lane split found after given lanePlanIndex.
DW_INTERNAL_ERROR Unexpected internal error.

◆ dwLanePlan_getPoint()

DW_API_PUBLIC dwStatus dwLanePlan_getPoint	(	dwMapsGeoPoint *	pointWGS84,
		dwVector3f *	pointLocal,
		const dwMapsLane **	lane,
		dwTime_t *	time,
		const dwLanePlanIndex *	index,
		dwConstLanePlanHandle_t	lanePlan
	)

Get point data from lane plan at given index.

Parameters

[out]	pointWGS84	WGS84 coordinates at index. nullptr allowed if this output is not needed.
[out]	pointLocal	local coordinates at index. nullptr allowed if this output is not needed.
[out]	lane	Maps lane at index. nullptr allowed if this output is not needed.
[out]	time	Arrival time at index. nullptr allowed if this output is not needed.
[in]	index	Index pointing into the provided lane plan.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully returned point data at index
DW_INVALID_ARGUMENT index is a nullptr or not valid.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.

◆ dwLanePlan_getTargetLanes()

DW_API_PUBLIC dwStatus dwLanePlan_getTargetLanes	(	dwMapsLanePtrBuffer *	lanes,
		uint32_t *	laneChangeIndex,
		float32_t	distance,
		dwLanePlanHandle_t	lanePlan
	)

Get target lane ptrs e.g.

for an upcoming split, return lanes before the split before (no ambiguity) and desired lanes after split (again no ambiguity) e.g. for an upcoming lane change, after "change now", return the immediate target adjacent lanes and its successors Use distance as the stopping criterion for successors

Parameters

[out]	lanes	output maps lane array for targt lanes
[out]	laneChangeIndex	output index in lane array indicating the LaneCount of the ego lane (lanes[laneChangeIndex] is the first index in lane change target lane)
[in]	distance	length ahead of ego for stitching map lanes ahead
[in]	lanePlan	current lane plan

Returns: DW_SUCCESS Successfully returned estimated distance and time to destination.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_INVALID_ARGUMENT distToDestination or timeToDestination or lanePlanHandle is null.

◆ dwLanePlan_increaseIndex()

DW_API_PUBLIC dwStatus dwLanePlan_increaseIndex	(	dwLanePlanIndex *	lanePlanIndex,
		uint32_t	increaseCount,
		dwConstLanePlanHandle_t	lanePlan
	)

Helper function to compute the next lane plan point along a lane plan.

At the end of a lane plan lane, the index will jump onto the connected lane of the subsequent lane plan segment.

Parameters

[in,out]	lanePlanIndex	Lane plan index to be increased.
[in]	increaseCount	Number of times the index is to be increased.
[in]	lanePlan	Lane plan.

Returns: DW_SUCCESS Successfully increased given lane plan index.
DW_INVALID_ARGUMENT lanePlanIndex is a nullptr.
DW_BAD_CAST Could not successfully cast lanePlan handle to a lane plan object.
DW_NOT_AVAILABLE Failed to increase the lane plan index.

◆ dwLanePlan_initialize()

DW_API_PUBLIC dwStatus dwLanePlan_initialize	(	dwLanePlanHandle_t *	lanePlan,
		dwConstLanePlannerHandle_t	lanePlanner
	)

Creates a lane plan object and returns a handle to it.

Lane Plan objects store the result of the lane planner.

Note: : allocates memory.

Parameters

[out]	lanePlan	Resulting lane planner handle. Preallocated buffer sizes are defined in the lane planner.
[in]	lanePlanner	Lane Planner object handle.

Returns: DW_SUCCESS lanePlan handle is successfully initialized.
DW_INVALID_ARGUMENT lanePlan is nullptr.

◆ dwLanePlan_initializeLanePlanActions()

DW_API_PUBLIC dwStatus dwLanePlan_initializeLanePlanActions ( dwLanePlanActions * lpActions )

Default initialize a dwLanePlanActions object.

Parameters

[out] lpActions obj to be default initialized

Returns: DW_SUCCESS Successfully initialized the object.
DW_INVALID_ARGUMENT Input ptr is a nullptr.

◆ dwLanePlan_release()

DW_API_PUBLIC dwStatus dwLanePlan_release ( dwLanePlanHandle_t lanePlan )

Release a lane plan object.

Parameters

[in,out] lanePlan Lane plan to release.

Returns: DW_SUCCESS lanePlan successfully released.
DW_INVALID_ARGUMENT lanePlan is nullptr.

◆ dwLanePlan_updateCurrentPointWithCurrentRoadSegment()

DW_API_PUBLIC dwStatus dwLanePlan_updateCurrentPointWithCurrentRoadSegment	(	const dwMapsRoadSegment *	currentRoadSegment,
		const dwVector3f *	position,
		const dwMatrix3d *	localToENURotation33,
		dwTime_t	timestamp,
		dwLanePlanHandle_t	lanePlan
	)

Update the current point on the lane plan based on a pose defined in relative coordinates.

The resulting current point can be accessed by calling dwLanePlan_getCurrentPoint.

Use this function when it is known that the current lane on is the provided road segment. This reduces the search space for the current point on the lane plan, and thus improves performance.

Parameters

[in]	currentRoadSegment	ID of road segment that defines the position's coordinate system
[in]	position	Current position
[in]	localToENURotation33	3x3 Rotation matrix that rotates from local coordinate system (x: forward, y: left, z: up) into ENU local cartesian coordinate system with origin at the origin of the reference road segment (x: east, y: north, z: up). z coordinate of ENU is the normal of the earth spheroid at origin of the reference road segment. Orientation is not used if localToENURotation33 is nullptr.
[in]	timestamp	Timestamp of the passed pose
[in]	lanePlan	Lane plan on which the current point is being tracked.

Returns: DW_SUCCESS Successfully updated current current point on lane plan.
DW_INVALID_ARGUMENT referenceRoadSegment or position is a nullptr, or lane plan is a null handle
DW_NOT_AVAILABLE Failed to update current point on lane plan. A lane plan needs to be computed first.

◆ dwLanePlan_updateCurrentPointWithGlobalPose()

DW_API_PUBLIC dwStatus dwLanePlan_updateCurrentPointWithGlobalPose	(	const dwMapsGeoPoint *	gps,
		const dwMatrix3d *	localToENURotation33,
		dwTime_t	timestamp,
		bool	ignoreHeight,
		dwLanePlanHandle_t	lanePlan
	)

Update the current point on the lane plan based on a pose defined in absolute coordinates.

The resulting current point can be accessed by calling dwLanePlan_getCurrentPoint.

Parameters

[in]	gps	Current position
[in]	localToENURotation33	3x3 Rotation matrix that rotates from local coordinate system (x: forward, y: left, z: up) into ENU local cartesian coordinate system with origin at the gps point (x: east, y: north, z: up). z coordinate of ENU is the normal of the earth spheroid at the gps point. Orientation is not used if localToENURotation33 is nullptr.
[in]	timestamp	Timestamp of the passed pose
[in]	ignoreHeight	Defines whether distances are computed based on lat and lon only.
[in]	lanePlan	Lane plan on which the current point is being tracked.

Returns: DW_SUCCESS Successfully updated current current point on lane plan.
DW_INVALID_ARGUMENT gps is a nullptr or laneplan is a null handle
DW_NOT_AVAILABLE Failed to update current point on lane plan. A lane plan needs to be computed first.

◆ dwLanePlan_updateCurrentPointWithLocalPose()

DW_API_PUBLIC dwStatus dwLanePlan_updateCurrentPointWithLocalPose	(	const dwMapsRoadSegment *	referenceRoadSegment,
		const dwVector3f *	position,
		const dwMatrix3d *	localToENURotation33,
		dwTime_t	timestamp,
		dwLanePlanHandle_t	lanePlan
	)

Update the current point on the lane plan based on a pose defined in relative coordinates.

The resulting current point can be accessed by calling dwLanePlan_getCurrentPoint.

Parameters

[in]	referenceRoadSegment	ID of road segment that defines the position's coordinate system
[in]	position	Current position
[in]	localToENURotation33	3x3 Rotation matrix that rotates from local coordinate system (x: forward, y: left, z: up) into ENU local cartesian coordinate system with origin at the origin of the reference road segment (x: east, y: north, z: up). z coordinate of ENU is the normal of the earth spheroid at origin of the reference road segment. Orientation is not used if localToENURotation33 is nullptr.
[in]	timestamp	Timestamp of the passed pose
[in]	lanePlan	Lane plan on which the current point is being tracked.

Returns: DW_SUCCESS Successfully updated current current point on lane plan.
DW_INVALID_ARGUMENT referenceRoadSegment or position is a nullptr, or lane plan is a null handle
DW_NOT_AVAILABLE Failed to update current point on lane plan. A lane plan needs to be computed first.

◆ dwLanePlanner_initialize()

DW_API_PUBLIC dwStatus dwLanePlanner_initialize	(	dwLanePlannerHandle_t *	lanePlanner,
		float32_t	maxPlanLengthMeters,
		dwConstMapHandle_t	map
	)

Creates a lane planner object and returns a handle to it.

Note: : allocates memory.

Parameters

[out]	lanePlanner	Resulting lane planner handle.
[in]	maxPlanLengthMeters	Maximum length of result. This defines the module's buffer sizes that are preallocated for the runtime algorithm.
[in]	map	Map object handle from the Maps module.

Returns: DW_SUCCESS lanePlanner handle is successfully initialized.
DW_INVALID_ARGUMENT lanePlanner is nullptr.

◆ dwLanePlanner_release()

DW_API_PUBLIC dwStatus dwLanePlanner_release ( dwLanePlannerHandle_t lanePlanner )

Release a lane planner object.

Parameters

[in,out] lanePlanner Lane planner to release.

Returns: DW_SUCCESS lanePlanner successfully released.
DW_INVALID_ARGUMENT lanePlanner is nullptr.

◆ dwLanePlanner_run()

DW_API_PUBLIC dwStatus dwLanePlanner_run	(	const dwMapsLane *	startLane,
		const dwMapsLane const	targetLanes,
		uint32_t	targetLaneCount,
		const dwMapsGeoPoint *	gpsPathPoints,
		uint32_t	gpsPathPointCount,
		bool	ignoreHeight,
		dwLanePlannerCostFunction_t	costFn,
		void *	costFnContext,
		dwLanePlanHandle_t	lanePlan,
		dwLanePlannerHandle_t	lanePlanner
	)

Create a lane plan along the provided gps path points, based on the map that is given at initialization.

A dijkstra search is applied to the lane graph of the HD map. The search starts at the closest lane to the first point of the input gps path points. The target is any lane on the road segment closest to the last input gps path point.

Parameters

[in]	startLane	Lane where the search is started. If nullptr, the lane assigned to the first gps path point is used.
[in]	targetLanes	Target of the search. If nullptr, the lane group assigned to the last gps path point is used.
[in]	targetLaneCount	Number of lanes in the targetLanes array. If 0, the lane group assigned to the last gps path point is used.
[in]	gpsPathPoints	Path points to follow. If startLane and targetRoadSegment are omitted, at least 2 points are required to define the start and end point of the lane plan.
[in]	gpsPathPointCount	Number of provided gps path points.
[in]	ignoreHeight	Defines whether the height of the path points should be considered when looking for the closest lanes.
[in]	costFn	Optional. Cost function that allows to implement a custom cost calculation for a search node.
[in]	costFnContext	Pointer that is forwarded to costFn.
[in,out]	lanePlan	Resulting lane plan.
[in]	lanePlanner	The lane planner object that comptues the lane plan.

Returns: DW_SUCCESS Lane plan successfully computed.
DW_BAD_CAST Could not successfully cast handles to their corresponding object.
DW_BUFFER_FULL One of the preallocated buffers is full. See error log for details.
DW_INVALID_ARGUMENT lanePlanner is null or less than 2 gps path points are provided.
DW_NOT_AVAILABLE No lanes found for first or last gps path point, or no lane plan was found.
DW_INTERNAL_ERROR Unexpected internal error encountered.

Detailed Description

Data Structures

Typedefs

Functions

Data Structure Documentation

◆ dwLanePlan

◆ dwLanePlanActions

◆ dwLanePlanIndex

◆ dwLanePlanLane

◆ dwLanePlanLaneChange

◆ dwLanePlanSegment

Typedef Documentation

◆ dwConstLanePlanHandle_t

◆ dwConstLanePlannerHandle_t

◆ dwLanePlanHandle_t

◆ dwLanePlannerCostFunction_t

◆ dwLanePlannerHandle_t

Function Documentation

◆ dwLanePlan_computeDistance()

◆ dwLanePlan_containsLane()

◆ dwLanePlan_decreaseIndex()

◆ dwLanePlan_findClosestPoint()

◆ dwLanePlan_get()

◆ dwLanePlan_getComplexity()

◆ dwLanePlan_getCurrentGeoPoint()

◆ dwLanePlan_getCurrentIndex()

◆ dwLanePlan_getCurrentPoint()

◆ dwLanePlan_getEstimatedArrivalInfo()

◆ dwLanePlan_getLanePlanActions()

◆ dwLanePlan_getLanePlanActionsNew()

◆ dwLanePlan_getLanePlanSplitMergeDetails()

◆ dwLanePlan_getNextLaneChange()

◆ dwLanePlan_getNextLaneChangeAt()

◆ dwLanePlan_getNextLaneMerge()

◆ dwLanePlan_getNextLaneMergeAt()

◆ dwLanePlan_getNextLaneSplit()

◆ dwLanePlan_getNextLaneSplitAt()

◆ dwLanePlan_getPoint()

◆ dwLanePlan_getTargetLanes()

◆ dwLanePlan_increaseIndex()

◆ dwLanePlan_initialize()

◆ dwLanePlan_initializeLanePlanActions()

◆ dwLanePlan_release()

◆ dwLanePlan_updateCurrentPointWithCurrentRoadSegment()

◆ dwLanePlan_updateCurrentPointWithGlobalPose()

◆ dwLanePlan_updateCurrentPointWithLocalPose()

◆ dwLanePlanner_initialize()

◆ dwLanePlanner_release()

◆ dwLanePlanner_run()