ROM Vision Tool

휴대폰 카메라 영상의 2D 관절 좌표로 관절 가동범위를 측정하는 브라우저 각도계 프로토타입 v0.9입니다. 임상 정확도는 아직 검증되지 않았습니다(아래 "검증 방법" 참고).

v0.8에서 달라진 점

영역	v0.7	v0.8
측정 항목	무릎·팔꿈치 굴곡, 어깨 외전, 고관절 굴곡 (8개)	+ 어깨 굴곡/신전, 고관절 외전/내전, 발목 배측/저측굴곡 (14개)
방향	절댓값만 표시해서 과신전·신전 구분 불가	얼굴(귀→코)과 발(종아리 기준 뒤꿈치→발끝)로 몸 방향을 판별해 부호 있는 각도 표시: 굴곡 +, 과신전·신전 −
가이드 라인	세 관절점을 잇는 선	각도계 표준 정렬: 축(●), 고정팔(파랑), 0° 기준선(점선, 고정팔 연장), 이동팔(초록), 각도 호, 값 라벨
지레팔	없음	이동 분절 무게중심에서 내린 수직선과 축까지의 수평 거리(중력 지레팔)를 표시. 분절이 수평일 때 100%
수동 보정	없음	화면 고정·보정: 정지 화면에서 관절점을 손가락으로 끌어 실제 뼈 기준점에 맞추면 각도를 다시 계산하고 끝범위로 반영. PNG로 저장 가능
떨림 처리	각도 지수평활	관절점에 One Euro 필터 적용: 정지 시 떨림은 줄이고 움직일 때 지연은 줄임. 화면 숫자와 가이드 선이 같은 점에서 계산됨
품질 확인	가시성, 측면/정면 판정	+ 운동면 이탈 각도(MediaPipe 3D 좌표, 25° 경고 / 45° 측정 중단), 분절 크기, 화면 가장자리, 측정 쪽이 카메라 반대편인지, 휴대폰 기울기(가속도계)
회전 버그	측정 중 휴대폰을 돌리면 화면 비율이 바뀌어 각도가 왜곡됨	매 프레임 영상 크기를 확인해 캔버스를 다시 맞추고 추적 초기화
거울 화면	후면 카메라에서도 기본 켜짐	전면은 거울, 후면은 실제 방향으로 자동 전환
보안	meta CSP만 사용 (unsafe-inline 스타일)	vercel.json 보안 헤더(CSP frame-ancestors 'none', X-Frame-Options, Permissions-Policy, nosniff, Referrer-Policy, HSTS). 인라인 스타일을 제거해 style-src 'self'로 강화. 복원 파일의 알 수 없는 필드 제거, 모든 기록 삭제 기능 추가

기존 운동 분석 프로그램과 비교

기능	Kinovea	Hudl Technique · OnForm 등 영상 분석 앱	ROM Vision v0.8
자동 관절 인식	✗ (수동 각도 도구)	주로 수동 도구 (일부 앱은 AI 스켈레톤 제공)	✓ (MediaPipe, 기기 내 처리)
각도계식 고정팔·이동팔·0° 기준선	수동으로 그림	수동으로 그림	✓ 자동 + 수동 보정
정지 화면에서 기준점 보정	✓	✓	✓
과신전·신전 부호 구분	사용자가 판단	사용자가 판단	✓ 자동 (방향 미확인 시 기록 차단 또는 경고)
운동면 이탈·촬영 품질 경고	✗	✗	✓
중력 지레팔 표시	✗	✗	✓
슬로모션·프레임 단위 재생	✓	✓	✗
설치	PC 프로그램	앱	웹 주소만 열면 됨

경쟁 제품 열은 공개 자료에서 확인되는 일반적인 기능이며, 버전·요금제에 따라 다를 수 있습니다.

아직 없는 기능: 슬로모션·프레임 단위 재생, 녹화 영상 불러오기, 여러 카메라를 이용한 3D 측정, 손목·경추·회전 운동 측정.

실행

정적 파일을 HTTPS로 호스팅하거나 로컬 서버에서 실행합니다. file://로 열면 ES 모듈과 카메라 접근이 제한될 수 있습니다.

python -m http.server 8000

브라우저에서 http://localhost:8000을 열고 카메라 권한을 허용하세요. MediaPipe 코드·WASM·모델은 vendor/mediapipe/에서 같은 사이트로 불러오므로 외부 CDN에 접속하지 않습니다. GPU 초기화에 실패하면 CPU로 다시 시도합니다. 처리 속도가 6fps 미만이면 끝범위를 기록할 수 없다고 경고합니다.

정확하게 찍는 법

