README.md

---
title: Fall Detection Demo
emoji: "🚨"
colorFrom: blue
colorTo: red
sdk: gradio
sdk_version: "5.50.0"
app_file: app.py
pinned: false
license: cc-by-nc-4.0
hardware: zero-a10g
---

# Fall Detection Demo

YOLOv11-Pose + ST-GCN 2-stage 파이프라인을 사용한 실시간 낙상 감지 데모입니다.

## 파이프라인 구성

- **Stage 1: Pose Estimation** - YOLOv11m-pose
  - 입력: 비디오 프레임
  - 출력: 17개 COCO keypoints (x, y, confidence)

- **Stage 2: Temporal Classification** - ST-GCN
  - 입력: 60 프레임 슬라이딩 윈도우 (2초 @ 30fps)
  - 출력: Fall/Non-Fall 확률

## 사용법

1. 비디오 파일을 업로드합니다 (MP4, AVI, MOV 지원)
2. 필요시 고급 설정에서 파라미터를 조정합니다
3. "분석 시작" 버튼을 클릭합니다
4. 결과 비디오와 확률 그래프를 확인합니다

## 파라미터 설명

- **낙상 판정 임계값 (Fall Threshold)**: 이 값 이상의 확률이면 낙상으로 판정 (기본값: 0.85, 권장: 0.8-0.9)
- **키포인트 표시 (Keypoint Mode)**:
  - `all`: 전체 17개 키포인트 표시
  - `major`: 주요 9개 키포인트만 표시 (코, 어깨, 엉덩이, 무릎, 발목)

## 모델 정보

| 모델 | 용도 | 파라미터 |
|------|------|----------|
| YOLOv11m-pose | Pose Estimation | ~25M |
| ST-GCN | Temporal Classification | ~3M |

## 성능

- **Latency**: ~2초 (60 프레임 윈도우 기준)
- **Accuracy**: 99.6% (AI Hub 검증 데이터셋)

## 모델 저장소

모델 파일은 Private HuggingFace Model 저장소에서 자동으로 다운로드됩니다.

- **저장소**: `YoungjaeDev/fall-detection-models` (Private)
- **파일**: `yolo11m-pose.pt`, `best_acc.pth`
- **토큰**: HF Spaces의 경우 `HF_TOKEN` Secret 설정 필요

## 로컬 실행

```bash
# 의존성 설치
pip install -r requirements.txt

# HuggingFace 로그인 (Private 모델 접근용)
huggingface-cli login

# 앱 실행
python app.py
```

로컬 개발 시 프로젝트 루트에 `yolo11m-pose.pt`와 `runs/stgcn_binary_exp2_fixed_graph/best_acc.pth`가 있으면 HF에서 다운로드하지 않고 로컬 파일을 사용합니다.

## 참고자료

- [YOLOv11 (Ultralytics)](https://github.com/ultralytics/ultralytics)
- [ST-GCN Paper](https://arxiv.org/abs/1801.07455)
- AI Hub 낙상사고 위험동작 영상-센서 쌍 데이터