10-10 人体骨格キーポイント検出機能サンプルチュートリアル
前章 10-9 では、顔認識モデルと特徴比較技術を使い、AI に「 誰なのか ( Who ) 」を認識させることに成功し、専用の VIP 受付システムを構築しました。
しかし、応用シーンが「 医療分野の転倒検出 」や「 アスリートの姿勢分析 」の場合、「 その人が誰か 」を知ることは主目的ではありません。より重要なのは、「 その人が今何をしているのか ( What ) 」を知ることです。
本章では、行動分析の入り口となる 人体骨格キーポイント検出 ( Human Skeleton 17KPS ) に入ります。AI の注目点を「顔」から「全身」へ拡張し、頭部の顔特徴点、肩、肘、手首、腰、膝、足首を含む人体の 17 個の関節点を正確に取得します。さらに、OpenCV の高度な描画テクニックに挑戦し、コードでこれらの関節点を「 接続 」して、テクノロジー感のあるデジタル骨格を描画します。
学習目標
本章では、以下を学びます。
1. 視点の切り替え : 「特徴比較」から「姿勢マーキング」へ戻る開発ロジックの違いを理解する。
2. 骨格辞書の構築 : C++ の Struct を実装し、人体骨格の接続対応表を定義する。
3. 確率値 ( Probability ) の活用 : 前章で学んだ fProbability を使ってフィルタリングを行い、骨格が画面外に描画されるのを防ぐ。
4. OpenCV の高度な描画 : cv::circle による関節描画と cv::line による骨格線描画を組み合わせ、動的な骨格オーバーレイを完成させる。
準備作業
今回のモデルパッケージは、複数の認識用重みファイルを組み合わせているため、これまでよりファイル数が多くなっています。Human Skeleton 17KPS モデルの圧縮ファイルを探してください。ファイル名には HUMAN.SKELETON.17KPSのような文字が含まれている場合があります。解凍後、 QDEEP.OD.HUMAN.SKELETON.17KPS.EX.CFG と対応するすべての重みファイルを、Qt プロジェクトのビルド出力ディレクトリにコピーしてください。
コア API はどのように変更するのか？
10-9 では、顔特徴を抽出するために FLAG_FULL tを有効にしました。しかし本章では人物認識は不要で、全身の座標だけが必要です。そのため API 設定はよりシンプルな使い方に戻りますが、モデル設定値は大きく異なります。
• モデル設定タイプの変更 : QDEEP_CREATE_OBJECT_DETECT の 3 番目の引数を、骨格専用の QDEEP_OBJECT_DETECT_CONFIG_MODEL_HUMAN_SKELETON_17_KEYPOINTS_EX に変更してください。
• 17KPS の返却構造を理解する : 前章を振り返ると、 sKeypoints 配列には顔の 5 点だけが入っていました。しかしこのモデルでは、sKeypoints に 17 個の点がすべて格納されます。これらの点の順序は固定されており、例えば 0 は鼻、5 は左肩、6 は右肩、というように定義されています。そして今回は、構造体内の fProbability、つまり信頼度スコアが非常に重要な役割を果たします。
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_KEYPOINT 内で sKeypoints[ QDEEP_MAX_KEYPOINY_SIZE ] という配列が使用可能になります。この配列の各要素は、単一の「特徴点」を表すための構造体 QDEEP_MAX_KEYPOINY_SIZE です。
この構造体には、非常に重要な 4 つのパラメータが含まれています。定義は以下の通りです。
コアコードの作成
プロジェクトを開き、最も重要なコード変更を行いましょう。
骨格接続辞書を定義する
骨格を描画するには、17 個の点を適当に接続するわけにはいきません。「左肩は左肘に接続する」「左肘は左手首に接続する」というルールを、プログラムに明確に伝える必要があります。 mainwindow.cpp の上部、ループの外側に、これらの接続ルールと専用色を定義する構造体と配列を作成してください。
モデル読み込みを変更する
コンストラクタ内で、新しい骨格モデル設定を適用します。今回は人物認識を行わないため、 dwFlags は軌跡追跡に設定すれば十分です。
OpenCV による動的な接続描画と安全対策
AI から返却された構造体を正常に取得できたら、次の重要な作業は OpenCV API を使って骨格を画像上に重ねることです。
ここでは、「 先に線を描き、その後に点を描く」という描画手順を導入し、プログラミングにおける continue による早期スキップを使って、安全対策を非常にすっきり実装します。描画手順は以下の通りです。
1. 骨格の接続線を描画する : 定義済みの bones 辞書を使い、接続されたキーポイント同士に線を描画します。ここで非常に重要な点があります。 必ず先に線を描いてください。 先に円点を描いてから線を描くと、太い骨格線が繊細な関節点を覆ってしまい、画面の立体感が弱くなります。
2. 関節の円点を描画する : 各キーポイント座標に cv::circle を使って塗りつぶし円を描画します。遮蔽によって信頼度が低い点や、座標が 0 の無効な点を画面に描画しないように、 continue 条件フィルタを実装します。条件を満たさない点は、そのままスキップして描画しません。
最終確認
左下の 「Build and RUN」 をクリックしてプロジェクトを実行します。
1. 受信と検出を開始します。
2. 自分、または近くの人にカメラの前に立ってもらい、手を振ったり、足を上げたり、いくつかストレッチ動作をしてみてください。
➤ 重要なお知らせ : 初めてこのソフトウェアを 起動する（プログラムを実行する）瞬間、画面が表示されるまで少し時間がかかる場合がありますが、心配しないでください。これは「AI モデルの読み込み」処理をプログラムのコンストラクタ内に書いているためです。初回実行時、モデルは初期化設定を行う必要があり、その間システムは巨大なニューラルネットワークの重みファイルを GPU に読み込んでいます。ソフトウェアが正常に起動すれば、AI の頭脳はバックグラウンドで準備完了です。次回以降は、この初期化待ち時間は不要になります。
おめでとうございます！ この段階から、取得するデータは単なる X/Y 座標ではなく、「人体姿勢」の定量データになります。この 17 個のキーポイントこそが、 行動分析 ( Behavior Analysis )を構築するための中核となる基礎です。今後、連続映像と時間軸上でこれらのキーポイントの変化をさらに追跡すれば、スマート介護における「転倒検出アラート」や、スポーツトレーニングにおける「姿勢分析」など、商用レベルの高度な AI 分野へ応用を広げることができます。