5.2 物体検出

サンプルの概要

物体検出サンプルは /app/pydev_demo/02_detection_sample/ にある Python インターフェース の開発コードサンプル群で、hbm_runtime モジュールを使用して物体検出タスクを行う方法を示します。これらのサンプルは、異なる YOLO シリーズのモデルに基づいて同じ物体検出機能を実現しています。含まれるモデルサンプル：

root@ubuntu:/app/pydev_demo/02_detection_sample$ tree -L 1
.
├── 01_ultralytics_yolov5x
├── 02_ultralytics_yolo11
├── 03_ultralytics_yolov8
└── 04_ultralytics_yolo10

実行結果の例

4 つのサンプルの結果は同じで、呼び出すモデルが異なるだけです。ここでは YOLOv5X モデルの結果を示します。その他の YOLO シリーズモデルの結果も同様です。

ハードウェアの準備

ハードウェアの接続

このサンプルは RDK 開発ボード本体のみで動作し、追加の周辺機器の接続は不要です。開発ボードに正常に給電され、システムが起動していることを確認してください。

クイックスタート

コードとボード上の場所

/app/pydev_demo/02_detection_sample/ に移動すると、4 つのサンプルフォルダが含まれていることが確認できます：

root@ubuntu:/app/pydev_demo/02_detection_sample# tree
.
├── 01_ultralytics_yolov5x
│   ├── coco_classes.names
│   ├── kite.jpg
│   ├── ultralytics_yolov5x.py
│   └── result.jpg
├── 02_ultralytics_yolo11
│   ├── coco_classes.names
│   ├── kite.jpg
│   ├── ultralytics_yolo11.py
│   └── result.jpg
├── 03_ultralytics_yolov8
│   ├── coco_classes.names
│   ├── kite.jpg
│   ├── ultralytics_yolov8.py
│   └── result.jpg
└── 04_ultralytics_yolo10
    ├── coco_classes.names
    ├── kite.jpg
    ├── ultralytics_yolo10.py
    └── result.jpg

コンパイルと実行

Python サンプルはコンパイル不要で、そのまま実行できます：

cd /app/pydev_demo/02_detection_sample/01_ultralytics_yolov5x
python ultralytics_yolov5x.py 

cd /app/pydev_demo/02_detection_sample/02_ultralytics_yolo11
python ultralytics_yolo11.py

cd /app/pydev_demo/02_detection_sample/03_ultralytics_yolov8
python ultralytics_yolov8.py

cd /app/pydev_demo/02_detection_sample/04_ultralytics_yolo10
python ultralytics_yolo10.py

実行結果

YOLOv5X の実行結果

root@ubuntu:/app/pydev_demo/02_detection_sample/01_ultralytics_yolov5x# python ultralytics_yolov5x.py 
[BPU_PLAT]BPU Platform Version(1.3.6)!
[HBRT] set log level as 0. version = 3.15.55.0
[DNN] Runtime version = 1.24.5_(3.15.55 HBRT)
[A][DNN][packed_model.cpp:247][Model](2026-01-26,17:07:20.971.89) [HorizonRT] The model builder version = 1.23.5
[W][DNN]bpu_model_info.cpp:491][Version](2026-01-26,17:07:21.81.905) Model: yolov5s_v2_672x672_bayese_nv12. Inconsistency between the hbrt library version 3.15.55.0 and the model build version 3.15.47.0 detected, in order to ensure correct model results, it is recommended to use compilation tools and the BPU SDK from the same OpenExplorer package.

...

检测到 18 个目标: person(0.86), person(0.79), person(0.67), person(0.65), person(0.55), person(0.54), person(0.51), person(0.45), person(0.44), person(0.34), person(0.33), kite(0.88), kite(0.84), kite(0.71), kite(0.70), kite(0.57), kite(0.44), kite(0.31)
[Saved] Result saved to: result.jpg

YOLOv11 の実行結果

root@ubuntu:/app/pydev_demo/02_detection_sample/02_ultralytics_yolo11# python ultralytics_yolo11.py 
[BPU_PLAT]BPU Platform Version(1.3.6)!
[HBRT] set log level as 0. version = 3.15.55.0
[DNN] Runtime version = 1.24.5_(3.15.55 HBRT)
[A][DNN][packed_model.cpp:247][Model](2026-01-26,17:10:52.565.485) [HorizonRT] The model builder version = 1.24.3

...

[Saved] Result saved to: result.jpg

YOLOv8 の実行結果

root@ubuntu:/app/pydev_demo/02_detection_sample/03_ultralytics_yolov8# python ultralytics_yolov8.py 
[BPU_PLAT]BPU Platform Version(1.3.6)!
[HBRT] set log level as 0. version = 3.15.55.0
[DNN] Runtime version = 1.24.5_(3.15.55 HBRT)
[A][DNN][packed_model.cpp:247][Model](2026-01-26,17:12:13.322.476) [HorizonRT] The model builder version = 1.24.3

