Skip to content
dev-burnernPublic

About

웹캠 기반 거북목 위험도 실시간 분석·알림 앱

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

FOZE

웹캠 기반 자세 분석으로 거북목(Forward Head Posture) 위험도를 실시간 피드백하는 데스크톱 앱입니다.

  • 실시간 랜드마크 추출: MediaPipe Pose Landmarker
  • 혼합 측정 로직: 측면(귀-어깨 기하) + 정면(비율/깊이 보조)
  • 경고/스트레칭 알림: 상태 지속 시간 기반
  • 세션 기록/분석: JSON 저장 + 기간 리포트

데모 / 스크린샷

  • docs/images/realtime.png
  • docs/images/turtle-page.png
  • docs/images/analysis-page.png

현재 저장소에는 예시 경로만 정의되어 있습니다.

빠른 시작

python -m venv .venv

Windows:

.venv\Scripts\activate

macOS / Linux:

source .venv/bin/activate

패키지 설치:

pip install -r requirements.txt

실행:

python main.py

프로젝트 구조

FOZE/
  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. 뷰 모드 자동 판별
  • 귀 가시성, 어깨 폭/깊이 차이를 이용해 정면/측면을 자동 판별합니다.
  1. 측면 지표 (1차)
  • 귀-어깨 기하로 목 기울기 각도를 계산합니다.
  • 해석 참고: CVA(대략) ≈ 90 - neck_angle.
  1. 정면 지표 (보조)
  • 코-어깨 수직 비율, 귀-어깨 비율, z축 깊이 차이를 결합해 가상 목 각도로 변환합니다.
  1. 안정화
  • EMA + median 필터, 프레임 급변 억제, 점수 히스테리시스로 떨림을 줄입니다.

실행 중 단축키

  • Q / ESC: 종료
  • S: 세션 저장
  • R: 스트레칭 타이머 리셋
  • P: 일시정지/재개
  • B: 백그라운드 모드
  • 1 / 2 / 3: 페이지 전환

데이터 / 개인정보 / 윤리

  • 기본 동작은 프레임 이미지 저장 없이 수치 데이터만 data/sessions/*.json에 저장합니다.
  • 로그/리포트에는 개인 식별 이미지 저장을 권장하지 않습니다.
  • 본 앱은 의료 진단 기기가 아니며, 통증/질환 의심 시 전문가 상담이 필요합니다.

FAQ

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/ 입니다.

핵심 API / 모듈 요약

  • 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 토스트 팝업(플랫폼별 제약 가능)

About

웹캠 기반 거북목 위험도 실시간 분석·알림 앱

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages