HumansXドキュメントセンター
公式サイトへ ↗
ドキュメントセンター › GX-MAT-09S

1.1 USB カメラによるリアルタイム検出

サンプルの概要

USB カメラによるリアルタイム検出のサンプルは /app/pydev_demo/07_usb_camera_sample/ にあり、Python インターフェースによるリアルタイム物体検出の例を提供します。hbm_runtime と YOLOv5X モデルを組み合わせて USB カメラの映像に対して推論を行い、検出結果をウィンドウにリアルタイムで表示する方法を示します。

含まれるモデルの例：

root@ubuntu:/app/pydev_demo/07_usb_camera_sample$ tree -L 1
.
├── coco_classes.names
└── usb_camera_yolov5x.py

実行結果の例

注意：本サンプルは検出結果を表示するウィンドウを開くため、GUI のある環境で実行する必要があります。Server 版のイメージの場合は、MobaXterm など X11 転送に対応したリモートツールで開発ボードに接続することを推奨します。これにより、ローカル PC 上で表示ウィンドウを確認できます。

USB カメラの映像をリアルタイムで読み取り、映像内の物体を検出して、検出枠、クラス、信頼度をウィンドウにリアルタイムで重ねて表示します。

ハードウェアの準備

ハードウェア接続

  • RDK 開発ボード 1 式
  • USB カメラ 1 台（開発ボードの USB ポートに接続）
  • 電源ケーブルと LAN ケーブルを接続

クイックスタート

コードとボード上の場所

/app/pydev_demo/07_usb_camera_sample/ に移動すると、サンプルファイルを確認できます。

root@ubuntu:/app/pydev_demo/07_usb_camera_sample# tree
.
├── coco_classes.names
└── usb_camera_yolov5x.py

コンパイルと実行

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

cd /app/pydev_demo/07_usb_camera_sample
python usb_camera_yolov5x.py

q キーで終了します（マウスのフォーカスを表示ウィンドウに合わせる必要があります）。

実行結果

実行すると、プログラムが利用可能な USB カメラデバイスを自動的に検索し、リアルタイムの物体検出を開始します。検出結果はウィンドウに表示されます。マウスのフォーカスを表示ウィンドウに合わせて q を押すと、プログラム全体が終了します。

root@ubuntu:/app/pydev_demo/07_usb_camera_sample# python usb_camera_yolov5x.py
Opening video device: /dev/video0
Open USB camera successfully
[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-20,19:02:15.744.442) [HorizonRT] The model builder version = 1.23.5
[W][DNN]bpu_model_info.cpp:491][Version](2026-01-20,19:02:15.859.240) 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.

...

Place the mouse in the display window and press 'q' to quit

詳細説明

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

パラメータ 説明 型 デフォルト値
--model-path BPU 量子化モデルのパス（.bin） str /app/model/basic/yolov5s_672x672_nv12.bin
--priority 推論の優先度（0～255、255 が最高） int 0
--bpu-cores BPU コアのインデックスリスト（例：0 1） int list [0]
--label-file クラスラベルのパス str coco_classes.names
--resize-type 前処理のリサイズ方式（0：直接リサイズ、1：レターボックスリサイズ） int 1
--classes-num 検出クラス数 int 80
--nms-thres NMS の IoU しきい値 float 0.45
--score-thres 信頼度しきい値 float 0.25

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

ここでは USB カメラのサンプルのソフトウェアアーキテクチャと処理の流れを紹介し、モデルの読み込みから結果の出力までの一連の実行過程を説明します。コード全体の構造とデータの流れを理解する助けとなります。

  1. カメラの検出とオープン - /dev/video* を自動的に検索して最初に利用可能な USB カメラを開き、解像度とフレームレートを設定します
  2. モデルの読み込み - hbm_runtime モジュールでモデルファイルを読み込みます
  3. 画像の読み込み - リアルタイムの画像フレームを読み取ります
  4. 画像の前処理 - カメラフレームをモデルの入力サイズにリサイズし、BGR を NV12 に変換して、モデルの入力形式に合わせてテンソルを構成します
  5. モデル推論 - BPU 上で YOLOv5X の順伝播推論を実行します
  6. 結果の後処理 - 出力を逆量子化し、予測枠をデコードして、信頼度フィルタリングと NMS を行い、座標を元画像にマッピングします
  7. 可視化出力 - 画像上に検出枠、クラス、信頼度を描画してウィンドウにリアルタイム表示し、q で終了します

API の流れ

ここではサンプルプログラムで使用している主な API を挙げ、各 API の機能、入力パラメータ、戻り値を説明します。コードの実装の詳細や API の呼び出し方を素早く理解する助けとなります。cv2. で始まるものは OpenCV ライブラリの汎用 API で、それ以外は D-Robotics 独自の API です。

  1. find_first_usb_camera()

USB カメラを自動検索します

  1. cv2.VideoCapture(device)

カメラを開きます

  1. hbm_runtime.HB_HBMRuntime(model_path)

量子化モデルを読み込みます。入力：モデルのパス

  1. load_class_names(label_file)

クラス名を読み込みます。入力：クラスファイルのパス

  1. cap.read()

画像フレームを取得します

  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_classification(cls_output, conf_thres)

予測結果をフィルタリングします。入力：分類出力、信頼度しきい値。戻り値：信頼度、クラス ID、有効なインデックス

  1. NMS(dbboxes, scores, ids, nms_thresh)

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

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

検出枠を元画像のサイズに合わせます。入力：検出枠、元画像の幅、元画像の高さ、モデル入力の幅、モデル入力の高さ、リサイズ方式。戻り値：スケーリング後の検出枠

  1. draw_boxes(img, boxes, ids, scores, coco_names, rdk_colors)

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

  1. cv2.imshow(...) / cv2.waitKey(1) 表示とキー入力による終了

FAQ

Q: 実行時に「No USB camera found」と表示される場合は？ A: カメラが接続されており、/dev の下に video* デバイスが存在することを確認してください。v4l2-ctl --list-devices で確認することもできます。

Q: モデルファイルが存在しない場合は？ A: --model-path が正しいか確認してください。/app/model/basic の下で該当するモデルを探すことができます。

Q: 映像が遅延したりカクついたりする場合は？ A: カメラの解像度やフレームレートを下げるか、モデルの入力サイズを小さくしてください。

Q: プログラムを終了するには？ A: マウスのフォーカスを表示ウィンドウに合わせ、q キーを押して終了します。

← 前へ1. カメラの使用次へ →1.2 MIPI カメラによるリアルタイム検出