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

5.3 セマンティックセグメンテーション

サンプルの概要

セマンティックセグメンテーションサンプルは /app/pydev_demo/03_instance_segmentation_sample/ にある Python インターフェース の開発コードサンプル群で、hbm_runtime モジュールを使用してセマンティックセグメンテーションタスクを行う方法を示します。これらのサンプルは、異なるニューラルネットワークモデルに基づいてセマンティックセグメンテーション機能を実現しています。

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

root@ubuntu:/app/pydev_demo/03_instance_segmentation_sample$ tree -L 1
.
├── 01_unetmobilenet
└── 02_ultralytics_yolo11_seg

実行結果の例

2 つのサンプルはいずれもセマンティックセグメンテーションを実現していますが、結果は異なります。ここでは 2 つのモデルの結果を示します。

unetmobilenet の実行結果例

yolov11 の実行結果例

ハードウェアの準備

ハードウェアの接続

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

クイックスタート

コードとボード上の場所

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

root@ubuntu:/app/pydev_demo/03_instance_segmentation_sample# tree
.
├── 01_unetmobilenet
│   ├── segmentation.png
│   ├── unet_mobilenet.py
│   └── result.jpg
└── 02_ultralytics_yolo11_seg
    ├── bus.jpg
    ├── coco_classes.names
    ├── result.jpg
    ├── ultralytics_yolo11_seg.py
    └── yolo11n_seg_bayese_640x640_nv12.bin

コンパイルと実行

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

cd /app/pydev_demo/03_instance_segmentation_sample/01_unetmobilenet
python unet_mobilenet.py 

cd /app/pydev_demo/03_instance_segmentation_sample/02_ultralytics_yolo11_seg
python ultralytics_yolo11_seg.py

実行結果

UNetMobileNet の実行結果

root@ubuntu:/app/pydev_demo/03_instance_segmentation_sample/01_unetmobilenet# python unet_mobilenet.py 
[BPU_PLAT]BPU Platform Version(1.3.6)! soc info(x5)
[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-02,02:54:24.731.966) [HorizonRT] The model builder version = 1.23.8

[W][DNN]bpu_model_info.cpp:491][Version](2000-01-02,02:54:24.831.251) Model: unet_mobilenet_1024x2048_nv12. Inconsistency between the hbrt library version 3.15.55.0 and the model build version 3.15.54.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.
=== Model Name List ===
['unet_mobilenet_1024x2048_nv12']

...

=== Scheduling Parameters ===
unet_mobilenet_1024x2048_nv12:
  priority    : 0
  customId    : 0
  bpu_cores   : [0]
  deviceId    : 0
[Saved] Result saved to: result.jpg

YOLOv11 インスタンスセグメンテーションの実行結果

root@ubuntu:/app/pydev_demo/03_instance_segmentation_sample/02_ultralytics_yolo11_seg# python ultralytics_yolo11_seg.py
[BPU_PLAT]BPU Platform Version(1.3.6)! soc info(x5)
[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-02,02:51:30.798.145) [HorizonRT] The model builder version = 1.24.3
=== Model Name List ===
['yolo11n_seg_bayese_640x640_nv12']

=== Model Count ===
1

=== Input Counts ===
yolo11n_seg_bayese_640x640_nv12: 1

...

=== Scheduling Parameters ===
yolo11n_seg_bayese_640x640_nv12:
  priority    : 0
  customId    : 0
  bpu_cores   : [0]
  deviceId    : 0
[Saved] Result saved to: result.jpg

詳細説明

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

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

UNetMobileNet のパラメータ説明

パラメータ 説明 型 デフォルト値
--model-path BPU 量子化モデルのパス（.bin） str /app/model/basic/mobilenet_unet_1024x2048_nv12.bin
--test-img 入力テスト画像のパス str segmentation.png
--img-save-path セグメンテーション結果画像の保存パス str result.jpg
--priority 推論の優先度（0~255、255 が最高） int 0
--bpu-cores BPU コアのインデックスリスト（例: 0 1） int list [0]
--alpha-f セグメンテーションマスクと元画像を合成する際の透明度係数（0.0=マスクのみ、1.0=元画像のみ） float 0.75

YOLOv11 のパラメータ説明

パラメータ 説明 型 デフォルト値
--model-path BPU 量子化モデルのパス（.bin） str /app/model/basic/yolo11n_seg_bayese_640x640_nv12.bin
--test-img 入力テスト画像のパス str bus.jpg
--label-file クラスラベルのパス（1 行に 1 クラス） str coco_classes.names
--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.7
--score-thres 信頼度しきい値 float 0.25
--is-open マスクにモルフォロジー演算を行うかどうか bool True
--is-point マスクのエッジ輪郭を描画するかどうか bool True

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

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

  1. モデルの読み込み - hbm_runtime モジュールを使用してプリコンパイル済みのモデルファイルを読み込む
  2. 画像の読み込み - 入力テスト画像を読み込む
  3. 画像の前処理 - 入力画像をモデルの入力サイズにスケーリングし、BGR を NV12 形式に変換
  4. モデル推論 - BPU 上でモデルの順伝播計算を実行
  5. 結果の後処理 - セグメンテーション出力を解析し、クラス予測をカラーマスクにマッピングして元画像と合成
  6. 結果の出力 - セグメンテーションマスクを重ねた結果画像を保存

API フローの説明

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

UNetMobileNet の API フロー

  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. np.argmax(logits, axis=-1)

最大値のインデックスを取得します。入力：モデル出力、指定の次元、戻り値：予測クラス

  1. cv2.resize(pred_class, (input_W, input_H), interpolation=cv2.INTER_NEAREST)

予測クラスを元画像のサイズにスケーリングします。入力：予測クラス、（モデル入力の幅、モデル入力の高さ）、補間の種類

  1. recover_to_original_size(seg_mask, img_w, img_h, resize_type)

セグメンテーションマスクを元画像のサイズに復元します。入力：セグメンテーションマスク、元画像の幅、元画像の高さ、スケーリングの種類

  1. cv2.addWeighted(origin_image, alpha, parsing_img, 1-alpha, 0.0)

元画像とセグメンテーションマスクを合成します。入力：元画像、元画像の重み、セグメンテーションマスクのカラー画像、セグメンテーションマスクの重み、輝度オフセット

YOLOv11 インスタンスセグメンテーションの API フロー

  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. filter_mces(mces_output, valid_indices)

マスク係数をフィルタリングします。入力：マスク係数の出力、有効インデックス、戻り値：マスク係数

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

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

  1. decode_masks(mces, boxes, protos, input_W, input_H, Mask_W, Mask_H, mask_thresh)

セグメンテーションマスクをデコードします。入力：マスク係数、検出枠、マスクプロトタイプ、入力の幅、入力の高さ、マスクの幅、マスクの高さ、しきい値、戻り値：マスク

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

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

  1. resize_masks_to_boxes(masks, boxes, img_w, img_h, do_morph)

マスクを検出枠の領域に合わせて調整し、元画像のサイズにスケーリングします。入力：マスク、検出枠、元画像の幅、元画像の高さ、モルフォロジー演算を行うかどうか、戻り値：調整後のマスク

  1. draw_boxes(image, boxes, cls_ids, scores, class_names, rdk_colors)

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

  1. draw_masks(image, boxes, masks, cls_ids, rdk_colors, alpha)

セグメンテーションマスクを描画します。入力：画像、検出枠、マスク、クラス ID、カラーマップ、透明度

  1. draw_contours(image, boxes, masks, cls_ids, rdk_colors, thickness)

マスクのエッジ輪郭を描画します。入力：画像、検出枠、マスク、クラス ID、カラーマップ、線幅

  1. cv2.imwrite(image_path, image)

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

FAQ

https://developer.d-robotics.cc/rdk_doc/Basic_Application/pydev_demo_sample/RDK_X5/instance_segment_sample#yolov11%E5%AE%9E%E4%BE%8B%E5%88%86%E5%89%B2-api-%E6%B5%81%E7%A8%8B

← 前へ5.2 物体検出次へ →5.4 姿勢推定