/dvs/git/dirty/gitlab-master_av/dw/sdk/samples/localization/README.md

Go to the documentation of this file.

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

@page dwx_maps_localization_sample HD Maps Localization Sample
@tableofcontents

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

@section dwx_maps_localization_description Description

The localization sample demonstrates how to use the HD map based localization module.
The sample shows how to:
1. Appropriately obtain and input synchronized GPS, IMU, CAN front facing camera detections, radar/lidar detections and a dwMap into the localization module.
2. Fuse multiple localization modules for different sensors together
3. Update the best-estimate of the vehicle position and orientation within an HD map.
4. Access the best-estimate of the current vehicle position and orientation.
5. Visualize the car's position in an HD map as well as the HD map projected into the front facing camera.

By default, the sample application runs on recorded, example data in the Driveworks library. It will localize using the fusion of localizations from a front facing camera and radar data.

Users can also run the sample on their own data by specifying a Driveworks-formatted HD map file and a Driveworks rig file;<br>
the rig file can specify live GPS, IMU, CAN, and video sensors for in-field usage, or recorded files containing the equivalent data.<br>
This sample can run on both RAW and H264 video streams/files.

@section dwx_maps_localization_running Running the Sample

The shell command for the sample is:

    ./sample_localization --threshold=(0,1)
                          --rigFile=[path/to/rig/file]
                          --map=[path/to/map/directory or path/to/map/xmlfile]
                          --outputFile=[path/to/output/file]
                          --processRate=[int]
                          --printLatency
                          --camera
                          --lidar
                          --radar
                          --gps=[name]
                          --imu=[name]

where

    --threshold=(0,1)
        Threshold for detections; a larger threshold allows less confident detections to be used
        Default value: 0.3

    --rigFile=[path/to/rig/file]
        Rig file containing all information about vehicle sensors and calibration.
        Default value: path/to/data/samples/samples/localization/rig.json

    --map=[path/to/map/directory or path/to/map/xmlfile]
        Map on which to localize. Camera localization can use either path/to/map/xmlfile or path/to/map/directory. Radar/lidar/fusion localizations must use path/to/map/directory. When using path/to/map/directory, the directory must contain core.xml and radar/lidar map layers, when needed.
        Default value: path/to/sdk/data/hdmaps/nvmap

    --outputDir=[/path/to/output/directory]
        When specified, dumps localization output into a /path/to/output/directory/trajectory_[sensor].txt file for each sensor enabled.
        Default value: ""

    --outputCovDir=[/path/to/output/directory]
        When specified, dumps localization covariance output into a /path/to/output/directory/covariance_[sensor].txt file for each sensor enabled.
        Default value: ""

    --processRate=[int]
        Frames per second that sample runs at (as computational capacity allows)
        Default value: 30

    --printLatency
        If passed, prints latency statistics to standard output after sample completion

    --camera
        If passed, enables camera localization. Requires a specified .xml map or a directory containing a core.xml file and loads all camera sensors specified in the rig. If multiple localizations passed, run fusion of all sensors specified.

    --radar
        If passed, enables radar localization. Requires radar map image layer in map directory and loads all radar sensors specified in the rig. If multiple localizations passed, run fusion of all sensors specified.

    --lidar
        If passed, enables lidar localization. Requires lidar map image layers in map directory and loads all lidar sensors specified in the rig. If multiple localizations passed, run fusion of all sensors specified.

    --gps
        Load all gps sensors who's name attribute in the rig file match this parameter.
        Default value: ""

    --imu
        Load all imu sensors who's name attribute in the rig file match this parameter.
        Default value: ""

The sample app has keyboard commands:
- Press the space key to start or pause the application.
- Press the ESC key to close the application.

@section dwx_maps_localization_output Output

- Left: the HD map elements projected into the current view from the front facing camera
- Right: a bird's eye view of the vehicle's localized position in the HD map. The red axis points forward,
    the green axis points left, and the blue axis points up.

@section dwx_maps_localization_colors Color legends

- Blue lines: road boundaries.
- Light green lines: non-traversable lane dividers.
- Dark green lines: traversable lane divider lines.
- Grey lines: local invisible lane divider lines.
- Yellow lines: poles, road signs, and traffic lights.

![Localization Sample](sample_localization.png)

@section dwx_maps_localization_more Additional information

For more details see @ref localization_mainsection .