1. 운동면과 화면을 평행하게: 굴곡/신전 항목은 정측면, 외전 항목은 정면(또는 등 뒤)에서 찍습니다. 비스듬히 찍으면 실제와 다른 각도가 나옵니다(투영 오차). 품질 목록에 "평면 이탈"이 25°를 넘으면 경고, 45°를 넘으면 측정하지 않습니다.
2. 휴대폰은 1배 기본 렌즈, 2–3 m 거리, 측정 관절 높이에서 수직으로 세웁니다. 초광각(0.5배)은 화면 가장자리 왜곡이 큽니다. 측정 관절을 화면 가운데에 둡니다.
3. 측정할 쪽이 카메라를 향하게 합니다. 반대편 다리·팔은 가려져서 모델이 추정한 위치를 씁니다.
4. 얼굴 옆모습이나 발 전체가 보이게 합니다. 몸 방향을 알아야 굴곡과 신전(과신전)을 구분합니다. 어깨·고관절 굴곡/신전은 방향이 확인될 때까지 기록하지 않습니다.
5. 두 끝범위에서 각각 0.6초 이상 멈춥니다. 각도 변화가 4° 이내인 구간의 중앙값을 끝범위로 기록합니다.
6. 중요한 기록은 화면 고정·보정으로 점을 실제 뼈 기준점(대전자, 대퇴골 외측상과, 외측복사뼈, 견봉 등)에 맞춘 뒤 반영합니다. 자동 점은 피부 위 뼈 기준점이 아니라 모델이 추정한 관절 중심입니다.

각도 정의

항목	축	고정팔	이동팔	0°
무릎 굴곡/신전	무릎	엉덩이(대전자) 방향	발목(외측복사뼈) 방향	허벅지 연장선 (과신전 −)
팔꿈치 굴곡/신전	팔꿈치	어깨(견봉) 방향	손목 방향	위팔 연장선 (과신전 −)
고관절 굴곡/신전	고관절	몸통 외측 중앙선	무릎 방향	몸통 연장선 (신전 −)
어깨 굴곡/신전	어깨	몸통 외측 중앙선	팔꿈치 방향	팔을 내린 위치 (신전 −)
어깨 외전	어깨	몸통 중앙선과 평행	팔꿈치 방향	팔을 내린 위치 (내전 −)
고관절 외전/내전	고관절	양쪽 골반(ASIS)을 잇는 선	무릎 방향	골반선의 수직선 (내전 −)
발목 배측/저측굴곡	발목	종아리(비골두) 방향	발바닥(뒤꿈치→발끝)과 평행	종아리와 발이 90° (저측굴곡 −)

• 모든 계산은 거울 반전 전 원본 영상의 픽셀 좌표로 합니다. 화면 비율, 거울 표시, 누운 자세, 휴대폰 좌우 기울기는 관절 사이 각도에 영향을 주지 않습니다(테스트로 확인).
• 고관절각은 골반 움직임을 분리하지 못하고, 어깨각은 견갑골·몸통 움직임을 분리하지 못합니다.
• 중력 지레팔은 화면 세로 방향을 중력 방향으로 가정합니다. 휴대폰이 옆으로 기울면 경고합니다. 무게중심 위치는 Winter의 인체 분절 비율(허벅지·종아리 43.3%, 위팔 43.6%, 아래팔 43%, 발 50%)을 씁니다. 분절 하나만 계산하므로 팔 전체·다리 전체의 토크가 아닙니다.

검증 모드 (v0.9)

화면의 "검증 모드 · 고니오미터 비교" 카드에서 앱 값과 고니오미터 값을 짝지어 기록합니다. 임상 기록과 따로 저장됩니다(romvision_validation_v1).

1. 카메라를 켜고 관절 가이드가 보이는 상태에서 자세를 유지합니다. 정확한 비교를 원하면 화면 고정·보정으로 기준점을 맞춥니다.
2. 현재 앱 각도 가져오기 → 같은 자세에서 고니오미터로 잰 값을 입력(과신전·신전은 −) → 촬영 방향 선택 → 비교 기록 추가.
3. 관절별로 다음을 자동 계산합니다(Bland–Altman 방식).
   • 평균 차이(앱 − 고니오미터): + 이면 앱이 크게, − 이면 작게 잰다는 뜻
   • 95% 일치한계: 평균 차이 ± 1.96 × 표준편차. 이 관절에서 기대할 수 있는 오차 범위
   • 평균 절대오차, 최대 오차, ±5°·±10° 이내 비율
   • 자동 vs 화면 고정·보정, 촬영 방향별 평균 오차
4. 검증 CSV로 내보내 보관하거나 엑셀에서 추가 분석합니다. 5회 미만은 해석하지 않도록 안내합니다.

검증 방법 (실제 기기에서 꼭 해 보세요)

이 저장소의 테스트는 계산식이 정확한지 확인합니다(알려진 각도로 만든 합성 자세에서 오차 0). 모델이 관절점을 얼마나 정확히 찾는지는 실제 사람과 휴대폰으로만 확인할 수 있습니다.

