## TrafficCamNet Model Card

### Model Overview <a class="anchor" name="model_overview"></a>

The model described in this card detects one or more physical objects from four categories within an image and returns a box around each object, as well as a category label for each object.  The four categories of objects detected by this model are – car, persons, road signs and two-wheelers.

### Model Architecture <a class="anchor" name="model_architecture"></a>

The model is based on NVIDIA DetectNet_v2 detector with ResNet18 as a feature extractor. This architecture, also known as GridBox object detection, uses bounding-box regression on a uniform grid on the input image.  Gridbox system divides an input image into a grid which predicts four normalized bounding-box parameters (xc, yc, w, h) and confidence value per output class.

The raw normalized bounding-box and confidence detections needs to be post-processed by a clustering algorithm such as DBSCAN or NMS to produce final bounding-box coordinates and category labels.

### Training Algorithm <a class="anchor" name="training_algorithm"></a>

The training algorithm optimizes the network to minimize the localization and confidence loss for the objects.  The training is carried out in two phases.  In the first phase, the network is trained with regularization to facilitate pruning.  Following the first phase, we prune the network removing channels whose kernel norms are below the pruning threshold.  In the second phase the pruned network is retrained.  Regularization is not included during the second phase.

### Citations <a class="anchor" name="citations"></a>

- Redmon, J., Divvala, S., Girshick, R., Farhadi, A.: You only look once: Unified, real-time object detection.  In: CVPR. (2016)
- Erhan, D., Szegedy, C., Toshev, A., Anguelov, D.: Scalable object detection using deep neural networks, In: CVPR. (2014)
- He, K., Zhang, X., Ren, S., Sun, J.: Deep Residual Learning for Image Recognition. In: CVPR (2015)

### Intended Use <a class="anchor" name="intended_use"></a>

Primary use case intended for this model is detecting cars in a color (RGB) image.  The model can be used to detect cars from photos and videos by using appropriate video or image decoding and pre-processing.  As a secondary use case the model can also be used to detect persons, road signs and two-wheelers from images or videos. However, these additional classes are not the main intended use for this model. This model can be used in smart city applications such as traffic pattern analysis, determining anomalous trajectories, etc.

#### Input

RGB Image of dimensions: 960 X 544 X 3 (W x H x C)
Channel Ordering of the Input: NCHW, where N = Batch Size, C = number of channels (3), H = Height of images (544), W = Width of the images (960)
Input scale: 1/255.0
Mean subtraction: None

#### Output

Category labels and bounding-box coordinates for each detected object in the input image.

### How to use this model <a class="anchor" name="how_to_use_this_model"></a>

