How to Use YOLO Models for Real-Time Object Detection with ailia-models

The ailia-models repository provides ready-to-run implementations of YOLO families (YOLOv5, YOLOv8, YOLOX, etc.) using the ailia SDK, enabling real-time object detection on images, videos, and webcam streams with automatic model downloading and GPU acceleration.

The axinc-ai/ailia-models repository offers production-ready implementations for real-time object detection using popular YOLO architectures. Whether you need to process static images, video files, or live webcam feeds, these scripts handle the entire pipeline from model downloading to visualization. This guide explains how to use YOLO models for real-time object detection by leveraging the repository's common architecture built on the ailia SDK.

The YOLO Inference Pipeline

All YOLO implementations in the repository follow a standardized nine-step execution flow. The process begins in scripts like object_detection/yolov5/yolov5.py with get_base_parser(), which configures model names, detection thresholds, and input sources.

Model initialization uses check_and_download_models(WEIGHT_PATH, MODEL_PATH, REMOTE_PATH) to fetch ONNX files automatically, followed by ailia.Net(MODEL_PATH, WEIGHT_PATH, env_id=args.env_id) to instantiate the inference engine.

Preprocessing varies by variant: yolov5_utils.letterbox_convert (line 86) handles YOLOv5 resizing, yolox_utils.preproc (line 9) manages YOLOX transformation, and yolov8.preprocess (line 46) prepares YOLOv8 inputs. Inference executes through detector.predict([img]) in YOLOv5 (line 42) or net.predict([img]) in YOLOv8 (line 50).

Post-processing applies variant-specific NMS implementations: yolov5_utils.post_processing (line 86), yolox_utils.predictions_to_object (line 38), or yolov8.post_processing (line 78). These convert raw tensors to ailia.DetectorObject instances containing normalized bounding boxes and class probabilities. Visualization uses plot_results(detect_object, org_img, COCO_CATEGORY) to render outputs. For video streams, recognize_from_video (line 73 in yolov5.py) loops these steps continuously using webcamera_utils.get_capture for frame acquisition.

Real-Time Object Detection with YOLOv5

YOLOv5 implementations support single images, video files, and webcam streams through a unified CLI interface.

Run detection on a static image:

python object_detection/yolov5/yolov5.py \
    -a yolov5s \
    -i input.jpg \
    -o result.png \
    -th 0.3 \
    -iou 0.45

The -a flag selects the architecture (yolov5s, yolov5m, etc.), while -th and -iou control confidence and NMS thresholds. The script automatically downloads yolov5s.onnx from remote storage if absent.

For video processing, the recognize_from_video function (line 73 in yolov5.py) manages the capture loop:

python object_detection/yolov5/yolov5.py \
    -a yolov5s \
    -v input_video.mp4 \
    -o output_video.mp4 \
    -th 0.25 \
    -iou 0.45

This leverages webcamera_utils.get_capture for input and OpenCV's VideoWriter for encoded output.

Webcam Detection Using YOLOX

YOLOX utilizes the ailia Detector API for optimized real-time performance on edge devices. The implementation in object_detection/yolox/yolox.py uses ailia.Detector instead of raw network inference.

import cv2
import ailia
from yolox import yolox
from yolox_utils import preproc, plot_results

# Initialize detector with YOLOX-nano

detector = ailia.Detector(
    'yolox_nano.onnx.prototxt',
    'yolox_nano.onnx',
    len(yolox.COCO_CATEGORY),
    format=ailia.NETWORK_IMAGE_FORMAT_BGR,
    channel=ailia.NETWORK_IMAGE_CHANNEL_FIRST,
    range=ailia.NETWORK_IMAGE_RANGE_U_INT8,
    algorithm=ailia.DETECTOR_ALGORITHM_YOLOX,
)

cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret:
        break
    
    # Pre-process (line 9 in yolox_utils.py)

    img, ratio = preproc(frame, (416, 416))
    
    # Inference

    detector.compute(frame, 0.3, 0.45)
    
    # Visualize (line 54 in yolov5.py/yolox.py)

    result = plot_results(detector, frame, yolox.COCO_CATEGORY)
    cv2.imshow('YOLOX-nano', result)
    
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

