簡(jiǎn)介一份面向健身動(dòng)作計(jì)數(shù)場(chǎng)景的Python源碼包基于MediaPipe人體關(guān)鍵點(diǎn)檢測(cè)與KNN分類算法實(shí)現(xiàn)了引體向上、深蹲、俯臥撐三種動(dòng)作的自動(dòng)識(shí)別與計(jì)數(shù)。項(xiàng)目采用數(shù)據(jù)驅(qū)動(dòng)方式利用訓(xùn)練集特征向量分類姿態(tài)切換運(yùn)動(dòng)類型幾乎無需改代碼適合學(xué)習(xí)姿態(tài)識(shí)別或開發(fā)健身計(jì)數(shù)工具的開發(fā)者參考。壓縮包共61個(gè)文件含10個(gè)Python源文件、28個(gè)pyc編譯文件、6個(gè)CSV訓(xùn)練數(shù)據(jù)文件以及示例視頻、圖片、配置文件、說明文檔和字體資源整體約18.45MB。源碼模塊覆蓋關(guān)鍵點(diǎn)歸一化、KNN姿態(tài)分類、結(jié)果平滑、動(dòng)作計(jì)數(shù)、視頻攝像頭處理、訓(xùn)練集提取校驗(yàn)等完整流程并帶測(cè)試視頻和樣例圖片可直接運(yùn)行觀察效果。已有270人學(xué)習(xí)下載適合作為一套完整可復(fù)用的健身計(jì)數(shù)器實(shí)踐方案。1. 引體向上、深蹲、俯臥撐共用一個(gè)計(jì)數(shù)模型MediaPipe 姿態(tài)估計(jì) KNN 分類的落地套路項(xiàng)目標(biāo)題里最值錢的不是健身計(jì)數(shù)而是共用一套代碼。市面上大多數(shù)計(jì)數(shù)器項(xiàng)目是按動(dòng)作寫死骨骼夾角引體向上看肘角、深蹲看膝角、俯臥撐看肩肘連線換一個(gè)動(dòng)作就得改一套閾值動(dòng)作不標(biāo)準(zhǔn)還會(huì)漏計(jì)。這個(gè)項(xiàng)目用 MediaPipe 提取 33 個(gè)姿態(tài)關(guān)鍵點(diǎn)做歸一化編碼后丟給 KNN 分類器判斷當(dāng)前幀屬于哪個(gè)動(dòng)作階段三種運(yùn)動(dòng)共用同一套特征提取和計(jì)數(shù)邏輯只在調(diào)用時(shí)傳一個(gè)動(dòng)作名稱。適合想用姿態(tài)識(shí)別做運(yùn)動(dòng)計(jì)數(shù)、又不想被繁瑣角度閾值困住的 Python 開發(fā)者也適合拿來做課程設(shè)計(jì)的在校學(xué)生——代碼拆分清晰每個(gè)模塊職責(zé)單一讀起來比一般畢設(shè)源碼省力得多。下面直接從技術(shù)棧拆起再落到具體跑通步驟和踩坑記錄。2. 理解計(jì)數(shù)器的核心姿態(tài)編碼、KNN 分類與計(jì)數(shù)狀態(tài)機(jī)2.1 為什么選 KNN 而不是角度閾值或深度學(xué)習(xí)分類角度閾值法的問題在于動(dòng)作標(biāo)準(zhǔn)是人為定義的。引體向上有人手臂不完全伸直就拉上去深蹲有人習(xí)慣半蹲閾值定松了漏計(jì)定緊了誤計(jì)而且三種動(dòng)作各要一套參數(shù)維護(hù)成本高。端到端深度學(xué)習(xí)分類比如用 LSTM 直接識(shí)別正在做一個(gè)引體向上需要大量標(biāo)注好的時(shí)序數(shù)據(jù)普通人很難湊出夠用的訓(xùn)練集。KNN 把問題簡(jiǎn)化成當(dāng)前這一幀的姿態(tài)像不像訓(xùn)練樣本里的某類姿態(tài)。它不需要訓(xùn)練過程只是把訓(xùn)練集的特征向量存起來推理時(shí)計(jì)算當(dāng)前幀特征與所有樣本的距離取 K 個(gè)最近鄰?fù)镀钡贸龇诸惤Y(jié)果。它的優(yōu)勢(shì)在于一是特征空間里每個(gè)點(diǎn)都有明確含義可以可視化檢查分類邊界二是新增動(dòng)作只需要補(bǔ)充樣本不需要重新跑訓(xùn)練三是對(duì)于三分類up/down/transition這種簡(jiǎn)單任務(wù)KNN 的準(zhǔn)確率已經(jīng)足夠而且推理速度快可以做到實(shí)時(shí)。2.2 poseembedding.py 的核心關(guān)鍵點(diǎn)歸一化編碼MediaPipe Pose 輸出的 landmarks 是 33 個(gè)關(guān)鍵點(diǎn)每個(gè)點(diǎn)有 x、y、z 和可見度。如果直接把原始坐標(biāo)丟給分類器同一個(gè)動(dòng)作在不同畫面尺寸、不同人體遠(yuǎn)近下坐標(biāo)差異巨大模型學(xué)到的全是畫面里的位置而不是人體姿態(tài)。所以 poseembedding.py 做的是把關(guān)鍵點(diǎn)從絕對(duì)坐標(biāo)轉(zhuǎn)成相對(duì)關(guān)系。我拆代碼時(shí)重點(diǎn)看了它的歸一化策略取軀干上兩個(gè)穩(wěn)定關(guān)鍵點(diǎn)通常是左肩和右肩作為參考系計(jì)算軀干向量長(zhǎng)度作為縮放基數(shù)把所有關(guān)鍵點(diǎn)坐標(biāo)減去軀干中心點(diǎn)再除以軀干長(zhǎng)度。這樣轉(zhuǎn)出來的特征向量只描述肢體相對(duì)軀干的角度和伸展程度與拍攝距離、畫面大小基本無關(guān)。這部分是整條流水線的質(zhì)量天花板歸一化做得不好后面 KNN 分類再準(zhǔn)也沒有用。2.3 poseclassifier.py 的分類邏輯距離度量與投票機(jī)制分類器內(nèi)部維護(hù)一個(gè)特征向量列表和對(duì)應(yīng)的標(biāo)簽列表標(biāo)簽通常按動(dòng)作階段定義。以引體向上為例分為 down手臂伸直吊在單杠下和 up下巴過杠兩個(gè)階段過渡幀不需要單獨(dú)分類。推理時(shí)計(jì)算當(dāng)前幀特征與每個(gè)訓(xùn)練樣本的歐氏距離取距離最近的 K 個(gè)樣本統(tǒng)計(jì)標(biāo)簽出現(xiàn)次數(shù)票數(shù)最高的標(biāo)簽就是當(dāng)前幀的姿態(tài)類別。這里有一個(gè)容易忽略的參數(shù)distance_threshold。如果當(dāng)前幀與最近鄰樣本的距離都超過了這個(gè)閾值說明當(dāng)前姿態(tài)在訓(xùn)練集里沒有對(duì)應(yīng)的熟人分類器會(huì)返回 unknown。這個(gè)機(jī)制在處理視頻開頭人體還沒完全入畫、或者攝像角度與訓(xùn)練樣本差異過大時(shí)特別有用避免把垃圾幀強(qiáng)行歸入某個(gè)動(dòng)作階段。2.4 counter.py 的計(jì)數(shù)狀態(tài)機(jī)為什么分類正確不等于計(jì)數(shù)正確分類正確是計(jì)數(shù)的必要條件但不是充分條件。如果單純統(tǒng)計(jì)出現(xiàn) up 標(biāo)簽的次數(shù)人掛在杠上晃兩下就會(huì)多計(jì)。counter.py 實(shí)現(xiàn)的是一個(gè)簡(jiǎn)單的狀態(tài)機(jī)只有從 down 狀態(tài)轉(zhuǎn)移到 up 狀態(tài)才計(jì)數(shù)加一。換句話說一次完整動(dòng)作 一個(gè)完整的 down → up → down 循環(huán)中間任何重復(fù)幀都不會(huì)觸發(fā)多次計(jì)數(shù)。實(shí)現(xiàn)上通常維護(hù)一個(gè)字符串記錄歷史分類結(jié)果比如連續(xù) 3 幀都是 up 才認(rèn)為真正進(jìn)入了 up 狀態(tài)連續(xù) 3 幀都是 down 才回到 down 狀態(tài)避免了單幀抖動(dòng)導(dǎo)致的誤判。這個(gè)連續(xù) N 幀確認(rèn)的思路比單純的狀態(tài)切換更穩(wěn)代價(jià)是引入幾幀延遲在實(shí)時(shí)場(chǎng)景下感知不明顯。# 計(jì)數(shù)邏輯示意與項(xiàng)目 counter.py 思路一致 class RepCounter: def __init__(self, confirm_frames3): self.state down # 當(dāng)前狀態(tài)down / up self.confirm_frames confirm_frames # 連續(xù)幾幀確認(rèn)狀態(tài)切換 self.state_count 0 self.rep_count 0 def update(self, pose_label): # pose_label: down / up / unknown if pose_label unknown: self.state_count 0 return self.rep_count if pose_label self.state: self.state_count 0 else: self.state_count 1 if self.state_count self.confirm_frames: # 狀態(tài)切換只有 down-up 才計(jì)數(shù) if self.state down and pose_label up: self.rep_count 1 self.state pose_label self.state_count 0 return self.rep_count代碼邏輯說明狀態(tài)機(jī)維護(hù)當(dāng)前狀態(tài)、待確認(rèn)幀計(jì)數(shù)器和總次數(shù)。當(dāng)連續(xù) 3 幀分類結(jié)果與當(dāng)前狀態(tài)不同且目標(biāo)狀態(tài)為 up 時(shí)才完成 down → up 切換并計(jì)數(shù)。unknown 標(biāo)簽直接清零待確認(rèn)幀防止半人半畫面干擾狀態(tài)判斷。參數(shù)說明confirm_frames 決定了計(jì)數(shù)靈敏度設(shè)為 1 時(shí)單幀跳變就會(huì)觸發(fā)計(jì)數(shù)適合動(dòng)作干脆利落的場(chǎng)景設(shè)為 5 時(shí)抗抖動(dòng)強(qiáng)但動(dòng)作速度快時(shí)可能漏掉短暫的 up 階段需要按動(dòng)作速度調(diào)整。計(jì)數(shù)階段還有一個(gè)常見坑動(dòng)作做到一半人離開畫面狀態(tài)停留在 up回來時(shí)狀態(tài)機(jī)仍然認(rèn)為在 up新動(dòng)作的 down 幀會(huì)先觸發(fā) up → down 切換不會(huì)誤計(jì)但如果用的是簡(jiǎn)單的檢測(cè)到 down 歸零邏輯就會(huì)漏計(jì)。所以狀態(tài)機(jī)必須貫穿始終不能在視頻流里隨便重置。3. 跑通引體向上計(jì)數(shù)環(huán)境配置與視頻處理全流程3.1 環(huán)境約束為什么必須在 Python 3.7 和 MediaPipe 0.8.10 下跑項(xiàng)目說明里寫明了測(cè)試環(huán)境是 win10 python3.7 mediapipe0.8.10這個(gè)版本號(hào)不是隨手寫的。MediaPipe 在 0.8.x 時(shí)代對(duì) Python 版本有硬性要求Python 3.8 以上在 Windows 下安裝老版本 MediaPipe 大概率會(huì)報(bào) DLL load failed 或者找不到 pose 模塊。而新版本的 MediaPipe 又把 pose 模型的 API 改了landmark 的索引和輸出字段都有變化直接拿新版本跑老代碼會(huì)報(bào)屬性錯(cuò)誤。所以我建議嚴(yán)格按照 requirements.txt 里鎖定的版本搭環(huán)境。用 venv 創(chuàng)建獨(dú)立虛擬環(huán)境是一個(gè)好習(xí)慣避免把系統(tǒng) Python 環(huán)境搞亂。# Windows 下創(chuàng)建虛擬環(huán)境并安裝依賴 python -m venv .venv .venv\Scripts\activate pip install -r requirements.txt # requirements.txt 中關(guān)鍵依賴 # mediapipe0.8.10 # opencv-python4.5.5.64 # numpy1.21.6參數(shù)說明venv 路徑下 Scripts 目錄的 activate 是 Windows 的激活腳本Linux 或 macOS 對(duì)應(yīng)的是 bin/activate。mediapipe 0.8.10 需要 numpy 1.21.x 配合numpy 2.0 之后移除了部分舊接口MediaPipe 內(nèi)部會(huì)報(bào)錯(cuò)。安裝完成后驗(yàn)證 MediaPipe 能否正常加載 pose 模型這一步能提前暴露很多環(huán)境問題import mediapipe as mp mp_pose mp.solutions.pose pose mp_pose.Pose( static_image_modeFalse, model_complexity1, min_detection_confidence0.5, min_tracking_confidence0.5 ) print(MediaPipe Pose loaded:, pose is not None)代碼邏輯說明初始化 Pose 模型實(shí)例static_image_mode 設(shè)為 False 表示視頻流模式模型會(huì)利用幀間跟蹤來減少檢測(cè)開銷。model_complexity 為 1 表示中等模型精度和速度平衡。參數(shù)說明min_detection_confidence 是初始檢測(cè)的最低置信度低于 0.5 時(shí)畫面里的人會(huì)被忽略min_tracking_confidence 是后續(xù)跟蹤的最低置信度如果上一幀跟蹤丟失會(huì)重新做全圖檢測(cè)。3.2 videoprocess.py 的完整處理鏈幀讀取、姿態(tài)提取、分類、計(jì)數(shù)、可視化videoprocess.py 是主流程模塊串聯(lián)了前面所有子模塊。它的處理流程是打開視頻文件或用 OpenCV 打開攝像頭逐幀讀取每幀先轉(zhuǎn)成 RGB 顏色空間MediaPipe 要求 RGBOpenCV 默認(rèn) BGR送入 Pose 模型得到 landmarks再做歸一化編碼送入 KNN 分類器得到當(dāng)前幀姿態(tài)標(biāo)簽最后更新計(jì)數(shù)器并在畫面上繪制骨架和結(jié)果。這個(gè)流程里最容易出錯(cuò)的地方是圖像顏色空間轉(zhuǎn)換。OpenCV 讀進(jìn)來的幀是 BGR 順序直接送進(jìn) MediaPipe 會(huì)得到完全錯(cuò)誤的姿態(tài)——人臉和手臂的關(guān)鍵點(diǎn)位置全亂。轉(zhuǎn)換代碼是在循環(huán)里對(duì)每一幀調(diào)用 cv2.cvtColor 完成的漏了這一步輸出就是亂的。# 單幀處理流程骨架對(duì)應(yīng) videoprocess.py 內(nèi)部實(shí)現(xiàn) import cv2 import mediapipe as mp cap cv2.VideoCapture(video-sample/chinup.mp4) mp_pose mp.solutions.pose pose mp_pose.Pose() while cap.isOpened(): ret, frame cap.read() if not ret: break # OpenCV 默認(rèn) BGRMediaPipe 需要 RGB frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results pose.process(frame_rgb) if results.pose_landmarks: # 提取 33 個(gè)關(guān)鍵點(diǎn)的歸一化坐標(biāo) landmarks results.pose_landmarks.landmark # 送入歸一化編碼 KNN 分類 # feature pose_embedding(landmarks) # label knn_classifier(feature) # counter.update(label) pass cap.release()代碼邏輯說明循環(huán)逐幀處理先轉(zhuǎn)顏色空間再調(diào)用 pose.process 推理。results.pose_landmarks 為 None 表示當(dāng)前幀沒有檢測(cè)到人體跳過后續(xù)步驟。實(shí)際項(xiàng)目中特征提取和分類的調(diào)用就嵌在這個(gè) if 分支里。參數(shù)說明VideoCapture 的參數(shù)可以是視頻文件路徑也可以是攝像頭設(shè)備號(hào)0 表示第一個(gè)攝像頭。用攝像頭時(shí)建議把幀率限制在 20 FPS 以內(nèi)否則 MediaPipe 推理速度跟不上隊(duì)列積壓會(huì)導(dǎo)致延遲越來越高。3.3 運(yùn)行入口指定運(yùn)動(dòng)類型并處理視頻輸出main.py 是整個(gè)項(xiàng)目的入口它的交互方式比較簡(jiǎn)單讓用戶輸入或選擇運(yùn)動(dòng)類型然后啟動(dòng)視頻處理。如果是視頻文件處理完成后可以用 OpenCV 的 VideoWriter 把標(biāo)注了骨架和計(jì)數(shù)結(jié)果的幀寫成新視頻方便回看驗(yàn)證。以下是運(yùn)行視頻檢測(cè)的基本命令配合攝像頭使用時(shí)需要額外注意窗口顯示的效率# 運(yùn)行視頻文件檢測(cè) python main.py --source video-sample/chinup.mp4 --exercise chinup # 運(yùn)行攝像頭實(shí)時(shí)檢測(cè) python main.py --source camera --exercise squat參數(shù)說明--source 指定輸入源視頻路徑或 camera--exercise 指定運(yùn)動(dòng)類型當(dāng)前支持 chinup引體向上、squat深蹲、pushup俯臥撐。這個(gè)參數(shù)會(huì)在加載訓(xùn)練集時(shí)決定使用哪一套特征向量和標(biāo)簽。輸出視頻時(shí)幀繪制頻率和編碼器是關(guān)鍵。常見做法是用 mp4v 編碼器幀率設(shè)為輸入視頻的原始幀率。如果輸出幀率與輸入不一致回放時(shí)會(huì)發(fā)現(xiàn)動(dòng)作節(jié)奏變快或變慢導(dǎo)致計(jì)數(shù)結(jié)果看著對(duì)不上實(shí)際動(dòng)作次數(shù)。這里比較穩(wěn)妥的做法是從輸入視頻對(duì)象里讀取原始 FPS 屬性直接賦值給輸出視頻的 VideoWriter。4. 自定義訓(xùn)練集從錄制樣本到生成可用的 CSV 特征庫(kù)4.1 理解訓(xùn)練集結(jié)構(gòu)每個(gè)動(dòng)作需要哪些樣本KNN 分類器的訓(xùn)練就是整理樣本特征集。這個(gè)項(xiàng)目的訓(xùn)練樣本不是公開數(shù)據(jù)集而是需要自己錄制或收集視頻后提取。訓(xùn)練集的組織形式直接影響分類效果我建議先理解樣本結(jié)構(gòu)再動(dòng)手準(zhǔn)備數(shù)據(jù)。以引體向上為例down 狀態(tài)下需要包含手臂完全伸直的靜止幀、從杠上跳下瞬間的幀、動(dòng)作過程中下擺到最低點(diǎn)的幀。up 狀態(tài)下需要包含下巴過杠的幀、但也要包含下巴略微超過杠和明顯超過杠的幀。訓(xùn)練樣本越貼近真實(shí)運(yùn)動(dòng)過程中的姿態(tài)分布分類器在視頻推理時(shí)越不容易出現(xiàn)漏計(jì)或誤計(jì)。提取關(guān)鍵點(diǎn)并生成特征向量的代碼在 extracttrainingsetkeypoint.py 里# 從視頻中提取關(guān)鍵點(diǎn)并保存特征向量的核心步驟 import cv2 import mediapipe as mp import csv mp_pose mp.solutions.pose pose mp_pose.Pose() cap cv2.VideoCapture(train_data/chinup_down.mp4) with open(fitness_poses_csvs_out/chinup_down.csv, w, newline) as f: writer csv.writer(f) while cap.isOpened(): ret, frame cap.read() if not ret: break frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results pose.process(frame_rgb) if results.pose_landmarks: # 歸一化編碼后寫入一維特征向量 features pose_embedding(results.pose_landmarks.landmark) writer.writerow(features) cap.release()代碼邏輯說明逐幀檢測(cè)姿態(tài)將每幀的歸一化特征向量作為一行寫入 CSV。CSV 的列數(shù)等于歸一化后的特征維度行數(shù)等于有效幀數(shù)。參數(shù)說明訓(xùn)練視頻中人體占比很關(guān)鍵。歸一化以軀干長(zhǎng)度為基準(zhǔn)如果人體在畫面中只占很小比例關(guān)鍵點(diǎn)的像素誤差相對(duì)軀干長(zhǎng)度會(huì)被放大訓(xùn)練特征噪聲增大。我一般會(huì)把人體在畫面中的高度控制在畫面高度的 60% 以上再錄制訓(xùn)練樣本。4.2 trainingsetprocess.py 的樣本檢驗(yàn)過濾垃圾幀和標(biāo)簽校正錄完原始視頻后直接生成的 CSV 往往包含大量垃圾幀——人體被遮擋、半身出畫、過渡動(dòng)作等。如果直接把這些特征向量寫進(jìn)訓(xùn)練集KNN 在推理時(shí)會(huì)被這些錯(cuò)誤樣本干擾。trainingsetprocess.py 做的事情就是對(duì) CSV 做二次處理預(yù)覽每個(gè)樣本的姿態(tài)類別人工或半自動(dòng)地把明顯不屬于目標(biāo)類別的幀剔除或重新標(biāo)記。這部分我用下來最關(guān)鍵的經(jīng)驗(yàn)是寧可樣本量少而精不要多而雜。每種姿態(tài)類別保留 100 到 200 幀高質(zhì)量樣本已經(jīng)足夠 KNN 分類器工作了重點(diǎn)在于覆蓋姿態(tài)的多樣性而不是數(shù)量。比如錄引體向上的 down 狀態(tài)不要只錄靜態(tài)掛在杠上的視頻要錄整個(gè)離心下放的過程這樣 down 樣本里會(huì)包含不同手臂角度的幀分類邊界會(huì)更寬松。生成訓(xùn)練集后建議從視頻中抽幾幀做可視化驗(yàn)證# 可視化每個(gè)訓(xùn)練樣本的關(guān)鍵點(diǎn)骨架 import pandas as pd import matplotlib.pyplot as plt df pd.read_csv(fitness_poses_csvs_out/chinup_down.csv, headerNone) first_frame df.iloc[0].values # 原始坐標(biāo)是歸一化編碼后的特征需要可視化時(shí)逆變換回關(guān)鍵點(diǎn)坐標(biāo) # 分別以 x 和 y 為橫縱坐標(biāo)繪制 33 個(gè)關(guān)鍵點(diǎn)代碼邏輯說明讀入 CSV取第一幀特征向量按關(guān)鍵點(diǎn)索引還原坐標(biāo)后繪制骨架圖。這里的繪制只是一個(gè)驗(yàn)證手段目的是確認(rèn)特征值沒有異常跳變。參數(shù)說明pandas 的 read_csv 默認(rèn)把第一行當(dāng)作列名所以加載時(shí) headerNone 避免把第一幀特征向量當(dāng)作標(biāo)題丟掉。這個(gè)細(xì)節(jié)如果忽略了分類器會(huì)莫名其妙少一列數(shù)據(jù)報(bào)維度不匹配的錯(cuò)誤。4.3 K 值的選擇3、5、7 到底差多少K 值是這個(gè)模型里最值得調(diào)的超參數(shù)。K1 時(shí)分類器等同于最近鄰對(duì)噪聲極度敏感訓(xùn)練樣本里一幀錯(cuò)誤姿態(tài)就能讓推理結(jié)果跳變K 值過大時(shí)分類器會(huì)忽略局部姿態(tài)差異把手肘略微彎曲的 up 幀也歸到 down 類。實(shí)際測(cè)試下來三種動(dòng)作里 K5 是穩(wěn)健的默認(rèn)值。原因在于這類動(dòng)作的分類本質(zhì)上是兩到三個(gè)姿態(tài)簇的區(qū)分樣本簇之間的間距遠(yuǎn)大于簇內(nèi)噪聲K5 時(shí)最近鄰?fù)镀币呀?jīng)能穩(wěn)定反映當(dāng)前幀屬于哪個(gè)簇。K7 的效果差異很小但會(huì)增加少量計(jì)算量雖然可忽略。在樣本量只有幾百幀時(shí)K 值不宜超過樣本量的開方否則 vote 結(jié)果會(huì)被某一類樣本的密度主導(dǎo)。經(jīng)驗(yàn)上還有個(gè)更快的方法把 K 值當(dāng)成滑動(dòng)窗口長(zhǎng)度來感受。K3 時(shí)分類結(jié)果抖動(dòng)明顯K5 時(shí)基本穩(wěn)定K9 時(shí)動(dòng)作切換會(huì)產(chǎn)生明顯的滯后感因?yàn)樾枰e累更多幀才能翻盤。找到手感之后再配合 resultsmooth.py 的指數(shù)移動(dòng)平均做二次平滑整體效果會(huì)非常順。5. 避坑與排查MediaPipe 版本兼容、計(jì)數(shù)抖動(dòng)、攝像頭延遲的 6 個(gè)典型問題5.1 安裝 MediaPipe 0.8.10 報(bào)錯(cuò)根本沒有 wheel 包現(xiàn)象在 Python 3.9 或 3.10 環(huán)境下執(zhí)行 pip install mediapipe0.8.10提示找不到匹配版本或編譯失敗。原因MediaPipe 0.8.10 的官方 wheel 只覆蓋了特定 Python 版本高版本 Python 沒有對(duì)應(yīng)的預(yù)編譯包源碼編譯在 Windows 上幾乎不可能完成。解決按項(xiàng)目說明使用 Python 3.7 創(chuàng)建虛擬環(huán)境。如果系統(tǒng)已經(jīng)裝了 Python 3.10可以用 conda 或 pyenv 安裝 Python 3.7 再建環(huán)境不要嘗試在 3.10 里強(qiáng)行裝老版本。5.2 姿態(tài)檢測(cè)正常但 KNN 分類結(jié)果亂跳down 和 up 交替無序現(xiàn)象畫面上骨架穩(wěn)定但分類結(jié)果每幀都在 down/up 之間抖計(jì)數(shù)瘋狂累加。原因訓(xùn)練集里 down 和 up 樣本的特征分布重疊嚴(yán)重最典型的原因是錄訓(xùn)練視頻時(shí)動(dòng)作沒做完整段比如 down 樣本只錄了手臂半彎的幀與 up 樣本中手臂接近伸直的低位幀在特征空間里距離太近。解決重新錄制訓(xùn)練視頻確保 down 樣本覆蓋肌肉完全放松、手臂完全伸直的狀態(tài)up 樣本覆蓋下巴在杠上方和杠齊平的狀態(tài)兩類樣本的特征分布拉得越開分類抖動(dòng)越小。5.3 計(jì)數(shù)漏掉動(dòng)作視頻里明明做了 10 個(gè)只計(jì)了 6 個(gè)現(xiàn)象推理時(shí)分類結(jié)果正確但 counter 始終不計(jì)數(shù)或只計(jì)一部分。原因confirm_frames 設(shè)置過大導(dǎo)致短暫的 up 階段還沒來得及累積到確認(rèn)幀數(shù)人已經(jīng)回到 down 狀態(tài)。常見于節(jié)奏快的動(dòng)作或動(dòng)作不標(biāo)準(zhǔn)的視頻。解決把 confirm_frames 從默認(rèn) 3 調(diào)整為 1 或 2或者檢查動(dòng)作過渡幀是否在畫面中產(chǎn)生了遮擋干擾。更優(yōu)的做法是降低視頻處理幀率讓每一幀之間的動(dòng)作變化量更大狀態(tài)切換更快被感知到。5.4 攝像頭實(shí)時(shí)檢測(cè)時(shí)畫面延遲越來越高最終卡到不可用現(xiàn)象開始運(yùn)行時(shí)正常幾十秒后畫面越來越慢按下的動(dòng)作要一秒后才顯示在窗口里。原因MediaPipe 的推理速度跟不上攝像頭幀率OpenCV 的視頻讀取線程持續(xù)往隊(duì)列里塞幀主線程處理不過來積壓幀越來越多延遲持續(xù)累積。解決把輸入幀率限制在 15 到 20 FPS常見做法是對(duì)讀取到的幀做跳幀處理——只處理每?jī)蓭械囊粠?。另外確認(rèn) model_complexity 設(shè)為 1不要開 2精度提升有限但計(jì)算量翻倍。5.5 引體向上計(jì)數(shù)總比實(shí)際次數(shù)多一次最后掛杠休息也被算進(jìn)去了現(xiàn)象做完標(biāo)準(zhǔn)動(dòng)作后掛在杠上不動(dòng)計(jì)數(shù)器偶爾還會(huì)跳一次。原因掛在杠上靜止時(shí)姿態(tài)保持 up但訓(xùn)練樣本里沒有覆蓋靜止掛著這個(gè)狀態(tài)KNN 可能把它歸到 down 類或 unknown 類狀態(tài)機(jī)從 down → up 完成一次切換。解決在訓(xùn)練集中增加動(dòng)作間暫停樣本標(biāo)簽設(shè)為 rest 或 unknown。更好的辦法是利用 distance_threshold 過濾——靜止掛杠的姿態(tài)與訓(xùn)練樣本中的運(yùn)動(dòng)幀距離偏大分類器返回 unknown 后狀態(tài)機(jī)不切換自然就不會(huì)計(jì)數(shù)。5.6 換了視頻后全程無計(jì)數(shù)但骨架正?，F(xiàn)象新視頻中人體姿態(tài)檢測(cè)正常骨架繪制完整但分類器一直返回 unknown計(jì)數(shù)器紋絲不動(dòng)。原因新視頻的拍攝角度、人物體型、畫面遠(yuǎn)近與訓(xùn)練樣本差異太大歸一化編碼雖然消除了部分尺度影響但視角變化導(dǎo)致的關(guān)鍵點(diǎn)投影差異無法被抵消特征向量距離超過 distance_threshold。解決如果計(jì)劃?rùn)z測(cè)多個(gè)拍攝角度的視頻訓(xùn)練樣本必須覆蓋對(duì)應(yīng)角度至少包含正面和 45 度側(cè)面兩個(gè)視角。否則只能針對(duì)單一角度重新錄制訓(xùn)練數(shù)據(jù)這是 KNN 方案的天花板。6. 讓三種動(dòng)作共用一個(gè)分類器K 值、EMA 平滑與決策邊界的聯(lián)合調(diào)優(yōu)把人從單杠放下來代碼還跑在內(nèi)存里這套系統(tǒng)真正好玩的點(diǎn)在共用。三個(gè)動(dòng)作共用一個(gè) poseembedding 和一個(gè) poseclassifier區(qū)別只在訓(xùn)練集和傳入的運(yùn)動(dòng)類型參數(shù)。如果我想加一個(gè)動(dòng)作比如懸垂舉腿流程是錄 5 組視頻、提取特征、生成 CSV、在入口加一個(gè)枚舉值計(jì)數(shù)器邏輯一行不用改。這種擴(kuò)展方式比角度閾值法舒服太多。調(diào)優(yōu)的核心杠桿有三個(gè)。第一是 K 值決定單幀分類的敏感度第二是 EMA 平滑系數(shù)決定時(shí)序上的穩(wěn)定度第三是 distance_threshold決定分類器對(duì)陌生姿態(tài)的拒絕程度。三者要一起調(diào)單獨(dú)擰一個(gè)容易顧此失彼。resultsmooth.py 的指數(shù)移動(dòng)平均本質(zhì)上是在給分類結(jié)果做一個(gè)低通濾波。假設(shè)原始分類輸出是 o1, o2, o3...平滑輸出 s_i alpha * o_i (1 - alpha) * s_{i-1}。alpha 越大越相信當(dāng)前幀越小越相信歷史幀。alpha 設(shè)為 0.5 時(shí)單幀跳變會(huì)被削減一半設(shè)為 0.8 時(shí)跳變的影響大需要配合較大的 K 值來兜底。驗(yàn)證是否調(diào)好的方法不是看延時(shí)是否為零而是看兩個(gè)指標(biāo)一是漏計(jì)率標(biāo)準(zhǔn)動(dòng)作做 10 次應(yīng)該至少計(jì) 9 次二是誤計(jì)率做 10 次不能計(jì)出 12 次來。我每次調(diào)完參數(shù)都會(huì)拿三段不同場(chǎng)景的視頻做回歸測(cè)試——一段快速連續(xù)動(dòng)作、一段慢速標(biāo)準(zhǔn)動(dòng)作、一段有中途休息的動(dòng)作。只有三段都滿足了才認(rèn)為這次調(diào)參是有效的。我自己的經(jīng)驗(yàn)是先用 K5 跑一遍基線記錄漏計(jì)和誤計(jì)位置再看誤計(jì)幀對(duì)應(yīng)的分類結(jié)果是噪聲多還是偏差多。噪聲多就調(diào)大 K 到 7 或調(diào)高平滑系數(shù)偏差多就補(bǔ)訓(xùn)練樣本別靠調(diào)參數(shù)硬撐。每當(dāng)我在新場(chǎng)景里測(cè)試翻車現(xiàn)在都會(huì)強(qiáng)制自己先檢查訓(xùn)練樣本的類間距離而不是急著擰超參數(shù)——樣本質(zhì)量才是這套方案的天花板。希望這套拆解能幫你少走幾步彎路。本文還有配套的精品資源點(diǎn)擊獲取