YOLOs-CPP

Production-Ready YOLO Inference Engine for C++

A blazing-fast, unified C++ inference library for the entire YOLO family

Quick Start · Features · Models · API · Benchmarks · Docs

📰 Latest News

• [2026.08.23] Released ros2_yolos_trt, a ROS 2 TensorRT inference package achieving sub-2 ms inference latency.
• [2026.08.02] Released v1.1.0 with depth estimation, batch inference, in-memory model loading, and Ultralytics parity improvements. See the release notes.
• [2026.08.02] Added monocular metric depth estimation for YOLO26 via yolos::depth::YOLODepthEstimator and the image_depth_inference example.
• [2026.08.02] Added batch inference with batchDetect, batchSegment, and batchClassify, plus in-memory model loading across all supported tasks.
• [2026.04.11] Added YOLOE open-vocabulary detection and segmentation in C++. See the Model Guide and the image_yoloe_seg / video_yoloe_seg examples.
• [2026.01.22] Released YOLOs-CPP-TensorRT, achieving 530+ FPS on NVIDIA GPUs and Jetson platforms.
• [2026.01.22] Released motcpp, a C++ implementation of popular multi-object tracking (MOT) algorithms.
• [2026.01.22] Released the ros2_yolos_cpp ROS 2 integration package.
• [2026.01.18] Released production-ready v1.0.0. Watch the demo.
• [2025.05.15] Added image classification support.
• [2025.04.04] Released Depths-CPP, a new project for real-time metric depth estimation.
• [2025.03.16] Added pose estimation support.
• [2025.02.19] Added YOLOv12 object detection support.
• [2025.02.11] Added oriented bounding box (OBB) support.
• [2025.01.29] Added YOLOv9 object detection support.
• [2025.01.26] Added YOLOv9 segmentation support.
• [2025.01.26] Added segmentation support for YOLOv8 and YOLO11, including quantized models.
• [2024.10.23] Released v0.0.1, the initial YOLOs-CPP release with object detection support.

Why YOLOs-CPP?

YOLOs-CPP is a production-grade inference engine that brings the entire YOLO ecosystem to C++. Unlike scattered implementations, YOLOs-CPP provides a unified, consistent API across all YOLO versions and tasks.

#include "yolos/yolos.hpp"

// One API for all YOLO versions and tasks
auto detector = yolos::det::YOLODetector("yolo11n.onnx", "coco.names");
auto detections = detector.detect(frame);

The Problem

• Fragmented ecosystem: Each YOLO version has different C++ implementations
• Inconsistent APIs: Different interfaces for detection, segmentation, pose
• Production gaps: Most implementations lack proper error handling, testing, and optimization

The Solution

YOLOs-CPP unifies everything under one roof:

🎬 Demo

Instance Segmentation	Pose Estimation
Real-time Detection	Multi-Object Detection

⚡ Quick Start

Prerequisites

Installation

# Clone
git clone https://github.com/Geekgineer/YOLOs-CPP.git
cd YOLOs-CPP

# Build (auto-downloads ONNX Runtime)
./build.sh 1.20.1 0   # CPU build
./build.sh 1.20.1 1   # GPU build (requires CUDA)

# Run
./build/image_inference models/yolo11n.onnx data/dog.jpg

# Download ONNX Runtime
wget https://github.com/microsoft/onnxruntime/releases/download/v1.20.1/onnxruntime-linux-x64-1.20.1.tgz
tar -xzf onnxruntime-linux-x64-1.20.1.tgz

# Configure and build
mkdir build && cd build
cmake .. -DONNXRUNTIME_DIR=../onnxruntime-linux-x64-1.20.1 -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

# CPU
docker build -f Dockerfile.cpu -t yolos-cpp:cpu .
docker run --rm -it yolos-cpp:cpu

# GPU (requires nvidia-docker)
docker build -t yolos-cpp:gpu .
docker run --gpus all --rm -it yolos-cpp:gpu

🎯 Features

Supported Models

