ドキュメント5.5 オープンドメイン物体検出
サンプルの概要
オープンドメインインスタンスセグメンテーションサンプルは /app/pydev_demo/05_open_instance_seg_sample/ にある Python インターフェース の開発コードサンプル群で、hbm_runtime モジュールを使用してオープンドメイン物体検出タスクを行う方法を示します。このサンプルは YOLO-World モデルを使用しており、テキストプロンプト（prompts）による柔軟な物体検出に対応しているため、事前にクラスリストを定義する必要がありません。
含まれるモデルサンプル：
root@ubuntu:/app/pydev_demo/05_open_instance_seg_sample$ tree -L 1
.
└── 01_yolo_world
実行結果の例
サンプルは画像内でテキストプロンプトに一致する対象を検出し、検出枠、クラス名、信頼度を描画します。
ハードウェアの準備
ハードウェアの接続
このサンプルは RDK 開発ボード本体のみで動作し、追加の周辺機器の接続は不要です。開発ボードに正常に給電され、システムが起動していることを確認してください。
クイックスタート
コードとボード上の場所
/app/pydev_demo/05_open_instance_seg_sample/ に移動すると、オープンドメインインスタンスセグメンテーションのサンプルフォルダが含まれていることが確認できます：
root@ubuntu:/app/pydev_demo/05_open_instance_seg_sample# tree
.
└── 01_yolo_world
├── dog.jpeg
├── offline_vocabulary_embeddings.json
├── result.jpg
├── yolo_world.bin
└── yoloworld.py
コンパイルと実行
Python サンプルはコンパイル不要で、そのまま実行できます。
cd /app/pydev_demo/05_open_instance_seg_sample/01_yolo_world
python yoloworld.py
実行結果
root@ubuntu:/app/pydev_demo/05_open_instance_seg_sample/01_yolo_world# python yoloworld.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](2000-01-01,10:59:17.916.291) [HorizonRT] The model builder version = 1.23.6
[W][DNN]bpu_model_info.cpp:491][Version](2000-01-01,10:59:18.311.878) Model: yolo_world. Inconsistency between the hbrt library version 3.15.55.0 and the model build version 3.15.49.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.
...
[Saved] Result saved to: result.jpg
詳細説明
サンプルプログラムのパラメータオプションの説明
オープンドメインインスタンスセグメンテーションサンプルはコマンドライン引数による設定に対応しています。パラメータを指定しない場合、プログラムはデフォルト値を使用して同じディレクトリ内のテスト画像を自動的に読み込み、推論を行います。
| パラメータ | 説明 | 型 | デフォルト値 |
|---|---|---|---|
--model-path |
BPU 量子化モデルのパス（.bin） |
str | /app/model/basic/yolo_world.bin |
--test-img |
入力テスト画像のパス | str | dog.jpeg |
--label-file |
語彙埋め込みファイルのパス（JSON 形式） | str | offline_vocabulary_embeddings.json |
--prompts |
テキストプロンプト。カンマ区切り（例: dog,cat） |
str | dog |
--img-save-path |
検出結果画像の保存パス | str | result.jpg |
--priority |
推論の優先度（0~255、255 が最高） | int | 0 |
--bpu-cores |
BPU コアのインデックスリスト（例: 0 1） |
int list | [0] |
--nms-thres |
非最大値抑制（NMS）のしきい値 | float | 0.45 |
--score-thres |
信頼度しきい値 | float | 0.05 |
ソフトウェアアーキテクチャの説明
ここでは、オープンドメインインスタンスセグメンテーションサンプルのソフトウェアアーキテクチャと処理の流れを紹介し、モデルの読み込みから結果出力までの一連の実行過程を説明して、コードの全体構造とデータの流れを理解できるようにします。
- 語彙の読み込み - JSON ファイルから語彙の埋め込みベクトルを読み込む
- プロンプト処理 - ユーザーが指定したテキストプロンプトを解析し、語彙から対応する埋め込みベクトルを検索
- モデルの読み込み -
hbm_runtimeモジュールを使用してプリコンパイル済みのモデルファイルを読み込む - 画像の読み込み - 入力テスト画像を読み込む
- 画像の前処理 - 画像をモデルの入力サイズにスケーリングし、BGR を RGB に変換して NCHW 形式に変換
- モデル推論 - BPU 上でモデルの順伝播計算を実行（入力は画像テンソルとテキスト埋め込みベクトル）
- 結果の後処理 - post_utils ライブラリを使用して推論結果を解析し、デコード、信頼度フィルタリング、NMS（非最大値抑制）を実行
- 結果の出力 - 画像上に検出枠を描画し、結果画像を保存
API フローの説明
ここでは、サンプルプログラムで使用している主な API インターフェースを列挙し、各インターフェースの機能、入力パラメータ、戻り値を説明して、開発者がコードの実装詳細とインターフェースの呼び出し方法をすばやく理解できるようにします。cv2. で始まるものは OpenCV の汎用インターフェース、np. で始まるものは Numpy の汎用インターフェースで、それ以外は hbm_runtime およびその関連インターフェースです。
json.load(file)
語彙埋め込みファイルを読み込みます。入力：ファイルパス、戻り値：語彙辞書
hbm_runtime.HB_HBMRuntime(model_path)
プリコンパイル済みモデルを読み込みます。入力：モデルファイルのパス
load_image(image_path)
テスト画像を読み込みます。入力：画像ファイルのパス
cv2.resize(img, (0,0), fx,fy)
画像をスケーリングします。入力：画像、目標サイズ、水平方向のスケール係数、垂直方向のスケール係数、戻り値：スケーリング後の画像
np.transpose
配列を転置し、画像を HWC から NCHW 形式に変換します
model.run(input_dict)
モデル推論を実行します。入力：画像テンソルとテキスト埋め込みを含むデータ、戻り値：モデル出力
cv2.minMaxLoc(array)
配列内の最大値とその位置を検索します。入力：モデル出力、戻り値：信頼度の最小値、信頼度の最大値、最小値の位置、最大値の位置
NMS(boxes，scores_np，nms_thres)
非最大値抑制を行います。入力：検出枠、信頼度、クラス、IoU しきい値、戻り値：保持するインデックス
draw_boxes(img, boxes, cls_ids, scores, classes, rdk_colors)
検出結果を描画します。入力：画像、検出枠、クラス ID、信頼度、クラスリスト、カラーマップ
cv2.imwrite(img_path,img)
最終結果を保存します。入力：保存パス、画像