...

检测到 13 个目标: person(0.88), person(0.87), person(0.72), person(0.50), person(0.45), person(0.34), person(0.30), kite(0.90), kite(0.84), kite(0.76), kite(0.71), kite(0.62), kite(0.61)
[Saved] Result saved to: result.jpg

YOLOv10 の実行結果

root@ubuntu:~/app/pydev_demo/02_detection_sample/04_ultralytics_yolo10# python ultralytics_yolo10.py 
[BPU_PLAT]BPU Platform Version(1.3.6)!
[HBRT] set log level as 0. version = 3.15.55.0
[DNN] Runtime version = 1.24.5_(3.15.55 HBRT)
[A][DNN][packed_model.cpp:247][Model](2026-01-26,17:13:38.644.334) [HorizonRT] The model builder version = 1.24.3

...

检测到 14 个目标: kite(0.91), kite(0.81), kite(0.51), kite(0.39), kite(0.78), kite(0.41), kite(0.80), person(0.27), person(0.58), person(0.60), person(0.76), person(0.26), person(0.91), person(0.90)
[Saved] Result saved to: result.jpg

詳細説明

サンプルプログラムのパラメータオプションの説明

物体検出サンプルはコマンドライン引数による設定に対応しています。4 つのサンプルのパラメータはほぼ同じですが、各サンプルのデフォルトモデルパスは異なります。パラメータを指定しない場合、プログラムはデフォルト値を使用して同じディレクトリ内のテスト画像を自動的に読み込み、推論を行います。

各サンプルのデフォルトモデルパス：

ソフトウェアアーキテクチャの説明

ここでは、物体検出サンプルのソフトウェアアーキテクチャと処理の流れを紹介し、モデルの読み込みから結果出力までの一連の実行過程を説明して、コードの全体構造とデータの流れを理解できるようにします。4 つのサンプルのアーキテクチャは同じため、ここではソフトウェアアーキテクチャ図を 1 つだけ示します。

1. モデルの読み込み - hbm_runtime モジュールを使用してプリコンパイル済みのモデルファイルを読み込む
2. 画像の読み込み - 入力テスト画像を読み込む
3. 画像の前処理 - 入力画像をモデルの入力サイズにスケーリングし、BGR を NV12 形式に変換
4. モデル推論 - BPU 上でモデルの順伝播計算を実行
5. 結果の後処理 - post_utils ライブラリを使用して推論結果を解析し、デコード、信頼度フィルタリング、NMS（非最大値抑制）を実行
6. 結果の出力 - 画像上に検出枠を描画し、結果画像を保存

API フローの説明

ここでは、サンプルプログラムで使用している主な API インターフェースを列挙し、各インターフェースの機能、入力パラメータ、戻り値を説明して、開発者がコードの実装詳細とインターフェースの呼び出し方法をすばやく理解できるようにします。4 つのサンプルの呼び出しインターフェースはほぼ同じため、ここでは API フローの説明図を 1 つだけ示します

1. hbm_runtime.HB_HBMRuntime(model_path)

プリコンパイル済みモデルを読み込みます。入力：モデルファイルのパス

1. load_image(image_path)

テスト画像を読み込みます。入力：画像ファイルのパス

1. resized_image(img, input_W, input_H, resize_type)

画像をスケーリングします。入力：画像、目標の幅、目標の高さ、スケーリングの種類、戻り値：スケーリング後の画像

1. bgr_to_nv12_planes(image)

BGR を NV12 形式に変換します。入力：BGR 画像、戻り値：y プレーン、uv プレーン

1. model.run(input_data)

モデル推論を実行します。入力：前処理済みの画像データ、戻り値：モデル出力

1. dequantize_outputs(outputs, output_quants)

結果を逆量子化します。入力：モデル出力、指定の型、戻り値：逆量子化後の結果

1. decode_outputs(output_names, fp32_outputs, STRIDES, ANCHORS, classes_num)

モデル出力をデコードします。入力：出力名のリスト、モデル出力、ストライド、アンカーボックス、クラス数、戻り値：予測結果

1. filter_predictions(pred, score_thres)

予測結果をフィルタリングします。入力：予測結果、信頼度しきい値、戻り値：検出枠、信頼度、クラス

1. NMS(detections, iou_threshold)

非最大値抑制を行います。入力：検出枠、信頼度、クラス、IoU しきい値、戻り値：保持するインデックス

1. scale_coords_back(boxes, img_w, img_h, input_W, input_H, resize_type)

検出枠を元画像のサイズに調整します。入力：検出枠、元画像のサイズ、モデルの入力サイズ、補間方法、戻り値：スケーリング後の検出枠

1. draw_boxes(image, detections, class_names)

検出結果を描画します。入力：画像、検出枠、クラス ID、信頼度、クラスリスト、カラーマップ

FAQ

https://developer.d-robotics.cc/rdk_doc/Basic_Application/pydev_demo_sample/RDK_X5/detection_sample#faq