planning/laneplanner/docs/usecase6.md

Go to the documentation of this file.

# Copyright (c) 2019-2020, NVIDIA CORPORATION.  All rights reserved.

@page laneplanner_usecase6 Lane Plan Events

@note SW Release Applicability: This tutorial is applicable to modules in **NVIDIA DRIVE Software** releases.

There are 3 kinds of events that appear while driving along a Lane Plan:

- Lane changes
- Lane splits
- Lane merges

An any point on the lane plan the next appearance of each event can be queried:

```{.cpp}
    dwStatus dwLanePlan_getNextLaneChange(
        dwLanePlanIndex* laneChangePointIndex,
        dwLanePlanLaneChange* laneChange,
        const dwLanePlanIndex* queryPointIndex,
        dwConstLanePlanHandle_t lanePlan);

    dwStatus dwLanePlan_getNextLaneSplit(
        dwLanePlanIndex* laneSplitPointIndex,
        dwLanePlanLaneSplit* laneSplit,
        const dwLanePlanIndex* queryPointIndex,
        dwConstLanePlanHandle_t lanePlan);

    dwStatus dwLanePlan_getNextLaneMerge(
        dwLanePlanIndex* laneMergelanePlanIndex,
        dwLanePlanLaneMerge* laneMerge,
        const dwLanePlanIndex* queryPointIndex,
        dwConstLanePlanHandle_t lanePlan);
```

##### Lane Change

A Lane Change is described by the lane change side in driving direction and the number of lane changes that are necessary:

```{.cpp}
    typedef struct dwLanePlanLaneChange  {
        // Side towards the lane change is going.
        dwMapsSide laneChangeSide;

        // Number of lanes that need to be changed.
        uint32_t laneChangeCount;  
    } dwLanePlanLaneChange;
```

The exact geometry about where the lane change must happen can be extracted from the Lane Plan Segment, where the lane change happens.

##### Lane Split

A Lane Split is a case where a lane has more than one outgoing connections. The exact point of the lane split is the point on the Lane Plan that corresponds to the returned laneSplitPointIndex.

The involved lanes are described in the dwLanePlanLaneSplit struct:

```{.cpp}
    typedef struct dwLanePlanLaneSplit
    {
        // lane that splits
        const dwMapsLane* laneBeforeSplit;

        // list of connections leading into const the new lanes,
        // sorted from left to right.
        dwMapsLaneConnection* splitLanes[DW_MAPS_MAX_LANE_CONNECTIONS];


        // Number of lanes emerging from
        // the lane before the split.
        uint32_t splitCount;

        // Index of the connection that follows the lane plan.
        // DW_PLANNING_LANEPLANNER_INVALID_LANE_INDEX
        // if the information is not available.
        uint32_t splitIndex;
    } dwLanePlanLaneSplit;
```

The key fields in this structure are:

- laneBeforeSplit enters the lane split point.
- splitLanes lists all outgoing connections.
- splitIndex refers to the connection in that list that must be followed to stay on the Lane Plan.

##### Lane Merge

A Lane Merge is a case where a lane has more than one incoming connections. The exact point where the joining lanes merge into a single lane is the point on the Lane Plan that corresponds to the returned lanePlanMergeIndex. The involved lanes in the merge are described in the `dwLanePlanLaneMerge` struct:

```{.cpp}
    typedef struct dwLanePlanLaneMerge
    {
        //< lane into which the lanes merge.
        const dwMapsLane* laneAfterMerge;

        //< connections leading from
        //  'laneAfterMerge' into the
        //  merging lanes.
        //  Sorted from left to right.
        const dwMapsLaneConnection* mergingLanes[DW_MAPS_MAX_LANE_CONNECTIONS];

        // number of merging lanes
        uint32_t mergingLaneCount;

        // Index of the connection that connects to the lane on
        // the lane plan. DW_ROUTPLANNER_INVALID_LANE_INDEX
        //  if the information is not available.
        uint32_t mergingLaneIndex;
    } dwLanePlanLaneMerge;
```

‘laneAfterMerge’ is the lane after the merge point. All incoming connections forming the merge are listed in the ‘mergingLanes’ list, with ‘mergingLaneIndex’ referring to the connection that comes from the Lane Plan.