5.1 画像分類

サンプルの概要

画像分類サンプルは /app/pydev_demo/01_classification_sample/ にある Python インターフェース の開発コードサンプル群で、hbm_runtime モジュールを使用して画像分類タスクを行う方法を示します。これらのサンプルは、異なるニューラルネットワークモデルに基づいて同じ画像分類機能を実現しています。

含まれるモデルサンプル：

root@ubuntu:/app/pydev_demo/01_classification_sample$ tree -L 1
.
├── 01_resnet18
└── 02_mobilenetv2

実行結果の例

2 つのサンプルの結果は同じで、呼び出すモデルが異なるだけです。ここでは resnet18 モデルの結果を示します。MobileNetV2 の結果も同様です。

ハードウェアの準備

ハードウェアの接続

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

クイックスタート

コードとボード上の場所

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

root@ubuntu:/app/pydev_demo/01_classification_sample# tree
.
├── 01_resnet18
│   ├── imagenet1000_clsidx_to_labels.txt
│   ├── resnet18.py
│   └── zebra_cls.jpg
└── 02_mobilenetv2
    ├── imagenet1000_clsidx_to_labels.txt
    ├── mobilenetv2.py
    └── zebra_cls.jpg

コンパイルと実行

Python サンプルはコンパイル不要で、サンプルディレクトリに移動してそのまま実行できます。

cd /app/pydev_demo/01_classification_sample/01_resnet18
python resnet18.py 

cd /app/pydev_demo/01_classification_sample/02_mobilenetv2
python mobilenetv2.py

実行結果

resnet18 の実行結果

root@ubuntu:/app/pydev_demo/01_classification_sample/01_resnet18# python resnet18.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-20,18:14:57.93.241) [HorizonRT] The model builder version = 1.23.5
[W][DNN]bpu_model_info.cpp:491][Version](2026-01-20,18:14:57.223.307) Model: resnet18_224x224_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.

...

Top-5 Predictions:
zebra: 0.9853
tiger, Panthera tigris: 0.0009
prairie chicken, prairie grouse, prairie fowl: 0.0008
gazelle: 0.0006
warthog: 0.0004
root@ubuntu:/app/pydev_demo/01_classification_sample/01_resnet18#

mobilenetv2 の実行結果

root@ubuntu:/app/pydev_demo/01_classification_sample/02_mobilenetv2# python mobilenetv2.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-21,17:24:56.88.461) [HorizonRT] The model builder version = 1.23.5
[W][DNN]bpu_model_info.cpp:491][Version](2026-01-21,17:24:56.172.366) Model: mobilenetv2_224x224_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.

...

Top-5 Predictions:
zebra: 0.9936
tiger, Panthera tigris: 0.0039
hartebeest: 0.0007
tiger cat: 0.0007
impala, Aepyceros melampus: 0.0003

詳細説明

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

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

パラメータ	説明	型	デフォルト値
`--model-path`	BPU 量子化モデルのパス（`.bin`）	str	サンプルごとに異なります。下表「各サンプルのデフォルトモデルパス」を参照
`--test-img`	入力テスト画像のパス	str	`zebra_cls.jpg`
`--label-file`	クラスラベルのマッピングファイルのパス（dict 形式）	str	`imagenet1000_clsidx_to_labels.txt`
`--priority`	推論の優先度（0~255、255 が最高）	int	`0`
`--bpu-cores`	BPU コアのインデックスリスト（例: `0 1`）	int list	`[0]`

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

サンプル	デフォルトモデルパス
ResNet18	`/opt/hobot/model/x5/basic/resnet18_224x224_nv12.bin`
MobileNetV2	`/opt/hobot/model/x5/basic/mobilenetv2_224x224_nv12.bin`

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

ここでは、基本的な画像分類サンプルのソフトウェアアーキテクチャと処理の流れを紹介し、モデルの読み込みから結果出力までの一連の実行過程を説明して、コードの全体構造とデータの流れを理解できるようにします。

モデルの読み込み - hbm_runtime モジュールを使用してプリコンパイル済みのモデルファイルを読み込む
画像の読み込み - 入力テスト画像を読み込む
画像の前処理 - 入力画像をモデルの入力サイズにスケーリングし、BGR を NV12 形式に変換
モデル推論 - BPU 上でモデルの順伝播計算を実行
結果の後処理 - post_utils ライブラリを使用して推論結果を解析し、分類確率を取得
結果の出力 - Top-5 の分類結果と対応する信頼度を出力

API フローの説明

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

hbm_runtime.HB_HBMRuntime(model_path)

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

load_image(image_path)

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

resized_image(img, input_W, input_H, resize_type)

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

bgr_to_nv12_planes(image)

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

model.run(input_data)

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

print_topk_predictions(outputs, idx2label)

後処理を行い Top-K の結果を出力します。入力：モデル出力 tensor、クラス名のリスト

FAQ

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