README.md

---
language:
- vi
license: agpl-3.0
library_name: ultralytics
pipeline_tag: object-detection
tags:
- yolo
- yolov8
- onnx
- torchscript
- tensorrt
- int8
- fp16
- vision
- object-detection
- traffic-sign
- vietnam
---

**Documentation languages**

- 🇺🇸 English: README.md
- 🇻🇳 Tiếng Việt: README.vi.md

# VTSR

VTSR is a YOLOv8n object-detection model for recognizing 56 classes of Vietnamese traffic signs.

This repository focuses on optimized deployment artifacts derived from the original FP32 PyTorch checkpoint, including ONNX INT8, TensorRT INT8, and TorchScript FP16 models.

## Demo

An interactive Gradio demo is available on Hugging Face Spaces:

https://huggingface.co/spaces/liamxdev/vtsr

The demo currently uses the ONNX INT8 artifact for CPU-compatible inference.

## Model details

| Property           | Value                           |
| ------------------ | ------------------------------- |
| Task               | Object detection                |
| Architecture       | YOLOv8n                         |
| Classes            | 56                              |
| Input size         | 640 × 640                       |
| Label descriptions | `label-mapping.json`            |
| Dataset            | Vietnam Traffic Sign Dataset v3 |
| License            | AGPL-3.0                        |

The model returns traffic-sign codes such as `P-102`, `R-303`, and `W-224`. Vietnamese descriptions for these codes are provided separately in `label-mapping.json`.

## Artifacts

| File                    | Precision | Target platform                              |
| ----------------------- | --------- | -------------------------------------------- |
| `vtsr.pt`               | FP32      | PyTorch                                      |
| `vtsr_int8.onnx`        | INT8      | ONNX Runtime, CPU, cross-platform deployment |
| `vtsr.torchscript`      | FP16      | TorchScript runtimes                         |
| `vtsr.engine`           | INT8      | NVIDIA TensorRT and Jetson devices           |
| `label-mapping.json`    | —         | Traffic-sign code descriptions               |

> The original FP32 PyTorch checkpoint is intentionally omitted. This repository provides optimized deployment artifacts only.

## Usage

Install dependencies:

```bash
pip install ultralytics
```

Run inference:

```python
from ultralytics import YOLO

# Supported artifacts:
# vtsr.pt
# vtsr_int8.onnx
# vtsr.torchscript
# vtsr.engine

model = YOLO("vtsr_int8.onnx")

results = model.predict(
    source="traffic.jpg",
    imgsz=640,
    conf=0.25,
)

results[0].save("result.jpg")
```

See `label-mapping.json` for Vietnamese descriptions of traffic-sign codes.

## Download from Hugging Face Hub

```python
from huggingface_hub import hf_hub_download

repo_id = "liamxdev/vtsr"

model_path = hf_hub_download(
    repo_id=repo_id,
    filename="vtsr_int8.onnx",
)

mapping_path = hf_hub_download(
    repo_id=repo_id,
    filename="label-mapping.json",
)
```

Other artifacts can be downloaded in the same way:

* `vtsr.pt`
* `vtsr.torchscript`
* `vtsr.engine`

## Benchmark

See [benchmark.md](benchmark.md) for latency and throughput measurements.

## Supported classes

The model covers 56 Vietnamese traffic-sign codes in four broad groups:

* `P-*`: prohibition signs.
* `R-*`: mandatory and instruction signs.
* `W-*`: warning signs.
* `S-*` and `DP-*`: supplementary or special signs represented in the training dataset.

See `label-mapping.json` for the complete list and Vietnamese meanings.

## Training data

The model was trained using version 3 of the [Vietnam Traffic Sign Dataset](https://universe.roboflow.com/giang-yp9g1/vietnam-traffic-sign-altsi/dataset/3) published on Roboflow Universe. The dataset metadata declares a CC BY 4.0 license.

## Intended use

* Educational and research projects.
* Traffic-scene analysis prototypes.
* Vietnamese traffic-sign detection demos.
* CPU-oriented deployment through ONNX Runtime.
* NVIDIA GPU and Jetson deployment through TensorRT.
* Lightweight deployment through TorchScript.

## Limitations

* The model recognizes only the 56 classes listed in `label-mapping.json`.
* Detection quality can decrease with small, blurred, occluded, damaged, poorly lit, or unusually angled signs.
* Images outside the training distribution may produce missed detections or false positives.
* A detection is not a substitute for official road-sign interpretation or safety-critical driving decisions.
* Quantized and reduced-precision models may exhibit accuracy differences relative to the original PyTorch checkpoint.
* TensorRT engines are hardware-specific and may need to be regenerated for different GPU architectures.

## License

The exported model contains Ultralytics YOLO components and is distributed under the AGPL-3.0 license. Dataset attribution and its CC BY 4.0 terms apply separately.

For commercial licensing of Ultralytics components, see https://www.ultralytics.com/license.

## Citation

```bibtex
@misc{vietnam_traffic_sign_altsi_dataset,
  title        = {Vietnam Traffic Sign Dataset},
  author       = {giang},
  year         = {2024},
  publisher    = {Roboflow Universe},
  howpublished = {\url{https://universe.roboflow.com/giang-yp9g1/vietnam-traffic-sign-altsi}}
}
```