1. 같은 사람, 같은 자세에서 고니오미터 측정값과 ROM Vision 값을 나란히 기록합니다(관절당 5개 각도 이상, 각 3회).
2. 정측면 촬영과 15°·30° 비스듬한 촬영을 각각 해 보고 차이를 비교합니다.
3. 자동값과 "화면 고정·보정" 후 값을 비교합니다.
4. 차이의 평균과 범위를 기록해 두면 이 도구를 어디까지 믿을 수 있는지 알 수 있습니다. 참고로 MediaPipe와 RGB-D 카메라를 쓴 선행 연구(Lafayette 외, MDPI Sensors 2023 논문에서 재인용)는 정면 촬영에서 약 11°, 30° 비스듬한 촬영에서 약 14°의 편차를 보고했습니다. 이 도구의 오차는 직접 측정해야 알 수 있습니다.

저장·백업·복원

• 측정 기록은 해당 브라우저의 localStorage에 저장됩니다. 다른 기기나 브라우저와는 공유되지 않습니다. 브라우저 데이터 삭제·사생활 보호 모드 종료 시 사라질 수 있으므로 JSON 백업을 별도로 보관하세요.
• v0.8 기록은 clinical-v3 형식(음수 각도, 수동 보정 여부, 방향 미확인 비율 포함)입니다. v0.7 이하 기록은 각도 정의가 달라 백업·CSV에만 보존하고 추세 비교에서는 제외합니다.
• JSON 복원은 10MB/10,000개 이하의 v2·v3 형식을 검증하고, 알려진 필드만 남긴 뒤 기존 기록에 병합합니다. 같은 ID에 내용이 다르면 전체 복원을 중단합니다.
• CSV는 스프레드시트 수식으로 해석될 수 있는 시작 문자를 무력화합니다. 음수 각도는 숫자로 내보냅니다.
• 모든 기록 삭제는 확인 후 이 브라우저의 기록을 영구 삭제합니다.

보안·개인정보

• 영상과 측정 기록을 외부로 보내는 코드가 없습니다. CSP(connect-src 'self')로 외부 연결을 막습니다.
• vercel.json이 보안 헤더를 보냅니다: CSP(frame-ancestors 'none' 포함), X-Frame-Options: DENY(다른 사이트가 이 페이지를 숨겨 넣고 카메라를 쓰게 하는 클릭재킹 차단), Permissions-Policy(카메라·모션 센서만 이 사이트에 허용, 마이크·위치 차단), nosniff, Referrer-Policy: no-referrer, HSTS.
• 인라인 스크립트·스타일이 없어 CSP에 unsafe-inline이 필요 없습니다. 화면 문자열은 모두 textContent로 넣습니다.
• 암호화 저장·사용자 인증은 구현되지 않았습니다. 환자 식별번호에는 실명 대신 내부 번호를 쓰세요.

기술 구성

• index.html, styles.css: 화면과 스타일
• app.js: 카메라 제어, 각도계 오버레이, 화면 고정·보정, 기록·내보내기·복원, 규칙 기반 요약
• core.js: 관절 정의, 각도·방향·지레팔 계산, 품질 판정, One Euro 필터, 끝범위 판정, 기록 검증
• vendor/mediapipe/: MediaPipe Tasks Vision 0.10.14 / Pose Landmarker Full (수정 없이 포함, SHA-256 검증)
• vercel.json: 배포 보안 헤더

테스트

Node.js 22 이상에서 외부 패키지 없이 실행합니다.

npm run check
npm test

• tests/geometry.test.js: 7개 관절 유형을 알려진 각도의 합성 자세로 만들어 양방향 촬영, 좌우, 누운 자세, 거울 영상, 카메라 기울기, 화면 비율에서 계산값이 정확히 일치하는지 확인합니다. 방향 판별, 평면 이탈, 지레팔, 필터 동작도 확인합니다.
• tests/core.test.js, tests/app.test.js: 끝범위 판정, 저장 실패 시 값 보존, 기록 검증·병합·복원, CSV, 화면 동작
• tests/security.test.js: 보안 헤더, 인라인 코드 없음, HTML 삽입 API 미사용, 관절 메뉴와 정의 일치
• tests/vendor.test.js: vendor 파일 체크섬, 외부 출처 미사용

v0.8 개발 중에는 실제 MediaPipe 모델과 가짜 카메라 영상을 써서 헤드리스 Chromium(휴대폰 화면 크기)에서 카메라 시작, 각도 표시, 화면 고정·보정·반영·재개, CSP 위반 없음까지 확인했습니다. 실제 iOS/Android 기기에서의 카메라 동작과 측정 정확도는 별도로 확인해야 합니다.