Open-vocabulary YOLOE uses ONNX exported after set_classes() (text) or prompt-free *-pf checkpoints; see the guide for how that differs from interactive Python prompts. Export with scripts/export_yoloe_onnx.py, then run ./build/image_yoloe_seg or ./build/video_yoloe_seg, or the benchmarks yoloe-seg task.

Depth estimation is YOLO26-only (yolo26{n,s,m,l,x}-depth). See Depth Estimation.

Core Capabilities

• 🚀 High Performance: Zero-copy preprocessing, optimized NMS, GPU acceleration
• 🎯 Precision Matched: Identical results to Ultralytics Python (validated by 50 parity tests)
• 📦 Self-Contained: No Python runtime, no external dependencies at runtime
• 🔌 Easy Integration: Header-based library, modern C++17 API
• ⚙️ Flexible: CPU/GPU, dynamic/static input shapes, configurable thresholds
• 📚 Batch Inference: Multiple images per ONNX Runtime call, with automatic per-image fallback for fixed-batch exports
• 🔐 In-Memory Models: Load ONNX bytes directly — no file on disk required
• 📐 Metric Depth: YOLO26 monocular depth estimation returning per-pixel meters
• ⬜ Grayscale Inputs: Single-channel models are detected from the input tensor and preprocessed accordingly

📖 API Reference

Object Detection

#include "yolos/yolos.hpp"

// Initialize
yolos::det::YOLODetector detector("model.onnx", "coco.names", /*gpu=*/true);

// Detect
cv::Mat frame = cv::imread("image.jpg");
auto detections = detector.detect(frame, /*conf=*/0.25f, /*iou=*/0.45f);

// Process results
for (const auto& det : detections) {
    std::cout << "Class: " << det.className 
              << " Conf: " << det.confidence 
              << " Box: " << det.box << std::endl;
}

// Visualize
detector.drawDetections(frame, detections);

Instance Segmentation

yolos::seg::YOLOSegDetector detector("yolo11n-seg.onnx", "coco.names", true);
auto segments = detector.segment(frame);
detector.drawSegmentations(frame, segments, /*maskAlpha=*/0.5f);

Pose Estimation

yolos::pose::YOLOPoseDetector detector("yolo11n-pose.onnx", "", true);
auto poses = detector.detect(frame);
detector.drawPoses(frame, poses);

Oriented Bounding Boxes (OBB)

yolos::obb::YOLOOBBDetector detector("yolo11n-obb.onnx", "dota.names", true);
auto boxes = detector.detect(frame);
detector.drawOBBs(frame, boxes);

Image Classification

yolos::cls::YOLOClassifier classifier("yolo11n-cls.onnx", "imagenet.names", true);
auto result = classifier.classify(frame);
std::cout << "Predicted: " << result.className << " (" << result.confidence * 100 << "%)" << std::endl;

Batch Inference

One ONNX Runtime call for many images — the throughput win on GPU. Requires a model exported with dynamic=True; fixed-batch exports fall back to a per-image loop automatically, so the call works either way. See Batch Inference.

std::vector<cv::Mat> images = {cv::imread("a.jpg"), cv::imread("b.jpg"), cv::imread("c.jpg")};

yolos::det::YOLODetector detector("yolo11n.onnx", "coco.names", /*gpu=*/true);

// One result vector per input image, in input order
auto results = detector.batchDetect(images, /*conf=*/0.25f, /*iou=*/0.45f);

// Also: batchSegment(), batchClassify(), and batchDetect() for pose and OBB

./build/batch_image_inference models/yolo11n.onnx data/ models/coco.names

In-Memory Model Loading

For encrypted stores, network streams and resources embedded in the binary — the model never needs to exist as a file. See In-Memory Model Loading.

// Bytes from anywhere: decryption, download, embedded array
std::vector<uint8_t> bytes = yolos::utils::readFileBytes("yolo11n.onnx");

// Class names come in as a vector, so no labels file is needed either
yolos::det::YOLODetector detector(bytes.data(), bytes.size(), {"person", "bicycle", "car"});

// ONNX Runtime copied the buffer during construction — safe to wipe it now
auto detections = detector.detect(frame);

