steven0226/fall-guard-cv-xgboost

fall-guard-cv：居家跌倒偵測 XGBoost 分類器

這是「fall-guard-cv」居家跌倒偵測專案的分類器權重。這個專案的目標是用電腦視覺技術做一個平時完全在本機運作、只在真的偵測到跌倒時才通報家人的系統，回應高齡長輩獨居時常見的照護擔憂。

模型說明

• 輸入：54 維視窗統計特徵（來自 YOLO26-pose 17 個關鍵點衍生出的軀幹角、質心垂直速度、bbox 長寬比、髖高等 9 個基礎特徵，各自取 mean / std / min / max / last−first / max|Δ| 六種統計量，對應 1.5 秒滑動視窗）
• 輸出：二元分類（該視窗是否為跌倒瞬間）
• 架構：XGBoost，淺樹（max_depth=4）、200 棵樹，scale_pos_weight 依訓練折內類別比例調整
• 訓練資料：UR Fall Detection Dataset（URFD），30 段跌倒 + 40 段日常活動（ADL），Microsoft Kinect 拍攝

評估結果（Leave-One-Subject-Out，視窗級）

折	Precision	Recall	F1
P1	0.609	0.913	0.730
P2	0.575	0.913	0.706
P3	0.611	1.000	0.759
P4	1.000	0.444	0.615
P5	1.000	0.667	0.800

同一份資料上，經過折內調參的規則式（角度/速度閾值）baseline 整體略優，但 XGBoost 在部分折的 recall 更高，兩者錯誤模式不同。完整評估方法論（受試者級防洩漏切分、視窗級/事件級雙指標、誤報案例分析、跟規則式方法的完整對照）與 SHAP 特徵重要度分析請見主專案的開發文件。

授權與使用限制

本模型以 CC BY-NC-SA 4.0 授權釋出——訓練資料 URFD 本身為非商業授權（CC BY-NC-SA 4.0），故衍生模型比照相同限制，僅建議供研究／非商業用途使用。

引用：

Bogdan Kwolek, Michal Kepski, "Human fall detection on embedded platform using depth maps and wireless accelerometer," Computer Methods and Programs in Biomedicine, 117(3), Dec 2014.

檔案說明

檔案	用途
xgb_final.json	用全部 70 段影片訓練的最終部署模型（實際使用請用這個）
xgb_fold_P1.json ~ xgb_fold_P5.json	LOSO 五折的評估用模型（供重現上表分數，不建議直接部署——各折只用了部分資料訓練）
xgb_loso_results.json	訓練當下輸出的完整逐折指標
shap_summary.png	SHAP 特徵重要度摘要圖

讀取方式

import xgboost as xgb

booster = xgb.Booster()
booster.load_model("xgb_final.json")

# X: (N, 54) 的特徵矩陣，欄位順序需與訓練時的 54 維視窗統計特徵一致
proba = booster.predict(xgb.DMatrix(X))