10-9 人臉辨識功能範例教學
在前面的章節中，我們已經學會了如何讓 AI 找出畫面中的「 人、車、火、甚至任何物品 」。但您有沒有想過：AI 只能告訴我們「 這裡有一張臉 」，卻無法告訴我們「 這張臉是誰 」？
本章節將帶您進入影像分析最核心的應用領域——人臉辨識 ( Face Recognition )。 我們將導入強大的人臉辨識模型，它不僅能鎖定人臉，還能精準抓出五官關鍵點、判斷年齡跟性別，最重要的是：它能提取出人臉的專屬特徵向量！搭配我們即將實作的 UI 彈出視窗，您將能親手打造出一套點擊畫面就能註冊姓名，並自動迎賓的 VIP 辨識系統！
學習目標
透過本章節，您將學會 ：
1. API 參數大升級 ：掌握 QDEEP_OBJECT_DETECT_FLAG_FULL 旗標的物理意義。
2. 結構體進階解析 ：從 AI 回傳結果中提取 5 個五官座標與年齡、性別資訊。
3. OpenCV 繪圖大翻新 ：實作 cv::circle 畫出五官點，並利用 cv::getTextSize 繪製帶有完美底色的文字標籤。
4. 掌握特徵比對 API 與 UI 互動 ：實作滑鼠點擊註冊，並運用 QDEEP_GET_OBJECT_RECOGNITION_COMPARISON 進行特徵相似度計算，完成身分驗證邏輯。
準備工作
這次的模型包與以往稍微不同，因為它結合了多個辨識權重檔，所以檔案會比較多。請找到 Face Landmark 5KPS 模型壓縮檔（檔名可能標示為 FACE.LANDMARK.5KPS 相關字樣），將其解壓縮後，把裡面的 QDEEP.OD.FACE.LANDMARK.5KPS.CFG ( 設定檔 ) 以及所有對應的權重檔，一併複製到您 Qt 專案的建置輸出目錄下即可。
核心 API 要怎麼改？
這次在建立偵測器時，有幾個與以往截然不同的細節必須注意：
• 模型配置類型的改變 ：在 QDEEP_CREATE_OBJECT_DETECT 的第三個參數，請務必換成專屬的 QDEEP_OBJECT_DETECT_CONFIG_MODEL_FACE_LANDMARK_5_KEYPOINTS。
• dwFlags 參數 ：我們以前都是傳入軌跡追蹤 (_FLAG_TRAJECTORY_TRACKING)。但這次為了讓 AI 不只畫框，還要幫我們算出演算特徵值與五官點，我們必須將最後一個參數修改為 QDEEP_OBJECT_DETECT_FLAG_FULL！這會命令引擎火力全開，將所有的子屬性都計算出來回傳給我們。
• 回傳結構體的隱藏寶藏 ：雖然還是使用 QDEEP_OBJECT_DETECT_BOUNDING_BOX 結構體，但在 dwFlags 參數開啟多種功能的加持下，裡面有兩個隱藏數據被啟動了：
‧ nClassIDs ：這個陣列存放了附屬屬性，在目前這個模型中，存放的正是 AI 判斷出來的性別！
‧ nSubClassIDs ：這個陣列存放了附屬屬性，在目前這個模型中，存放的正是 AI 判斷出來的年齡！
‧ sKeypoints ：這是一個陣列，裝載了人臉的 5 個關鍵點（雙眼、鼻子、嘴角）的 X 與 Y 座標。
QDEEP_CREATE_OBJECT_DETECT
這是建立 AI 引擎並載入大腦（模型）的最關鍵 API。使用者必須透過此 API 初始化偵測器。
QDEEP_GET_OBJECT_RECOGNITION_COMPARISON
將兩個不同的特徵向量（例如：即時拍到的臉 vs. 註冊名冊裡的臉）丟給這支 API，它會瞬間回傳兩者的相似度分數。
QDEEP_OBJECT_DETECT_BOUNDING_BOX 結構體
換了人臉辨識的模型後，AI 引擎透過 QDEEP_OBJECT_DETECT_BOUNDING_BOX 回傳的 nClassID、nSubClassIDs、sKeypoints 將會有全新的物理意義。
QDEEP_OBJECT_DETECT_KEYPOINT 結構體
在啟動了全功率旗標 (FLAG_FULL) 之後，QDEEP_OBJECT_DETECT_BOUNDING_BOX 中會解鎖一個名為 sKeypoints[ QDEEP_MAX_KEYPOINY_SIZE ] 的陣列。這陣列裡的每一個元素，都是一個專門用來描述單一「 特徵點 」的結構體 ：QDEEP_OBJECT_DETECT_KEYPOINT。
它的內部包含了四個極具價值的參數，詳細定義如下 ：
撰寫核心程式碼
請開啟您的專案，我們來進行最核心的程式碼修改：
新增儲存特徵向量的資料結構
要讓 AI 認得人，我們必須在記憶體中建立一個「 名冊 」。請在 mainwindow.h 中宣告一個結構體來綁定「 名字 」與「 特徵向量 」，並設定比對的門檻值 ：
修改模型載入
在建構子中，套用我們剛剛提到的「 模型設定 」與「 全功率 Flag 」：
擴充類別名稱
在畫圖迴圈前，我們先定義好男生與女生的專屬顏色：0 : 男生 Male ( 綠色 )、1 : 女生 Female ( 紅色 )
OpenCV 繪圖與特徵比對邏輯
當我們從 AI 引擎取得物件的詳細資訊後，我們就可以開始利用 OpenCV API 來標記畫面了。但由於這次是「 人臉辨識 」，在畫圖之前我們必須先完成核心的「特徵比對」。定義了以下四個標準開發步驟：
1. 取得臉部特徵向量 ：在啟動 FLAG_FULL 的狀態下，AI 會將該張人臉的獨有特徵，存放在結構體的 fFeatureVectors 陣列中。
2. 進行特徵比對尋找最吻合者 ：利用 QDEEP_GET_OBJECT_RECOGNITION_COMPARISON，將「 即時特徵向量 」與名冊 (m_registeredFaces) 裡的特徵逐一進行運算。只要回傳的相似度分數大於我們設定的門檻值 ( 例如 : 0.75 )，就能成功認出這位 VIP！
3. 取得物件位置並使用 OpenCV 標記 ：取得比對結果與人臉座標後，我們畫出追蹤框、以及 5 個五官關鍵點。
4. 疊加包含物件資訊的文字 ：將比對出來的「 姓名、信心度、性別、年齡 」等綜合資訊，完美疊加在畫面上的底色框中。
加入 UI 彈出視窗與特徵註冊機制
要怎麼把「 陌生人 」變成「 熟人 」？我們必須攔截畫布的滑鼠點擊事件！ 當我們「 點擊畫面上的人臉框 (Click on a face box) 」時，我們就可以從結構體中取出它的特徵向量，並配對輸入的名字。您可以覆寫 Qt 的 mousePressEvent，並加入類似以下的邏輯概念：
最終驗證
請按下左下角的 「Build and RUN」 執行專案 ：
1. 啟動接收與偵測後，您會看到畫面上的人臉被框住，並且精準地在雙眼、鼻子、嘴角畫上了 5 個圓點！文字框則會顯示出 AI 判斷的年齡 ( Age )，人臉框色會顯示男生( 綠色 )或女生( 紅色 )。
2. 接著，用滑鼠點擊畫面上您的臉。
3. 畫面會瞬間彈出一個 UI 輸入視窗 (QInputDialog)。請輸入您的名字並按下確定。
4. 下一秒鐘，您頭上的標籤就會從 "Age: 27" 瞬間變成 "Arya (Age: 27)"！
➤ 溫馨小叮嚀 ( 非常重要 ) ： 在您第一次開啟這支軟體 ( 執行程式 ) 的瞬間，介面可能會需要稍等一下才會顯示出來，請不要緊張！這是因為我們將「 載入 AI 模型 」的邏輯寫在了程式的建構子內。模型在首次執行時必須進行初始化配置，此時系統正努力將龐大的神經網路權重檔載入到 GPU 中。只要軟體成功開啟（ 首次載入完成 ），代表 AI 大腦已經在背景準備就緒！後續當您再次開啟軟體時，就不需要這個初始化的等待時間了！
無論您在鏡頭前怎麼走動、甚至稍微轉頭，系統都會透過深層的特徵向量牢牢記住您！
恭喜您！透過這個章節，您已經完美融合了 API 參數操作、OpenCV 進階繪圖、以及 Qt UI 的互動邏輯。您開發出的這套程式，已經完全具備了成為智慧門禁的雛形！