Depth Estimation

yolos::depth::YOLODepthEstimator estimator("yolo26n-depth.onnx", true);
cv::Mat depth = estimator.estimate(frame);          // CV_32FC1, meters
std::cout << depth.at<float>(y, x) << " m" << std::endl;
estimator.drawDepth(frame, depth);

./build/image_depth_inference models/yolo26n-depth.onnx data/dog.jpg

Unlike the tasks above, depth takes no labels file and no confidence/IoU thresholds — the model outputs a single dense per-pixel map, not classes to filter. See Depth Estimation for the units and colormap options.

YOLOE (open-vocabulary segmentation)

See Model Guide — YOLOE for export and benchmarks.

#include "yolos/tasks/yoloe.hpp"
yolos::yoloe::YOLOESegDetector det("models/yoloe-26s-seg-text.onnx",
    {"person", "car", "bus", "bicycle", "motorcycle", "truck"}, /*gpu=*/true);
auto segs = det.segment(frame);
det.drawSegmentations(frame, segs);

# Image → image (JPEG/PNG …)
./build/image_yoloe_seg data/photo.jpg out.jpg models/yoloe-26n-seg.onnx "person,car,bus" 0

# Video → MP4
./build/video_yoloe_seg data/Transmission.mp4 out.mp4 models/yoloe-26n-seg.onnx "person,car,bus" 1

📊 Benchmarks

Tested on Intel i7-12700H (CPU) / NVIDIA RTX 3060 (GPU), 640×640 input:

cd benchmarks
./auto_bench.sh 1.20.1 0 yolo11n,yolov8n,yolo26n

🏗️ Architecture

YOLOs-CPP/
├── include/yolos/           # Core library
│   ├── core/                # Shared utilities
│   │   ├── types.hpp        # Detection, Segmentation result types
│   │   ├── preprocessing.hpp # Letterbox, normalization
│   │   ├── nms.hpp          # Non-maximum suppression
│   │   ├── drawing.hpp      # Visualization utilities
│   │   └── version.hpp      # YOLO version detection
│   ├── tasks/               # Task implementations
│   │   ├── detection.hpp    # Object detection
│   │   ├── segmentation.hpp # Instance segmentation
│   │   ├── pose.hpp         # Pose estimation
│   │   ├── obb.hpp          # Oriented bounding boxes
│   │   ├── classification.hpp
│   │   ├── depth.hpp        # Monocular metric depth (YOLO26)
│   │   └── yoloe.hpp        # YOLOE open-vocabulary (det/seg)
│   └── yolos.hpp            # Main include (includes all)
├── src/                     # Example applications
├── examples/                # Task-specific examples
├── tests/                   # Automated test suite
├── benchmarks/              # Performance benchmarking
└── models/                  # Sample models & labels

📚 Documentation

🧪 Testing

YOLOs-CPP includes a comprehensive test suite that validates C++ inference against Ultralytics Python:

cd tests
./test_all.sh        # Run all suites
./test_detection.sh  # Run detection only

Two kinds of test run in every suite. Parity tests compare C++ output against a fresh Ultralytics Python run on the same weights and images. Self-contained tests assert library behaviour directly against synthetic ONNX models or fixed reference values — no downloaded weights and no Ultralytics reference run. 27 of the 57 need nothing but the compiler; the other 30 use Python only to generate a synthetic model.

Each suite runs as its own CI job across the eight tasks above.

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

# Fork, clone, branch
git checkout -b feature/amazing-feature

# Make changes, test
./tests/test_all.sh

# Commit and PR
git commit -m "feat: add amazing feature"
git push origin feature/amazing-feature

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for details.

For commercial licensing options, please contact the maintainers.

🙏 Acknowledgments

YOLOs-CPP builds on the shoulders of giants:

• Ultralytics — YOLO models and training
• ONNX Runtime — High-performance inference
• OpenCV — Computer vision primitives

⭐ If YOLOs-CPP helps your project, consider giving it a star!

Made with ❤️ by the YOLOs-CPP Team