10-11 手部キーポイント検出機能サンプルチュートリアル

前章【10-10】では、カメラを少し引いて、人型骨格キーポイントモデルを使い、人体の全身骨格を取得しました。これにより、「行動分析」の基礎を築きました。しかし、開発したいものが「手話翻訳機」、「非接触エレベーターボタン（仮想マウス）」、または「じゃんけんゲーム」だったらどうでしょうか。この場合、全身骨格の精度だけでは不十分です。

本章では、カメラを「近づけ」、人体の中で最も精密で柔軟な部位である両手に注目します。ここでは手部キーポイントモデルを導入します。このモデルは、各手から手首と5本の指の各関節を含む21個のキーポイントを正確に取得できます。さらに素晴らしいことに、前章で構築した優れた OpenCV 描画アーキテクチャのおかげで、今回のアップグレードはほとんど手間をかけずに実現できます。

学習目標

本章を通して、以下を学びます。

1. 視点とモデルの切り替え : 全身（17点）から、より細かな手部（21点）の追跡領域へ移行します。

2. 手部接続辞書の構築 : 公式の21個のキーポイントのインデックス定義、つまり手首と5本の指のトポロジー構造を理解します。

3. アーキテクチャの再利用 : 10-10 の「先に線を描き、その後に点を描く」および「防御的フィル

準備作業

今回のモデルパッケージは、これまでのものと少し異なります。複数の認識用重みファイルを組み合わせているため、ファイル数が多くなります。Human Hand 21KPS モデルの圧縮ファイルを見つけてください。ファイル名には HUMAN.HAND.21KPS に関連する文字列が含まれている場合があります。解凍後、内部の QDEEP.OD.HUMAN.HAND.21KPS.LITE.CFG （設定ファイル）と、対応するすべての重みファイルを、Qt プロジェクトのビルド出力ディレクトリへまとめてコピーしてください。

コア API はどのように変更するのか

今回の API ロジックは 10-10 と完全に同じです。システムは取得した点を同じように sKeypoints 配列へ格納します。私たちが行う必要がある唯一の変更は、検出器を作成するときのパラメータを変更することです。

• モデル設定タイプの変更 : In QDEEP_CREATE_OBJECT_DETECT で、Enum を手部専用の QDEEP_OBJECT_DETECT_CONFIG_MODEL_HAND_LANDMARK_21_KEYPOINTS に変更してください。

• 核心的な違い（17KPS vs 21KPS）: 10-10 の全身モデルでは、1つの画面内の「1人」に対して、17個の点を含む配列が1組生成されます。一方、10-11 の手部モデルでは、AI は「手」を単位として扱います。画面内の各手は、左手・右手を問わず、それぞれ独立して 21個の点を含む sKeypoints 配列を1組生成します。

QDEEP_CREATE_OBJECT_DETECT

これは AI エンジンを作成し、「頭脳」（モデル）を読み込むための最も重要な API です。ユーザーはこの API を通して検出器を初期化する必要があります。

QDEEP_OBJECT_DETECT_BOUNDING_BOX 構造体

手部骨格キーポイントモデルに切り替えると、AI エンジンが QDEEP_OBJECT_DETECT_BOUNDING_BOX を通して返す sKeypoints は、まったく新しい物理的な意味を持つようになります。
 

 

QDEEP_OBJECT_DETECT_KEYPOINT 構造体

QDEEP_OBJECT_DETECT_BOUNDING_BOX の中では、 sKeypoints[ QDEEP_MAX_KEYPOINY_SIZE ] という配列が利用可能になります。この配列内の各要素は、単一の「特徴点」を記述するための専用構造体、 QDEEP_OBJECT_DETECT_KEYPOINT です。

内部には、非常に価値の高い4つのパラメータが含まれています。詳細な定義は以下の通りです。
 

コアコードの作成

プロジェクトを開き、最も重要なコード変更を行いましょう。

21点手部骨格接続辞書の定義

手の21個の点はランダムに配置されているわけではありません。非常に厳密な配置ロジックがあります。 0番は手首で、その後は4点ごとに1本の指を表します。mainwindow.cpp の上部で、前章の全身用 bones を、以下の指用接続辞書に置き換えてください。

モデル読み込みの変更

コンストラクタ内で、新しい手部モデル設定を適用します。今回は人物識別を行う必要がないため、 dwFlags は軌跡追跡だけに設定すれば十分です。
 

OpenCV 描画 S.O.P

AI が返す構造体を正常に取得したら、次は OpenCV を使って手部骨格を画面に重ねて描画します。開発者は以下の順序で描画してください。

1. 21個のキーポイントを取得する : m_pObjectList から、その手に対応する21個の sKeypoints 配列を取り出します。

2. 指の骨格接続線を描画する : 定義済みの fingerBones 辞書を使い、接続されている指関節同士を線で結びます。ここでも「先に線を描き、その後に点を描く」という美的な順序を維持し、線が関節を覆ってしまわないようにします。

3. 関節の円を描画する : 各指関節の座標上に塗りつぶし円を描画します。
 

最終確認

左下の 「Build and RUN」 をクリックしてプロジェクトを実行してください。

1. 受信と検出を開始します。

2. 両手をカメラの前に上げ、手を開く、握りこぶしを作る、または「いいね 」や「ピース  」のジェスチャーを試してください。

➤ 補足リマインダー（非常に重要）: 初めてこの ソフトウェアを起動する（プログラムを実行する）瞬間、インターフェースが表示されるまで少し時間がかかる場合があります。心配しないでください。これは「AI モデルを読み込む」ロジックをプログラムのコンストラクタ内に書いているためです。初回実行時にはモデルの初期化設定が必要であり、システムは巨大なニューラルネットワークの重みファイルを GPU に読み込んでいます。ソフトウェアが正常に起動した時点で、AI の頭脳はバックグラウンドで準備完了です。次回以降にソフトウェアを起動するときは、この初期化待ち時間は不要になります。

おめでとうございます。10-10 の全身追跡から 10-11 の指先キャプチャまでを通して、NexVDO SDK の姿勢認識モデルをしっかり習得しただけでなく、高い再利用性（High Reusability）と高い安定性を備えた商用レベルの OpenCV 描画コードを書く方法も学びました。