maps/docs/mainsection.md

Go to the documentation of this file.

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

@page maps_mainsection Maps

@note SW Release Applicability: This module is available in **NVIDIA DRIVE Software** releases.

## About This Module

The maps module provides an API to access NVIDIA<sup>&reg;</sup> DriveWorks HD maps data.

DriveWorks currently provides a conversion tool of HERE HD maps format into a DriveWorks map cache
file (XML). For more details about the tool, please refer to @ref dwx_maptool_here_to_dw_maps.

## Map Content Scope

In DriveWorks the Map represents both geometric landmarks and semantic "payload" information that
is used to enable safe operation and planning for an autonomous vehicle (AV).

In-memory representation of a "complete map" of drivable roads is a non-goal of DriveWorks Maps.
It is assumed that the Map contains a relevant local scope for the vehicle, representing a fraction
of the full world data available from a regional, continental or global scale backend database.

In general, multiple Map requests may be required over the duration of a long-distance drive.

## Core Layer Data

The Core Layer of the Map contains the basic data required for camera-only localization and short
to medium-range planning. This data is fully loaded in RAM as an object graph covering the full
extent of the requested Map.

- Road Segments: `dwMapsRoadSegment`
- Lane Groups: `dwMapsLaneGroup`
- Lanes: `dwMapsLane`
- Lane Divider Groups: `dwMapsLaneDividerGroup`
- Lane Dividers: `dwMapsLaneDivider`
- Features: `dwMapsFeature`

The basic elements are the Road Segments, all data can be accessed through them. A Road Segment
represents a piece of road containing several Lanes, Lane Groups, Lane Dividers, and Features.
Every Road Segment has an associated local ENU coordinate system defined by its WGS84 Origin.
Element geometries for the Road Segment are polylines of 3D points in local ENU coordinates.

Each Lane Group represents a "bundle" of adjacent Lanes with associated Lane Group Traversability.
This bitmask is used by the Lane Planner module to determine connectivity between adjacent lanes.
Lane Group Traversability may be determined automatically by Lane Divider Type or directly modified
by a server-side manual annotation or editing process.

For Lanes, a local polyline represents the centerline geometry of the Lane. Each Lane has pointers
to adjacent Lane Divider Groups, representing physical boundaries both left and right of the Lane.
Lane Divider Groups are contained by a parent Road Segment along with all referencing Lanes making
the ownership model for a Road Segment fully "self-contained".

Lane Dividers belonging to a Lane Divider Group are modeled by local polylines with an associated
Lane Divider Type. Although usually there is often a single Lane Divider at a lane boundary, there
are cases where Lanes are separated with multiple Lane Dividers, for example a painted solid line
and a physical Jersey barrier.

Features are a generic representation of objects encountered along the road, e.g. traffic signs,
traffic lights, etc. Each Feature is described by its type field and local geometry, expressed
like other elements in local ENU coordinates of its parent Road Segment.

## Connections

Road Segments and Lanes have connections to predecessors and successors along the road, represented
by `dwMapsRoadSegmentConnection` and `dwMapsLaneConnection` structs. Lane Connections for a Lane
may be `next` or `previous`. This is a reflection not of driving direction, but geometry ordering.

A connection is represented by the ID of the connected element, and if available, a pointer to it.
If the connected element is currently not in memory, the pointer is a NULL. It is possible that
connected elements have opposite geometry directions, meaning for a `next` connection, the end of
a polyline connects to the end of the connected polyline (and similarly on the start side for
`previous` connections). The `sameDirection` boolean flag in the Lane Connection struct indicates
the geometry directions of connected Lanes are either matching or opposing each other.

Lane Groups, Lanes, Lane Dividers, Lane Divider Groups, and Features each have pointers to parents:

- `dwMapsLaneGroup` -> `dwMapsRoadSegment`
- `dwMapsLane` -> `dwMapsLaneGroup`
- `dwMapsLaneDivider` -> `dwMapsLaneDividerGroup`
- `dwMapsLaneDividerGroup` -> `dwMapsRoadSegment`
- `dwMapsFeature` -> `dwMapsRoadSegment`

## Intersections

As of this release there is no publicly available encoding for data specific to road junctions in
DriveWorks Maps. That is a feature that we are currently developing and plan to expose publicly
in a future DriveWorks release.

## Attributes

Road Segments, Lanes, Lane Dividers and Features have attributes specifying type and properties.

| Main Data Structure | Type and Properties |
|-------------|------------|
| Road Segment  | Type (bridge, tunnel, etc.) |
| Lane | Type (shoulder, car pool, etc.) <br>Driving direction, relative to the geometry polyline |
| Lane Divider | Type (dashed, solid, etc.) <br>Material<br>Color |
| Feature | Type (traffic sign, traffic light, etc.) |

Lane Groups are defined such that Lane attributes are constant over the full length of all Lanes.
Wherever Lane or Lane Divider attributes change, that may affect the Lane Group Traversability
therefore a new Lane Group is required.

## Map Provider

The Map Provider interface defines methods for requesting a Map according to application needs.
Map requests are the way clients communicate their needs for Map content to the Map Provider.

Each implementation of Map Provider is specialized to a particular backend Map data source.
Initially we provide only a basic implementation of Map Provider assuming content exists in the
local filesystem as a cache file (XML) or "map directory" also containing Core and Content Layers.

## General Usage

Here is an example of using the Map Provider to request a Map and query the Core Layer content:

```{.cpp}
    // init map provider with XML cache file
    dwMapProviderHandle_t providerHandle = DW_NULL_HANDLE;
    dwMapProvider_initializeWithCacheFile(...);

    // select bounds of interest
    dwMapsBounds mapBounds{...};

    // request a map with core layer only (no content layers)
    // request processing occurs asynchronously on a worker thread
    dwMapsRequestToken token{};
    dwMapProvider_requestMapForBounds(&requestToken, &mapBounds, NULL, providerHandle);

    // handle to the requested map
    dwConstMapHandle mapHandle = DW_NULL_HANDLE;

    // poll for request completion
    dwStatus requestStatus = DW_NOT_READY;
    while (requestStatus != DW_SUCCESS)
    {
        // application code needs to handle error cases
        requestStatus = dwMapProvider_tryGetRequestedMap(&mapHandle, requestToken, providerHandle);
    }

    // memory for road segment query result
    dwMapsRoadSegmentBuffer roadSegments{...};

    while (...)
    {
        // select bounds of interest
        dwMapsBounds queryBounds{...};

        // query data
        roadSegments.size = 0;
        dwMaps_getRoadSegments(&roadSegments, &queryBounds, ...);

        // access data
        for (uint32_t i = 0; i < roadSegments.size; ++i)
        {
            const dwMapsRoadSegment& roadSegment = roadSegments.buffer[i];
            ...
        }
    }

    // release map back to map provider
    dwMapProvider_releaseMap(mapHandle, providerHandle);

    // release map provider
    dwMapProvider_release(...);
```

## Relevant Tutorials

- @ref maps_usecase1
- @ref maps_usecase2
- @ref maps_usecase3
- @ref maps_usecase4
- @ref maps_usecase5
- @ref maps_usecase6
- @ref maps_usecase7
- @ref maps_usecase8

## APIs

- @ref maps_group