5.4 姿勢推定

サンプルの概要

姿勢推定サンプルは /app/pydev_demo/04_pose_sample/ にある Python インターフェース の開発コードサンプル群で、hbm_runtime モジュールを使用して人体姿勢推定タスクを行う方法を示します。サンプルは YOLO11 モデルに基づいて人体キーポイント検出機能を実現しています。

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

root@ubuntu:/app/pydev_demo/04_pose_sample$ tree -L 1
.
└── 01_ultralytics_yolo11_pose

実行結果の例

サンプルは画像内の人体を検出し、人体のキーポイント（頭部、肩、肘、手首、膝、足首など）をマーキングするとともに、検出枠と信頼度を描画します。

ハードウェアの準備

ハードウェアの接続

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

クイックスタート

コードとボード上の場所

/app/pydev_demo/04_pose_sample/ に移動すると、姿勢推定のサンプルフォルダが含まれていることが確認できます：

root@ubuntu:/app/pydev_demo/04_pose_sample# tree
.
└── 01_ultralytics_yolo11_pose
    ├── bus.jpg
    ├── coco_classes.names
    ├── result.jpg
    ├── ultralytics_yolo11_pose.py
    └── yolo11n_pose_bayese_640x640_nv12.bin

コンパイルと実行

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

cd /app/pydev_demo/04_pose_sample/01_ultralytics_yolo11_pose
python ultralytics_yolo11_pose.py

実行結果

root@ubuntu:/app/pydev_demo/04_pose_sample/01_ultralytics_yolo11_pose# python ultralytics_yolo11_pose.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:16:20.686.495) [HorizonRT] The model builder version = 1.24.3
...
[Saved] Result saved to: result.jpg

詳細説明

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

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

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

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

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

API フローの説明

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

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

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

1. decode_boxes(box_output, valid_indices, anchor_size, stride, weights)

検出枠をデコードします。入力：ボックス出力、有効インデックス、アンカーボックスのサイズ、ストライド、重み、戻り値：検出枠

1. decode_kpts(kpts_output, valid_indices, anchor_size, stride)

キーポイントをデコードします。入力：キーポイント出力、有効インデックス、アンカーボックスのサイズ、ストライド、戻り値：キーポイント座標と信頼度

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

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

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

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

1. scale_keypoints_to_original_image(kpts_xy, kpts_score, boxes, img_w, img_h, input_W, input_H, resize_type)

キーポイント座標を元画像のサイズに調整します。入力：キーポイント座標、キーポイントの信頼度、検出枠、元画像の幅、元画像の高さ、モデル入力の幅、モデル入力の高さ、スケーリング方法、戻り値：スケーリング後のキーポイント座標と信頼度

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

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

1. draw_keypoints(image, kpts_xy, kpt_score, kpt_conf_thresh)

キーポイントの骨格を描画します。入力：画像、キーポイント座標、キーポイントの信頼度、キーポイントの信頼度しきい値

1. cv2.imwrite(image_path, image)

結果画像を保存します。入力：保存パス、画像

FAQ

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