Programmatic YOLOv8 Integration

YOLOv8 implementations in object_detection/yolov8/yolov8.py provide flexible model selection with ONNX Runtime fallback support.

import cv2
import ailia
from yolov8 import load_image, preprocess, post_processing, convert_to_detector_object, plot_results

# Load model (downloads automatically if missing)

net = ailia.Net('yolov8n.onnx.prototxt', 'yolov8n.onnx')

# Prepare input

img = load_image('demo.jpg')
img = cv2.cvtColor(img, cv2.COLOR_BGRA2BGR)

# Pre-process (line 46)

input_img = preprocess(img, input_shape=(640, 640))

# Inference (line 50)

output = net.predict([input_img])

# Post-process (line 78)

preds = post_processing(output, conf_thres=0.25, iou_thres=0.45)

# Convert to DetectorObject (line 22)

det_objs = convert_to_detector_object(preds, img.shape[1], img.shape[0])

# Draw and save

out = plot_results(det_objs, img, COCO_CATEGORY)
cv2.imwrite('yolov8_result.png', out)

Key Implementation Files

Understanding the source structure enables custom modifications and debugging:

• object_detection/yolov5/yolov5.py – Main CLI entry point with get_base_parser() and recognize_from_video() (line 73)
• object_detection/yolov5/yolov5_utils.py – letterbox_convert (line 86), post_processing, and NMS implementations
• object_detection/yolox/yolox.py – YOLOX-specific CLI using ailia.Detector API
• object_detection/yolox/yolox_utils.py – preproc (line 9) and predictions_to_object (line 38)
• object_detection/yolov8/yolov8.py – YOLOv8 inference with preprocess (line 46), post_processing (line 78), and convert_to_detector_object (line 22)
• util/detector_utils.py – Shared visualization via plot_results and image loading utilities
• util/webcamera_utils.py – Video capture and VideoWriter management
• util/model_utils.py – Automatic model downloading via check_and_download_models

Summary

• The ailia-models repository provides unified YOLO implementations (v5, v8, X) with consistent preprocessing, inference, and post-processing patterns
• Model initialization uses ailia.Net or ailia.Detector with automatic downloading via check_and_download_models
• Preprocessing varies by variant: letterbox_convert (YOLOv5), preproc (YOLOX), and preprocess (YOLOv8)
• Post-processing includes variant-specific NMS implementations that output standardized ailia.DetectorObject instances
• Real-time processing relies on recognize_from_video functions and webcamera_utils.get_capture for frame-by-frame analysis

Frequently Asked Questions

What YOLO variants are supported in ailia-models?

The repository supports YOLOv5 (s, m, l, x), YOLOv8 (n, s, m, l, x), YOLOX (nano, tiny, s, m, l, x), and YOLOv4. Each variant offers trade-offs between speed and accuracy, with nano and n variants optimized for edge devices and real-time webcam processing.

How does the ailia SDK achieve real-time performance?

The ailia SDK utilizes Vulkan and Metal GPU acceleration on desktop platforms and optimized inference engines for edge devices like Jetson and Raspberry Pi. Single-stage detection architectures in YOLO models perform bounding box regression and classification in one forward pass, enabling processing rates exceeding 30 FPS on modern CPUs and 100+ FPS on GPUs for lightweight variants like YOLOv5-nano or YOLOv8-n.

Can I run these models without GPU acceleration?

Yes. The scripts accept an env_id parameter (set via ailia.Net initialization) that allows CPU-only inference. While frame rates decrease without GPU acceleration, lightweight variants like YOLOX-nano or YOLOv8-n maintain usable performance on modern CPUs for real-time applications.

How do I adjust detection sensitivity and reduce false positives?

Modify the confidence threshold (-th or threshold parameter, typically 0.25-0.5) and NMS IoU threshold (-iou or iou_thres, typically 0.45-0.65) through CLI arguments or function parameters. Higher confidence thresholds filter low-probability detections, while adjusting the IoU threshold controls how aggressively overlapping boxes are suppressed during post-processing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}