10-10 人形骨架關鍵點偵測功能範例教學

在上一章【10-9】中，我們透過人臉辨識模型與特徵比對技術，成功讓 AI 學會了「 認人 ( Who ) 」，打造出專屬的 VIP 迎賓系統。

但如果我們的應用場景是「 醫療的跌倒偵測 」、或是「 運動員的姿勢分析 」，知道「 他是誰 」並不是重點，我們更需要知道的是「 他現在正在做什麼 ( What ) 」！

本章節將帶您進入行為分析的前哨站 —— 人體骨架關鍵點偵測 ( Human Skeleton 17KPS )。我們將把 AI 的關注點從「臉部」擴展到「全身」，精準抓取人體的 17 個關節點（涵蓋頭部五官、肩、肘、腕、髖、膝、踝）。更精彩的是，我們將挑戰進階的 OpenCV 繪圖技巧，用程式碼把這些關節點「連線」起來，畫出充滿科技感的數位骨架！

學習目標

透過本章節，您將學會：

1. 視角轉換 : 理解從「特徵比對」轉換回「姿態標記」的開發邏輯差異。

2. 建構骨架字典 : 實作 C++ 結構體 ( Struct ) 來定義人體骨骼的連線對應表 ( Bone Connections )。

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 。但在本章節，我們不需要認人，只需要全身的座標，因此 API 的設定會回歸單純使用，但模型的設定值將大不相同：

• 模型配置類型的改變 : 在 QDEEP_CREATE_OBJECT_DETECT 的第三個參數，請換成骨架專屬的  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_BOUNDING_BOX 中會解鎖一個名為 sKeypoints[ QDEEP_MAX_KEYPOINY_SIZE ] 的陣列。這陣列裡的每一個元素，都是一個專門用來描述單一「特徵點」的結構體：QDEEP_OBJECT_DETECT_KEYPOINT。

它的內部包含了四個極具價值的參數，詳細定義如下：

撰寫核心程式碼

請開啟您的專案，我們來進行最核心的程式碼修改：

定義骨骼連線字典

要畫出骨架，我們不能盲目地把 17 個點亂連一通。我們必須明確告訴程式「左肩要連到左肘」、「左肘要連到左腕」。 請在 mainwindow.cpp 的上方（迴圈外），建立一個結構體與陣列來定義這些連線規則與專屬顏色：

 

 

修改模型載入

在建構子中，套用新的骨架模型設定。我們這次不需要認人，所以 dwFlags 可以設定為軌跡追蹤即可：

 

OpenCV 動態連線繪圖與「防呆機制」

當我們順利取得 AI 回傳的結構體後，接下來的重頭戲就是使用 OpenCV API 將骨架疊加在影像上。

在這裡，我們將導入「先線後點」繪圖心法，並利用程式設計中的 continue 提早返回技巧，將「防呆機制」寫得極度優雅。繪圖 S.O.P 如下：

1. 畫出骨骼連線 ( 先畫線再畫點，避免點被線覆蓋 ) : 利用我們定義好的 bones 字典，將相連的關鍵點畫上線條。這裡有一個極為重要的細節：請務必先畫線！ 如果先畫圓點再畫線，粗曠的骨骼線條就會把精緻的關節點給蓋過去，導致畫面看起來不夠立體。

2. 畫出關節圓點 ( 導入 Early Return 防呆過濾 ) : 在每一個關鍵點座標上使用 cv::circle 畫出實心圓。為了避免將因遮擋而導致「信心值過低」或「座標為 0」的無效點畫在畫面上，我們實作了 continue 條件過濾：只要不符合規定，就直接跳過不畫！

最終驗證

請按下左下角的「Build and RUN」 執行專案：

1. 啟動接收與偵測。

2. 請您或身旁的人站到鏡頭前，揮揮手、抬抬腳，甚至是做幾個伸展動作。

 

➤ 溫馨小叮嚀 ( 非常重要 ) : 在您第一次開啟這支軟體 ( 執行程式 ) 的瞬間，介面可能會需要稍等一下才會顯示出來，請不要緊張！這是因為我們將「 載入 AI 模型 」的邏輯寫在了程式的建構子內。模型在首次執行時必須進行初始化配置，此時系統正努力將龐大的神經網路權重檔載入到 GPU 中。只要軟體成功開啟（ 首次載入完成 ），代表 AI 大腦已經在背景準備就緒！後續當您再次開啟軟體時，就不需要這個初始化的等待時間了！

恭喜您！從這一步開始，您獲取的數據不再只是單純的 X 與 Y 座標，而是「 人體姿態 」的量化數據。這 17 個關鍵點正是打造「 行為分析 ( Behavior Analysis ) 」的核心基石。未來，只要進一步追蹤這些關鍵點在連續影像與時間軸上的變化，您就能將應用延伸至智慧長照的「 跌倒偵測預警 」，或是運動訓練的「 姿態分析 」等商用級進階 AI 領域了！