maps/docs/usecase3.md

Go to the documentation of this file.

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

@page maps_usecase3 Map Query

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

## Result Buffers

Maps module functions that return an array of elements write the returned elements into a fixed size buffer that is passed in as an argument. There are Buffer structs for various map elements:

- `dwMapsGeoPointBuffer`
- `dwMapsPointBuffer`
- `dwMapsPolyline3fBuffer`
- `dwMapsLaneBuffer`
- `dwMapsLaneDividerLineBuffer`
- `dwMapsFeatureBuffer`
- `dwMapsLaneDividerBuffer`
- `dwMapsRoadSegmentBuffer`
- `dwMapsRoadSegmentPointerBuffer`

A Buffer struct must be initialized before being passed to the function:

- buffer: pointer to the fixed size array
- maxSize: size of the fixed size array
- size: current number of valid elements in the array

## Query Functions

### Road Segments

Road Segments provide access to all the map data.

The dwMaps_getRoadSegments() function returns copies of Road Segments that overlap with a bounding box of longitude and latitude coordinates.

```{.cpp}
   dwStatus dwMaps_getRoadSegments(
       dwMapsRoadSegmentBuffer* roadSegments,
       const dwMapsBounds* bounds,
       dwConstMapHandle_t mapHandle);
```

To retrieve pointers to Road Segments owned by the system instead use dwMaps_getRoadSegmentPointers().
This has the advantage of reduced memory footprint vs creating copies of dwMapsRoadSegment.

```{.cpp}
   dwStatus dwMaps_getRoadSegmentPointers(
       dwMapsRoadSegmentPointerBuffer* roadSegmentPointers,
       const dwMapsBounds* bounds,
       dwConstMapHandle_t mapHandle);
```

For convenience, there are a few more specific query functions:

- `dwMaps_getLaneDividers()`
- `dwMaps_getFeatures()`

### Lane Dividers

```{.cpp}
   dwStatus dwMaps_getLaneDividers(
       dwMapsLaneDividerBuffer* laneDividers,
       uint32_t typeFilter,
       const dwMapsBounds* bounds,
       dwConstMapHandle_t mapHandle);
```

`dwMaps_getLaneDividers()` returns all Lane Dividers that overlap with a bounding box of longitude and latitude coordinates, filtered by their type. A logical combination of type flags can be used to specify which Lane Dividers are returned.

### Features

```{.cpp}
   dwStatus dwMaps_getFeatures(
       dwMapsFeatureBuffer* features,
       uint32_t typeFilter,
       const dwMapsBounds* bounds,
       dwConstMapHandle_t mapHandle);
```

`dwMaps_getFeatures()` works the same way as `dwMaps_getLaneDividers()`.

### Closest Lane

```{.cpp}
   dwStatus dwMaps_getClosestLane(
       const dwMapsLane** closestLane,
       dwMapsGeoPoint* closestPoint,
       const dwMapsGeoPoint* p,
       dwBool onlyDrivable,
       dwBool ignoreHeight,
       dwConstMapHandle_t mapHandle);
```

`dwMaps_getClosestLane()` returns the closest Lane, and the closest point on it, to a given query point p. When the `onlyDrivable` flag is set to true, non-drivable lanes are not considered. `ignoreHeight` can be set if the height of the input point is unknown or inaccurate. In that case, the distances are compared, after projecting all points to height 0.

@note The maps module also provides a map tracker that allows a robust selection of the current lane when driving along a road. It also incorporates orientation and logical connections and thus can give a better result than just picking the closest lane.

For more information see @ref dwx_hd_map_access_sample .