| name | autorig-rig-health |
| description | AUTORIG 리그(mini_cubism character.json)의 유기적 연결 건강성을 3층으로 진단한다 — L1 구조(파트=메시 짝·고아 디포머·파라미터 구동·draw order 겹침·타깃 실존), ★L2 깊이 게이트(커버리지·단조성=회전 시 가까운 부품이 먼 부품보다 더 움직이나·과대진폭 방지, depth_map 대조), 프로(Strong20) 정량 대조. 결정론 게이트(scan_rig_health.py)는 메인이 돌리고, L3 시각 건강성은 극단포즈 실렌더 A/B로 별도 판정. 트리거 — "리그 건강성", "리그 건강성 체크", "유기적 연결 체크", "디포머/키폼/깊이 점검", "rig health", "리그 QA", "새 캐릭터 빌드 후 검사", "깊이 단조성", "리그 스캔". 깊이 역전 WARN 시 inject_depth_keyforms.py로 교정. |
AUTORIG 리그 유기적 연결 건강성 (3층 게이트)
캐릭터 움직임은 층 구조다: 핵심체인(파라미터→키폼→디포머→메시→부품, 깊이는 키폼 델타에 인코딩) 위에 물리·스키닝 가중치·부품 투명도·메시 해상도·idle·draw order, 그리고 리그 밖 웹캠 매핑+스무딩. 이 스킬은 그 연결의 건강성을 진단한다.
성숙도(정직): L1 구조 = 결정론 기준 확립. L2 깊이 단조성 = 이 트랙에서 만든 신규 유기성 기준. L3 시각 자연스러움 = 아직 정량화 미완 → 실렌더 A/B가 유일 판정.
1. L1·L2·프로 = 결정론 게이트 (메인이 직접 실행)
python3 scripts/build_depth_map_from_manifest.py \
--manifest experiments/<id>/layer_manifest.json \
--out experiments/<id>/rig_v0_project/depth_map.json
python3 scripts/scan_rig_health.py \
--project experiments/<id>/rig_v0_project \
--depth-map experiments/<id>/rig_v0_project/depth_map.json
출력 = PASS/WARN/FAIL 리포트(experiments/<id>/reports/rig_scan/HEALTH.txt). FAIL이면 exit 1.
- L1 구조: 파트=메시 짝 · 고아 디포머 없음 · 모든 파라미터가 keyform OR opacity OR mesh
vertex_keyforms로 구동(셋 다 봐야 — EyeExpr opacity와 ParamHairStrand_* vertex 구동 오탐 방지) · draw order 모호겹침(bbox+opacity 인지 = 대칭 L/R쌍·상태교체는 정상) · 키폼/물리/가중치 타깃 실존.
- 귀 물리 게이트(동물귀 있을 때, EAR-PENDULUM/VTXWEIGHT-002):
ear_physics(존재) 귀 파트에 물리 스프링 필수(없으면 정적 WARN) · ear_physics(진폭) max_offset ≤40px(과대 WARN) · ear_physics(정점가중치) 물리 있는 귀는 vertex_weights(머리거리 뿌리0·끝1) 필수 — 없으면 물리가 통짜 적용돼 "반쪽만 흔들림". 셋 다 WARN(정보), FAIL 아님.
- Hair strand vertex gate 후보(2026-07-06 유키 local evidence):
ParamHairStrand_*는 keyform_bindings가 아니라 mesh-local vertex_keyforms로 구동될 수 있다. health scan은 FAIL 0을 요구하되, L3 판정은 hair_idle/head_turn_hair/combo_hair GIF 또는 live compare에서 한다. 상세 SSOT: docs/ref/pipeline/AUTORIG-HAIRSTRAND-PHYSICS-001.md.
- ★L2 깊이 게이트 (depth_map 있을 때, 2-5D-DEPTH-ORACLE-001):
- 커버리지: 깊이 대상 head 디포머(DEF_PART)가 depth_map에 매핑되나 (<90% = WARN, 미매핑 = 깊이 미적용).
- 단조성: 디포머 계층 누적 유효 이동량이 depth_map z(가까움=1)와 단조인가 — 가까운 부품(front_hair)이 먼 부품(back_hair)보다 ≥ 이동. 회전축 키값은
key_values에서 자동 도출(±30 가정 안 함).
- 과대진폭 방지: 최근접 파트 이동이 기준(head_angle_warp)의 3배↑ = z-fighting·이탈 위험(WARN).
- 프로 대조: Strong20(param56/warp62/keyform253) 대비. 미달 = 정보(경량 빌드는 정상), FAIL 아님. foreshortening scale은 0.6~1.4 범위.
2. WARN 해석 규칙 (게이트는 단서, 판정은 맥락)
| WARN | 흔한 원인 | 조치 |
|---|
| 깊이 역전 (가까운 부품이 덜 이동) | ① 눈 등 의도적 고정(미끄럼 방지) ② depth_map이 코 깊이 과소평가(nose_reference 픽셀 0 → face 깊이) ③ 진짜 튜닝 누락 | ①②면 정상(주석). ③이면 §4 깊이 주입으로 교정 |
| 빈 물리 프로파일 (타깃 0) | 정의됐으나 미연결 스프링 | 타깃 배정 또는 제거 |
| 파라미터 미구동 | keyform·opacity 둘 다 없음 | 진짜 dead 파라미터인지 확인(런타임 직구동 allow 목록 제외) |
| ear_physics(정점가중치) 없음 | 물리 있는 귀에 vertex_weights 누락 | 통짜 이동=반쪽 정지 → rig_mesh build_vertex_weights(머리거리)로 재빌드 [[ear-head-parts-outside-deformer-bounds]] |
3. L3 시각 건강성 (실렌더 — 결정론 아님, 성역)
게이트 숫자가 맞아도 시각이 틀릴 수 있다(측정 적중 ≠ 시각 성공, [[pro-rotation-recipe-foreshortening]]). 극단 포즈 실렌더 A/B 필수:
python3 scripts/render_yaw_ab.py --before <기준리그> --after <대상리그> --out <reports>/...
머리 영역 크롭 몽타주 1장으로 갭·아티팩트·디졸브 육안 판정. 합성 시뮬 말고 실제 mini_cubism 렌더로([[visual-verify-real-render]]).
4. 깊이 교정 (L2 역전·누락 시)
python3 scripts/inject_depth_keyforms.py --project <리그> --axes X Y --kx 45 --ky 25
depth_map z 기반 다중 head-child 디포머 own 진폭 = (z_part − z_얼굴)×K 로 산출(front_hair 최대·뒤로 갈수록 작게 = 단조). front_hair_warp는 회전 키폼이 원래 없어(가장 가까운데 상속만) 신규 추가하고, edge_pinned(4변 전부→내부만, tip 상쇄)를 **pin_edges=["top"](뿌리만 핀)**으로 바꿔 tip이 자유 흔들리되 뿌리는 붙어 유지(=안 뜸). 눈은 얼굴 초과분 절반 캡. character.json.bak_depthinject 백업, idempotent. 리그는 메시 연속변형+계층+pin이라 갭 없이 깊이가 든다. 적용 후 §3 실렌더/웹캠 A/B로 확인.
5. 가드레일 (박제된 교훈)
- 프로데이터 = 필요조건이지 충분조건 아님. 경량 빌드(008=25/15/83)는 의도적; "프로 숫자 미달 = 나쁨" 아님. 용도(방송/데모 vs 풀리그)가 기준을 바꾼다.
- 측정 적중 ≠ 시각 성공: L1·L2 PASS여도 L3 실렌더로 확인하기 전엔 "됐다" 금지([[ssot-summary-overclaim]]).
- depth_map 한계: See-through 카테고리(front_hair) ↔ 리그 분할 파트(hair_front_L/C/R) 이름 불일치는 디포머명 컨벤션 맵(
DEF_PART)으로 다리. 비표준 네이밍 캐릭터는 맵 확장 필요(미지 항목은 graceful skip).
- 끄덕임 본질 한계: 끄덕임 천장은 키폼이 아니라 정수리 reveal(자산) 문제. 깊이 주입은 앞머리 움직임을 자연스럽게 할 뿐 끄덕임을 완전 해결하지 않는다.
- 도구는 캐릭터 무관(
--project/--depth-map 인자, 키값 자동도출). 새 캐릭터에 그대로 적용 가능.