This model needs to be used with NVIDIA Hardware and Software. For Hardware, the model can run on any NVIDIA GPU including NVIDIA Jetson devices. This model can only be used with [Transfer Learning Toolkit](https://developer.nvidia.com/transfer-learning-toolkit) (TLT), [DeepStream SDK](https://developer.nvidia.com/deepstream-sdk) or [TensorRT](https://developer.nvidia.com/tensorrt).

There are two flavors of the model:

- unpruned
- pruned

The `unpruned` model is intended for training using Transfer Learning Toolkit and the user's own dataset. This can provide high fidelity models that are adapted to the use case. The Jupyter notebook available as a part of [TLT container](https://ngc.nvidia.com/catalog/containers/nvidia:tlt-streamanalytics) can be used to re-train.

The `pruned` model is intended for efficient deployment on the edge using DeepStream SDK or TensorRT. This model accepts `960x544x3` dimension input tensors and outputs `60x34x16` bbox coordinate tensor and `60x34x4` class confidence tensor. DeepStream provides a toolkit to create efficient video analytic pipelines to capture, decode, and pre-process the data before running inference. DeepStream will then post-process the output bbox coordinate tensor and class confidence tensors with NMS or DBScan clustering algorithm to create appropriate bounding boxes. The sample application and config file to run this model are provided in DeepStream SDK.

The `unpruned` and `pruned` models are encrypted and will only operate with the following key:

- Model load key: `tlt_encode`

Please make sure to use this as the key for all TLT commands that require a model load key.

#### Model versions

- **unpruned_v1.0** - ResNet18 based pre-trained model.
- **pruned_v1.0** - ResNet18 deployment models. Contains common INT8 calibration cache for GPU and DLA

#### Instructions to use unpruned model with TLT <a class="anchor" name="instructions_to_use_unpruned_model_with_TLT"></a>

Inorder, to use this model as a pretrained weights for transfer learning, please use the below mentioned snippet as template for the `model_config` component of the experiment spec file to train a DetectNet_v2 model. For more information on the experiment spec file, please refer to the [Transfer Learning Tookit User Guide](https://docs.nvidia.com/TLT/tlt-user-guide/index.html).

```py
model_config {
  num_layers: 18
  pretrained_model_file: "/path/to/the/model.tlt"
  use_batch_norm: true
  objective_set {
    bbox {
      scale: 35.0
      offset: 0.5
    }
    cov {
    }
  }
  training_precision {
    backend_floatx: FLOAT32
  }
  arch: "resnet"
  all_projections: true
}
```

#### Instructions to deploy this model with DeepStream

To create the entire end-to-end video analytics application, deploy this model with [DeepStream SDK](https://developer.nvidia.com/deepstream-sdk). DeepStream SDK is a streaming analytics toolkit to accelerate deployment of AI-based video analytics applications. The pruned model included here can be integrated directly into deepstream by following the instructions mentioned
below.

1. Run the default `deepstream-app` included in the DeepStream docker, by simply executing the commands below.

   ```sh
   ## Download Model:

   mkdir -p $HOME/trafficcamnet && \
   wget https://api.ngc.nvidia.com/v2/models/nvidia/tlt_trafficcamnet/versions/pruned_v1.0/files/resnet18_trafficcamnet_pruned.etlt \
   -O $HOME/trafficcamnet/resnet18_trafficcamnet_pruned.etlt && \
   wget https://api.ngc.nvidia.com/v2/models/nvidia/tlt_trafficcamnet/versions/pruned_v1.0/files/trafficnet_int8.txt \
   -O $HOME/trafficcamnet/trafficnet_int8.txt

   ## Run Application

   xhost +
   docker run --gpus all -it --rm -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY -v $HOME:/opt/nvidia/deepstream/deepstream-5.1/samples/models/tlt_pretrained_models \
   -w /opt/nvidia/deepstream/deepstream-5.1/samples/configs/tlt_pretrained_models nvcr.io/nvidia/deepstream:5.1-21.02-samples \
   deepstream-app -c deepstream_app_source1_trafficcamnet.txt
   ```
2. Install deepstream on your local host and run the deepstream-app.

   To deploy this model with [DeepStream](https://developer.nvidia.com/deepstream-sdk), please follow the instructions below:

   [Download](https://developer.nvidia.com/deepstream-sdk) and install DeepStream SDK. The installation instructions for DeepStream are provided in [DeepStream development guide](https://docs.nvidia.com/metropolis/deepstream/dev-guide/index.html). The config files for the purpose-built models are located in:

   ```sh
   /opt/nvidia/deepstream/deepstream-5.1/samples/configs/tlt_pretrained_models
   ```

   `/opt/nvidia/deepstream` is the default DeepStream installation directory. This path will be different if you are installing in a different directory.

   You will need 2 config files and 1 label file. These files are provided in the `tlt_pretrained_models` directory.

   ```sh
   deepstream_app_source1_trafficcamnet.txt - Main config file for DeepStream app
   config_infer_primary_trafficcamnet.txt - File to configure inference settings
   labels_trafficnet.txt - Label file with 3 classes
   ```

   Key Parameters in `config_infer_primary_trafficcamnet.txt`

   ```sh
   tlt-model-key
   tlt-encoded-model
   labelfile-path
   int8-calib-file
   input-dims
   num-detected-classes
   ```

   Run `deepstream-app`:

   ```sh
   deepstream-app -c deepstream_app_source1_trafficcamnet.txt
   ```

   Documentation to deploy with DeepStream is provided in "Deploying to DeepStream" chapter of [TLT User Guide](https://docs.nvidia.com/TLT/tlt-user-guide/index.html).

### Example <a class="anchor" name="example"></a>

#### Input image

<img src="https://developer.nvidia.com/sites/default/files/akamai/NGC_Images/models/trafficcamnet/000020_input.jpg" width=800>

#### Output image

<img src="https://developer.nvidia.com/sites/default/files/akamai/NGC_Images/models/trafficcamnet/000020_output.jpg" width=800>

### Training Data <a class="anchor" name="training_data"></a>

TrafficCamNet v1.0 model was trained on a proprietary dataset with more than 3 million objects for car class. Most of the training dataset was collected and labeled in-house from several traffic cameras in a city in the US. The dataset also contains 40,000 images from a variety of dashcam to help with generalization and discrimination across classes. This content was chosen to improve accuracy of the object detection for images from a traffic cam at a traffic intersection.

|           |       |   Object  |   Distribution    |           |         |
|----   |----   |----   |----   |----   |----   |
|Environment| Images| Cars| Persons| Road Signs| Two-Wheelers|
|Dashcam (5ft height)|40,000|1.7M|720,000|354,127|54,000|
|Traffic-signal content|160,000|1.1M|53500|184000|11000|
|Total|20,000|2.8M|773,500|538,127|65,000|

TrafficCamNet project labelling guidelines:

- All objects that fall under one of the four classes (car, person two-wheeler, road_sign) in the image and are larger than the smallest bounding-box limit for the corresponding class (height &gt;= 10px OR width &gt;= 10px @1920x1080) are labeled with the appropriate class label.
- Occlusion:  For partially occluded objects that are visible approximately 60% or are marked as visible objects with bounding box around visible part of the object. These objects are marked as partially occluded. Objects under 60% visibility are not annotated.
- Truncation: For an object that is at the edge of the frame with visibility of 60% or more visible are marked with the truncation flag for the object.
- Each frame is not required to have an object.

### Evaluation Data <a class="anchor" name="evalation_data"></a>

The intended use of this model is to detect cars in smart city applications such as traffic pattern analysis, determining anomalous trajectories, etc.  With that in mind the model evaluation is conducted and key performance indicators (KPI) are calculated for car class only. The other classes - road signs, two-wheelers and persons are not factored in the model evaluation.

#### Dataset

The inference performance of TrafficCamNet v1.0 model was measured against 19,000 proprietary images across a variety of environments. The frames are high resolution images 1920x1080 pixels resized to 960x544 pixels before passing to the TrafficcamNet detection model.

#### Methodology and KPI

The true positives, false positives, false negatives are calculated using intersection-over-union (IOU) criterion greater than 0.5.  The KPI for the evaluation data are reported in the table below. Model is evaluated based on precision, recall and accuracy.

The intended use of this model is to detect cars and with that in mind, key performance indicators (KPI) are calculated for car class only. The other classes - road signs, two-wheelers and persons are not factored in the model evaluation.

|Model|     |TrafficcamNet |        |
|-----|----|----|----|
|Content|Precision|Recall|Accuracy|
|TrafficcamNet|92.65|89.95|83.9|

### Real-time Inference Performance <a class="anchor" name="realtime_inference_performance"></a>

The inference is run on the provided pruned model at INT8 precision. On Jetson Nano, FP16 precision is used. The inference performance is run using [`trtexec`](https://github.com/NVIDIA/TensorRT/tree/master/samples/opensource/trtexec) on Jetson Nano, AGX Xavier, Xavier NX and NVIDIA T4 GPU. The Jetson devices are running at Max-N configuration for maximum GPU frequency. The performance shown here is the inference only performance. The end-to-end performance with streaming video data might slightly vary depending on other bottlenecks in the hardware and software.

![alt text](https://developer.nvidia.com/sites/default/files/akamai/NGC_Images/models/trafficcamnet/trafficcamnet_perf.jpg)

### Limitations <a class="anchor" name="limitations"></a>

#### Very Small Objects

NVIDIA TrafficCamNet v1.0 model was trained to detect objects larger than  20x20 pixels.  Therefore it may not be able to detect objects that are smaller than 20x20 pixels.

#### Occluded Objects

When objects are occluded or truncated such that less than 40% of the object is visible, they may not be detected by the TrafficCamNet model.  For car class objects, the model will detect occluded cars as long as 40% of the car is visible.

#### Night-time, Monochrome or Infrared Camera Images

The TrafficCamNet model was trained on RGB images in good lighting conditions.  Therefore, images captured in dark lighting conditions or a monochrome image or IR camera image may not provide good detection results.

#### Warped Images

The TrafficcamNet  model was not trained on fish-eye lense cameras.  Therefore, the model may not perform well for warped images.
Person, Two-wheelers and Road signs
Although persons, two-wheelers and road signs classes are included in the model, the accuracy of these classes will be much lower than car class. Some re-training will be required on these classes to improve accuracy.

#### Location

This model is trained on images from traffic cameras and dash cameras in the US. The accuracy might be lower if run against images from other countries, especially if the country has a very different traffic pattern than the US. For these cases, it is recommended to re-train the unpruned model with TLT with your own dataset.

### Using TLT Pre-trained Models <a class="anchor" name="using_pretrained_models"></a>

- Get [TLT Container](https://ngc.nvidia.com/catalog/containers/nvidia:tlt-streamanalytics)
- Get other Purpose-built models from NGC model registry:
  - [PeopleNet](https://ngc.nvidia.com/catalog/models/nvidia:tlt_peoplenet)
  - [DashCamNet](https://ngc.nvidia.com/catalog/models/nvidia:tlt_dashcamnet)
  - [FaceDetectIR](https://ngc.nvidia.com/catalog/models/nvidia:tlt_facedetectir)
  - [VehicleMakeNet](https://ngc.nvidia.com/catalog/models/nvidia:tlt_vehiclemakenet)
  - [VehicleTypeNet](https://ngc.nvidia.com/catalog/models/nvidia:tlt_vehicletypenet)

### License <a class="anchor" name="license"></a>

License to use this model is covered by the Model EULA. By downloading the unpruned or pruned version of the model, you accept the terms and conditions of these [licenses](https://developer.nvidia.com/tlt-30-models-eula).

### Technical blogs <a class="anchor" name="technical_blogs"></a>

- Read the 2 part blog on training and optimizing 2D body pose estimation model with TLT - [Part 1](https://developer.nvidia.com/blog/training-optimizing-2d-pose-estimation-model-with-tlt-part-1)  |  [Part 2](https://developer.nvidia.com/blog/training-optimizing-2d-pose-estimation-model-with-tlt-part-2)
- Learn how to train [real-time License plate detection and recognition app](https://developer.nvidia.com/blog/creating-a-real-time-license-plate-detection-and-recognition-app) with TLT and DeepStream.
- Model accuracy is extremely important, learn how you can achieve [state of the art accuracy for classification and object detection models](https://developer.nvidia.com/blog/preparing-state-of-the-art-models-for-classification-and-object-detection-with-tlt/) using TLT
- Learn how to train [Instance segmentation model using MaskRCNN with TLT](https://developer.nvidia.com/blog/training-instance-segmentation-models-using-maskrcnn-on-the-transfer-learning-toolkit/)
- Learn how to improve INT8 accuracy using [Quantization aware training(QAT) with TLT](https://developer.nvidia.com/blog/improving-int8-accuracy-using-quantization-aware-training-and-the-transfer-learning-toolkit/)
- Read the technical tutorial on how [PeopleNet model can be trained with custom data using Transfer Learning Toolkit](https://devblogs.nvidia.com/training-custom-pretrained-models-using-tlt/)
- Learn how to [train and deploy real-time intelligent video analytics apps and services using DeepStream SDK](https://devblogs.nvidia.com/building-iva-apps-using-deepstream-5.0/)

### Suggested reading <a class="anchor" name="suggested_reading"></a>

- More information on about Transfer learning toolkit and pre-trained models can be found at the [NVIDIA Developer Zone](https://developer.nvidia.com/transfer-learning-toolkit)
- Read the [TLT getting Started](https://docs.nvidia.com/tlt/tlt-user-guide/text/tlt_quick_start_guide.html) guide and [release notes](https://docs.nvidia.com/tlt/tlt-user-guide/text/release_notes.html).
- If you have any questions or feedback, please refer to the discussions on [TLT Developer Forums](https://devtalk.nvidia.com/default/board/417/transfer-learning-toolkit/)
- Deploy your model on the edge using DeepStream. Learn more about [DeepStream SDK](https://developer.nvidia.com/deepstream-sdk)

### Ethical Considerations <a class="anchor" name="ethical_considerations"></a>

Training and evaluation dataset mostly consists of North American content.  An ideal training and evaluation dataset would additionally include content from other geographies.

NVIDIA’s platforms and application frameworks enable developers to build a wide array of AI applications. Consider potential algorithmic bias when choosing or creating the models being deployed. Work with the model’s developer to ensure that it meets the requirements for the relevant industry and use case; that the necessary instruction and documentation are provided to understand error rates, confidence intervals, and results; and that the model is being used under the conditions and in the manner intended.


tlt_trafficcamnet

4 class object detection network to detect cars in an image.

TrafficCamNet

Description

Publisher

Use Case

Framework

Latest Version

Modified

Size