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

Go to the documentation of this file.

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

@page dwx_parknet_sample Parking Space Detection Sample
@tableofcontents

@section dwx_parknet_description Description

The NVIDIA<sup>&reg;</sup> Parking space detection sample app is an example of using convolutional deep neural network,
called ParkNet, for visual perception of parking spaces.
Specifically, the ParkNet DNN allows detection and precise localization of available parking spaces
in image space and conversion of 2D coordinates from the images space
to 3D world coordinates of the input camera-rig.
The ParkNet app demonstrates perception by overlaying the lines of general-shape quadrilateral
that constitute an available parking space on top of the input video stream.
It also identifies and displays the entry line to the parking space location.
Such an entry line is one of the four lines of the detected quadrilateral.
The conversion of the 2-D coordinates of the corners of the quadrilateral into 3-D coordinates
of the camera-rig space is implemented implicitly within the app.

@warning The Parknet app does not demonstrate any control or path-planning functionality.
To see demonstration of control and path planning functionality,
please take a look at `Parking` sample app.

The ParkNet sample app has several input parameters defining its behavior.
The following section explains the sample app input parameters.

@section dwx_parknet_sample_running Running the Sample

The ParkNet sample, `sample_parking_perception`, accepts the following optional parameters.
If none are specified, it performs detections of parking spaces on a supplied pre-recorded video.

    ./sample_parking_perception --input-type=[video|camera]
                                  --camera-type=[camera]
                                  --camera-group=[a|b|c|d]
                                  --camera-index=[0|1|2|3]
                                  --video=[path/to/video]
                                  --stopFrame=[frame number]
                                  --ltm=[0|1]

Where:

    --input-type=[video|camera]
            Defines if the input is from a live camera or from a recorded video.
            Live camera is supported only on NVIDIA DRIVE(tm) platforms.
            It is not supported on Linux (x86 architecture) host systems.
            Default value: video

    --camera-type=[camera]
            Specifies a supported AR0231 `RCCB` sensor.
            Only applicable if --input-type=camera.
            Default value: ar0231-rccb-bae-sf3324

    --camera-group=[a|b|c|d]
            Is the group where the camera is connected to.
            Only applicable if --input-type=camera.
            Default value: a

    --camera-index=[0|1|2|3]
            Indicates the camera index on the given port.
            Default value: 0

    --video=[path/to/video]
            Defines the path to the video for the app to process. If this option is not set, the default sample
            video is used.
            Default value: data/samples/parking/sample.h264

    --model=[DEFAULT]
            Defines the ParkNet model to use for detection of parking spaces. There is currently only a single model available - DEFAULT.
            Default value: DEFAULT

    --stopFrame=[frame number]
            Defines the end position of the video segment for the app. Only frames up to this frame_number
            will be processed. The special setting of `0` enables to process all frames from
            the sequence with unlimited looping.
            Default value: 0

    --ltm=[0|1]
            Defines the setting of local tone mapping. The value of `1` enables the local tone-mapping,
            `0` disables it.
            Default value: 0

@subsection dwx_parknet_sample_examples Examples

### To run the sample on a default video in a loop

    ./sample_parking_perception

### To run the sample on a user-provided video (H264 or RAW) in a loop

    ./sample_parking_perception --video=<video file.raw>

### To run the ParkNet sample app on first 3000 frames of user-provided video

    ./sample_parking_perception --video=<video file.raw> --stopFrame=3000

### To run the sample on a live video from a camera

    ./sample_parking_perception --input-type=camera --camera-type=<rccb camera type> --camera-group=<camera group> --camera-index=<camera idx on camera group>

where `<camera type>` is a supported `RCCB` sensor.
See @ref supported_sensors for the list of supported cameras for each platform.

### To apply local tone mapping when processing video

    ./sample_parking_perception --ltm=1

@section dwx_parknet_sample_output Output

In the app's output, the green overlay lines represent detected parking spaces.
The red line within the parking-lines boundary represents the entry line to the parking space.
Such a line corresponds to a line between two of the four corners representing the parking space.

The following image shows a typical output of the ParkNet sample app on the default video sequence.
![Sample Parking Detection Output](images/parknet_sample_app.png)

@section dwx_parknet_sample_limitations Limitations

@warning ParkNet DNN currently has limitations that could affect its performance:

- The ParkNet is trained for the parking situations occurring in the United States of America. Most of the training
  data came from the US state of California and, thus, the performance is optimized for the layout of parking spaces
  typical in California.
- The trained data was dominated by parking lots and parking garages. Thus, the ParkNet best performance is
  observed on parking lots with most of the parking spaces available.
- The trained data was dominated by daytime, clear-weather data. As a result, the ParkNet DNN
  does not perform well in dark or rainy conditions.