Ultralytics YOLO-OBB on NVIDIA DeepStream 9.0

Run Ultralytics YOLO Oriented Bounding Box (OBB) detection — YOLOv8-OBB and YOLO11-OBB — on NVIDIA DeepStream 9.0, end to end. DeepStream 9.0 already ships the OBB parser, and nvdsosd draws the rotated boxes for you. You bring an ONNX model + a config, and you get rotated detection boxes on video.

Clean multi-class detection on real DOTA imagery (tennis courts, swimming pool, vehicles shown). Each box is oriented (rotated to the object's heading), not axis-aligned. The demo runs on 5 real DOTA tiles spanning ships, planes, vehicles, courts, harbors, and pool.

---

How it works

Pipeline

┌─────────────────────────────────────────┐
│           Input (file / RTSP)           │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│              nvstreammux                │
│        Batches decoded frames           │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│                nvinfer                  │
│   YOLO-OBB ONNX → TensorRT (FP16)       │
│                                         │
│  NvDsInferParseCustomYoloV11OBB:        │
│   • Decodes output tensor [1, 20, N]    │
│   • Applies confidence filter + NMS     │
│   • Sets bbox + rotation_angle (rad)    │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│               nvtiler                   │
│   Tiles streams into one canvas         │
│   (single stream in this config)        │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│               nvdsosd                   │
│  Draws oriented (rotated) boxes+labels  │
│  rotation_angle → NvOSD_RectParams      │
└──────────────────┬──────────────────────┘
                   │
          ┌────────┴────────┐
          ▼                 ▼
┌──────────────────┐  ┌──────────────────┐
│  [sink0] File    │  │  [sink1] Display │
│  H.264 MP4/NVENC │  │  Live X11 window │
│  out_obb.mp4     │  │  (optional)      │
│  (default)       │  │                  │
└──────────────────┘  └──────────────────┘

OBB CustomParser and Rendering

DeepStream 9.0 ships two things that make this entirely config-driven:

1. Prebuilt OBB parser — NvDsInferParseCustomYoloV11OBB is compiled into libnvds_infercustomparser.so inside the container. Despite the name, this parser handles both YOLOv8-OBB and YOLO11-OBB output format. The pgie config points at it with parse-bbox-func-name and custom-lib-path; no source code or build step required.

2. Automatic OBB rendering — gstnvinfer copies the parser’s per-object rotation_angle (radians) into NvOSD_RectParams.rotation_angle (degrees), and nvdsosd renders the rotated rectangle natively. No application code is needed.

---

Repository layout

Deepstream-OBB/
├── README.md
├── configs/
│   ├── config_deepstream_app.txt      # the deepstream-app pipeline
│   ├── config_pgie_yolo_obb.txt       # the nvinfer (primary GIE) config
│   └── labels_dota.txt                # 15 DOTA class names
├── assets/                 # sample annotated frames (committed, for the README)
├── data/                   # input videos (tracked; update [source0] uri to point at your file)
├── models/                 # ONNX + TensorRT engine (gitignored; generated on first run)
└── output/                 # annotated mp4 results (gitignored)

---

Prerequisites

DeepStream 9.0 requirements (source)

• Ubuntu 24.04
• NVIDIA driver 590.48.01
• CUDA 13.1
• TensorRT 10.14.1.48
• GStreamer 1.24.2

This project uses the Docker image (nvcr.io/nvidia/deepstream:9.0-samples-multiarch) which bundles all of the above — only the host driver needs to meet the minimum version.

Host requirements

• NVIDIA GPU
• NVIDIA driver ≥ 590.48.01
• Docker + NVIDIA Container Toolkit (--gpus all must work):

  docker run --rm --gpus all nvcr.io/nvidia/deepstream:9.0-samples-multiarch nvidia-smi

• For model export on the host: python3 with pip install ultralytics.

What is NOT in this repo (gitignored — generate locally per the steps below):

• models/ — ONNX and TensorRT engine files
• output/ — pipeline results

---

Quick start

From the repo root:

# 1) (once) pull the DeepStream image
docker pull nvcr.io/nvidia/deepstream:9.0-samples-multiarch

# 2) export a YOLO-OBB model to ONNX  -> models/<model>.onnx
pip install ultralytics
mkdir -p models && cd models
# YOLOv8 (pick one):
python3 -c "from ultralytics import YOLO; YOLO('yolov8n-obb.pt').export(format='onnx', imgsz=1024, opset=20)"
# or YOLO11:
# python3 -c "from ultralytics import YOLO; YOLO('yolo11n-obb.pt').export(format='onnx', imgsz=1024, opset=20)"
cd ..
mkdir -p output
# Then update onnx-file and model-engine-file in configs/config_pgie_yolo_obb.txt

# 3) run the pipeline  -> output/out_obb.mp4
#    (first run builds the TensorRT engine: a few minutes; cached afterwards)
docker run --rm --gpus all \
  -v "$PWD":/workspace -w /workspace/configs \
  -e LD_LIBRARY_PATH=/opt/nvidia/deepstream/deepstream/lib \
  nvcr.io/nvidia/deepstream:9.0-samples-multiarch \
  deepstream-app -c config_deepstream_app.txt

Open output/out_obb.mp4 — a slideshow of 5 real DOTA tiles with clean oriented boxes per scene (ships + harbors, planes, tennis & basketball courts, small/large vehicles, swimming pool).

To run on your own footage, drop a file in data/ and point configs/config_deepstream_app.txt → [source0] uri at it.

---

Step by step

1. Pull the DeepStream image (once)

docker pull nvcr.io/nvidia/deepstream:9.0-samples-multiarch

Verify GPU access works:

docker run --rm --gpus all nvcr.io/nvidia/deepstream:9.0-samples-multiarch nvidia-smi

2. Export the model

Export a YOLO-OBB model to ONNX on the host. Both YOLOv8-OBB and YOLO11-OBB are supported:

pip install ultralytics
mkdir -p models && cd models

# Option A — YOLOv8-OBB (nano; replace with yolov8s/m/l/x-obb for larger variants)
python3 -c "from ultralytics import YOLO; YOLO('yolov8n-obb.pt').export(format='onnx', imgsz=1024, opset=20)"

# Option B — YOLO11-OBB (nano; replace with yolo11s/m/l/x-obb for larger variants)
# python3 -c "from ultralytics import YOLO; YOLO('yolo11n-obb.pt').export(format='onnx', imgsz=1024, opset=20)"

cd ..
mkdir -p output

Then update onnx-file and model-engine-file in configs/config_pgie_yolo_obb.txt to match the exported filename.

3. Run

Place your input video in data/ and update [source0] uri in configs/config_deepstream_app.txt to point at it (e.g. file:///workspace/data/your_video.mp4). Also set [streammux] width/height to your video's resolution, then run from the repo root:

docker run --rm --gpus all \
  -v "$PWD":/workspace -w /workspace/configs \
  -e LD_LIBRARY_PATH=/opt/nvidia/deepstream/deepstream/lib \
  nvcr.io/nvidia/deepstream:9.0-samples-multiarch \
  deepstream-app -c config_deepstream_app.txt

The TensorRT engine is written into models/ (mounted), so it is reused on subsequent runs. Output is saved to output/out_obb.mp4.

---

Configuration reference

Key settings in configs/config_pgie_yolo_obb.txt:

Property	Value	Why
net-scale-factor	0.0039215697	1/255 — YOLO expects 0–1 RGB input
model-color-format	0	RGB
num-detected-classes	15	DOTAv1 classes
network-mode	2	FP16 (use 0 for FP32)
maintain-aspect-ratio	0	frame is stretched to fill the network input
cluster-mode	4	No clustering — the parser does its own NMS and sets the angle; DeepStream clustering would drop it
parse-bbox-func-name	NvDsInferParseCustomYoloV11OBB	the prebuilt OBB parser (works for both YOLOv8-OBB and YOLO11-OBB)
custom-lib-path	…/libnvds_infercustomparser.so	where that parser lives in the image
[class-attrs-all] pre-cluster-threshold	0.25	global confidence threshold (see note below)

Pipeline / I/O is in configs/config_deepstream_app.txt — source, streammux resolution, OSD, and the file/EGL sink.

---

Use your own input video

Edit configs/config_deepstream_app.txt:

[source0]
uri=file:///workspace/data/your_video.mp4     # put the file in ./data
# or an RTSP camera:
# type=4
# uri=rtsp://user:pass@host:554/stream

[streammux]
width=1920      # set to your video's resolution for best box alignment
height=1080

Put the file in ./data/ (mounted to /workspace/data), then run the docker run command above.

The model is DOTA = aerial / top-down. It detects well on nadir scenes (marinas, ports, parking lots, airports from above) and finds little on street-level or strongly oblique footage. That is the domain, not a bug.

Switching models

The same config and parser work for any Ultralytics YOLO-OBB model. To switch:

1. Export the model to ONNX:

   cd models
   # YOLOv8 variants:
   python3 -c "from ultralytics import YOLO; YOLO('yolov8s-obb.pt').export(format='onnx', imgsz=1024, opset=20)"
   # YOLO11 variants:
   # python3 -c "from ultralytics import YOLO; YOLO('yolo11s-obb.pt').export(format='onnx', imgsz=1024, opset=20)"
   # Available sizes: n / s / m / l / x

2. Update configs/config_pgie_yolo_obb.txt:

   onnx-file=/workspace/models/yolov8s-obb.onnx
   model-engine-file=/workspace/models/yolov8s-obb.onnx_b1_gpu0_fp16.engine
   num-detected-classes=15   # adjust if using a non-DOTA model

3. If using custom classes, replace configs/labels_dota.txt with your own labels (one per line) and set num-detected-classes accordingly. The parser is generic: num_classes = channels − 5.

---

Interactive shell in the container (for debugging)

To poke around inside the container (run gst-inspect-1.0, deepstream-app --help, etc.):

docker run --gpus all -it --rm \
  -v "$PWD":/workspace -w /workspace \
  -e LD_LIBRARY_PATH=/opt/nvidia/deepstream/deepstream/lib \
  nvcr.io/nvidia/deepstream:9.0-samples-multiarch bash

Live display instead of a file (optional)

By default [sink0] (file sink) is active and [sink1] (display) is disabled. To enable live display:

1. Open configs/config_deepstream_app.txt and set enable=1 under [sink1] (and optionally enable=0 under [sink0] to suppress the file output).
2. Pass the X server and DRI device into the container:

xhost +local:root
docker run --rm --gpus all \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  --device /dev/dri \
  -v "$PWD":/workspace -w /workspace/configs \
  -e LD_LIBRARY_PATH=/opt/nvidia/deepstream/deepstream/lib \
  nvcr.io/nvidia/deepstream:9.0-samples-multiarch \
  deepstream-app -c config_deepstream_app.txt

---

License

The files in this repository (configs, documentation) are released under the MIT License — see LICENSE.

This project depends on third-party components with separate licenses — see NOTICE for full details:

Component	License	Notes
NVIDIA DeepStream SDK 9.0	NVIDIA Proprietary	Runs inside the Docker container; not distributed here
Ultralytics YOLO-OBB weights	AGPL-3.0	Commercial license available from Ultralytics; ONNX/engine is gitignored
DOTA dataset (demo imagery)	DOTA Academic License	assets/ images derived from DOTA tiles; academic use only

Commercial use: if you deploy YOLO-OBB weights (YOLOv8-OBB or YOLO11-OBB, or a derived ONNX/TensorRT engine) in a commercial product, you must obtain a commercial license from Ultralytics. The configs and documentation in this repo are MIT and have no such restriction.

References

• DeepStream SDK docs — https://docs.nvidia.com/metropolis/deepstream/dev-guide/
• Ultralytics YOLO-OBB — https://docs.ultralytics.com/tasks/obb/
• DOTA dataset — https://captain-whu.github.io/DOTA/