10-11 手部關鍵點偵測功能範例教學

在上一章【10-10】中，我們拉遠了鏡頭，利用人形骨架關鍵點模型捕捉了人體的全身骨架，為「行為分析」打下了基礎。但如果我們想開發的是「手語翻譯機」、「非接觸式電梯按鈕 ( 虛擬滑鼠 )」或是「猜拳遊戲」呢？這時全身骨架的精度就不夠用了。

本章節，我們要把鏡頭「拉近」，聚焦在人體最精密、最靈活的部位——雙手！ 我們將導入手部關鍵點模型，它能在每一隻手上精準抓取出 21 個關鍵點（包含手腕與五根手指的各個關節）。最棒的是，得益於我們在上一章建立的優良 OpenCV 繪圖架構，您會發現這次的升級幾乎不費吹灰之力！

學習目標

透過本章節，您將學會：

1. 視角與模型轉換：從全身 (17點) 進入微觀的手部 (21點) 追蹤領域。
2. 建構手部連線字典：解析官方 21 個關鍵點的索引定義（手腕與五根手指的拓樸結構）。
3. 架構重用：完美沿用 10-10 的「先線後點」與「防呆過濾」S.O.P，體會 Clean Code 帶來的開發高效率！

準備工作

這次的模型包與以往稍微不同，因為它結合了多個辨識權重檔，所以檔案會比較多。請找到 Human Hand 21KPS 模型壓縮檔（檔名可能標示為 HUMAN.HAND.21KPS相關字樣），將其解壓縮後，把裡面的 QDEEP.OD.HUMAN.HAND.21KPS.LITE.CFG ( 設定檔 ) 以及所有對應的權重檔，一併複製到您 Qt 專案的建置輸出目錄下即可。

核心 API 要怎麼改？

這次的 API 邏輯與 10-10 完全一致，系統同樣會把抓到的點塞進 sKeypoints 陣列中。我們唯一要做的，就是修改建立偵測器時的參數：

• 模型配置類型的改變 : 在 QDEEP_CREATE_OBJECT_DETECT 中，請將 Enum 換成手部專屬的 QDEEP_OBJECT_DETECT_CONFIG_MODEL_HAND_LANDMARK_21_KEYPOINTS。

• 核心差異點 ( 17KPS vs 21KPS ) : 在 10-10 的全身模型中，一個畫面中的「一個人」會產生一組 17 個點的陣列。 但在 10-11 的手部模型中，AI 是以「手」為單位！畫面中的每一隻手（不論左右手），都會獨立產生一組包含 21 個點的 sKeypoints 陣列。

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。

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

撰寫核心程式碼

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

定義 21 點手部骨骼連線字典

手部的 21 個點可不是亂跳的，有著非常嚴謹的排列邏輯： 0 號是手腕，接著每 4 個點代表一根手指。請在 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 繪圖代碼。