웹캠 기반 자세 분석으로 거북목(Forward Head Posture) 위험도를 실시간 피드백하는 데스크톱 앱입니다.
- 실시간 랜드마크 추출: MediaPipe Pose Landmarker
- 혼합 측정 로직: 측면(귀-어깨 기하) + 정면(비율/깊이 보조)
- 경고/스트레칭 알림: 상태 지속 시간 기반
- 세션 기록/분석: JSON 저장 + 기간 리포트
docs/images/realtime.pngdocs/images/turtle-page.pngdocs/images/analysis-page.png
현재 저장소에는 예시 경로만 정의되어 있습니다.
python -m venv .venvWindows:
.venv\Scripts\activatemacOS / Linux:
source .venv/bin/activate패키지 설치:
pip install -r requirements.txt실행:
python main.pyFOZE/
main.py
config.py
requirements.txt
models/
pose_landmarker_lite.task
data/
sessions/
src/
pose_detector.py
posture_analyzer.py
alert_manager.py
stretch_guide.py
data_reporter.py
ui_renderer.py
popup_alert.py
주요 설정은 config.py에서 수정합니다.
| 항목 | 설명 | 기본값 |
|---|---|---|
TURTLE_NECK_ANGLE_THRESHOLD |
거북목 판정 각도 임계값 | 25.0 |
DATA_RECORD_INTERVAL |
세션 샘플링 주기(초) | 5.0 |
STRETCH_INTERVAL |
스트레칭 알림 간격(초) | 30 * 60 |
ALERT_WARNING_DELAY |
주의 경고 지연(초) | 3.0 |
ALERT_DANGER_DELAY |
위험 경고 지연(초) | 10.0 |
POSE_MIN_DETECTION_CONFIDENCE |
포즈 검출 신뢰도 임계 | 0.7 |
POSE_MIN_TRACKING_CONFIDENCE |
포즈 추적 신뢰도 임계 | 0.5 |
FOZE는 임상 진단 도구가 아니라 웰니스 피드백 도구입니다.
- 뷰 모드 자동 판별
- 귀 가시성, 어깨 폭/깊이 차이를 이용해 정면/측면을 자동 판별합니다.
- 측면 지표 (1차)
- 귀-어깨 기하로 목 기울기 각도를 계산합니다.
- 해석 참고:
CVA(대략) ≈ 90 - neck_angle.
- 정면 지표 (보조)
- 코-어깨 수직 비율, 귀-어깨 비율, z축 깊이 차이를 결합해 가상 목 각도로 변환합니다.
- 안정화
- EMA + median 필터, 프레임 급변 억제, 점수 히스테리시스로 떨림을 줄입니다.
Q/ESC: 종료S: 세션 저장R: 스트레칭 타이머 리셋P: 일시정지/재개B: 백그라운드 모드1/2/3: 페이지 전환
- 기본 동작은 프레임 이미지 저장 없이 수치 데이터만
data/sessions/*.json에 저장합니다. - 로그/리포트에는 개인 식별 이미지 저장을 권장하지 않습니다.
- 본 앱은 의료 진단 기기가 아니며, 통증/질환 의심 시 전문가 상담이 필요합니다.
Q. 카메라가 열리지 않습니다.
A. config.CAMERA_INDEX를 변경하고, 다른 앱(Zoom/Teams 등)의 카메라 점유를 해제하세요.
Q. 모델 파일 오류가 발생합니다.
A. models/pose_landmarker_lite.task 파일 존재를 확인하세요.
Q. 한글이 깨지거나 글꼴이 이상합니다.
A. config.FONT_PATH를 OS에 맞는 폰트 경로로 바꾸세요.
Q. 토스트 알림이 뜨지 않습니다.
A. 플랫폼/GUI 환경 제약일 수 있습니다. 이 경우 화면 오버레이 기반 알림 모드를 사용하세요.
Q. 데이터는 어디에 저장되나요?
A. 기본 경로는 data/sessions/ 입니다.
-
main.py:FOZEApp.run()
캡처/분석/렌더링/입력 루프 오케스트레이션 -
src/pose_detector.py:PoseDetector.detect()
프레임 -> 랜드마크 딕셔너리 변환 -
src/posture_analyzer.py:PostureAnalyzer.analyze()
정면/측면 판별, 거북목 지표 계산, 점수/상태 산출 -
src/alert_manager.py:update(),get_alert(),should_stretch()
경고 상태머신과 스트레칭 타이머 관리 -
src/data_reporter.py:record(),save_session(),load_period_report()
샘플링 저장과 기간별 통계 리포트 제공 -
src/ui_renderer.py:UIRenderer.*
OpenCV/Pillow 기반 오버레이 렌더링 -
src/popup_alert.py:show_toast()
OS 토스트 팝업(플랫폼별 제약 가능)