contact-dots은(는) 무엇을 하나요?
각 캐릭터의 손, 팔다리, 발, 골반(그리고 사용자가 지정하는 다른 모든 부위)에 점(dot)을 배치한 후,
헤드리스 Blender에서 프레임별로 각 점에서 표면까지의 간격, 점 사이의 거리, 방향 사이의 각도를 측정합니다.
dots.json을 작성하고 짧은 요약을 출력하며 dots-sheet.png(각 체크 및 최악 침투에 대한 클로즈업)를 렌더링합니다.
소스 파일을 절대 변경하지 않으며 사용자가 지정한 출력 폴더에만 기록합니다.
사용 시기
- "40번 프레임에서 그녀의 오른쪽 손바닥이 정말 그의 왼쪽 허벅지에 닿고 있나?" (신체 접촉,
touch) - "손가락이 컵 안으로 들어가나?" (침투는 항상 확인됨)
- "탄창이 40번 프레임에 제대로 장착되었다", "상자가 평평하게 놓여 있다", "총이 손에 고정되어 있다", "발이 바닥에 고정되어 미끄러지지 않는다" (구조적:
seat,rest,hold,distance) - "팔꿈치가 뒤로 굽혀지지 않는다", "뚜껑이 0-110도로 열린다", "손바닥이 테이블을 향한다" (회전:
range,align)
사용하지 않을 때: 포즈 수정, 물리 또는 균형 교정, 입 또는 옷 접촉, 메시-대-메시 겹침 검사.
필요 사항
Blender (최신 버전; 내부 Python 사용) 및 호스트 스크립트용 Python 3 표준 라이브러리.
Blender는 --blender PATH, $BLENDER, PATH, 일반 설치 폴더 순서로 찾습니다.
명령어
모든 명령어는 이 스킬 폴더의 scripts/dots.py를 통해 실행합니다:
python scripts/dots.py selftest [--out DIR] # 알려진 정답 확인; 새 기기에서 먼저 실행
python scripts/dots.py bones <file.fbx|.blend> # 리그의 뼈와 제안된 뼈 매핑
python scripts/dots.py measure <config.json> # 측정, 판단, dots.json + dots-sheet.png 생성
python scripts/dots.py sheet <dots.json> # 시트만 다시 렌더링
옵션: --blender PATH, --timeout S (기본 600), --limits finger|limb (측정),
--no-sheet (측정, 숫자만).
결과 줄 (경고 또는 자체 테스트 행 이후): dots: PASS ... (종료 코드 0), dots: FAIL ... (종료 코드 1) 또는
dots: skipped (<reason>) (종료 코드 2: Blender 없음, 시간 초과, Blender 오류 또는 잘못된 설정;
이유에 해당 항목이 표시됨). 건너뛴 실행은 결과가 아닙니다: 이유를 수정하고 다시 실행하세요.
문장에서 설정 파일로
- 각 캐릭터 파일에 대해
dots.py bones <file>을 실행하여 리그 매핑이 확실하지 않은 경우 확인합니다. (Mixamo 및 Unity 휴머노이드 이름은 자동 매핑됨; 그렇지 않으면boneMap을 작성). - 각 캐릭터에 짧은
role(her,him,a,b)을 부여합니다: 점 이름은<role>.<dot>형식입니다. - 확인할 각 항목을
checks의 한 항목으로 변환하고, 유지되어야 할 프레임을 지정합니다. out폴더 이름을 지정합니다 (상대 경로는 설정 파일 기준).
"40번 프레임에서 그녀의 오른쪽 손바닥이 그의 왼쪽 허벅지에":
{"out": "dots_out",
"characters": [{"role": "her", "file": "her.fbx"}, {"role": "him", "file": "him.fbx"}],
"frames": [40],
"checks": [{"id": "palm-on-thigh", "kind": "touch", "a": "her.R.palm", "b": "him.LeftUpLeg", "frames": [40]}]}
"그녀의 오른손이 그의 왼쪽 허벅지에" (손의 어떤 부분이든): "a": "her.R.hand" (그룹에서 가장 가까운 점이 사용됨).
신체 점 (S = R 또는 L): S.<finger>.tip, S.<finger>.mid (thumb, index, middle, ring,
pinky), S.palm, S.forearm.1-3, S.upperarm.1-3, S.thigh.1-3, S.shin.1-3, S.knee,
S.heel, S.ball, S.toe, pelvis.front, pelvis.back. 그룹: S.hand, S.foot,
S.forearm, S.upperarm, S.thigh, S.shin, pelvis.
표면 (touch의 b): <role> (전신), <role>.<canonical bone> (한 신체 부위,
예: him.LeftUpLeg, him.Spine1, him.Head), self, self.<bone>, prop:<object name>,
floor, nearest.
구조적 및 회전 체크는 사용자 정의 점 (뼈, 오브젝트 또는 메시 영역에)과
방향 (뼈 또는 오브젝트 축, 점 사이의 선, 표면 법선, 손바닥 법선, 세계 축)을 사용합니다.
전체 설정: references/config.md. 체크 종류별 작업 예제: references/checks.md.
touch, hold, align, range 및 rest를 포함한 전체 씬 (마네킹 손이 바를 잡고 들어 올림): examples/grab/
(ContactDots 저장소에 있음; config.json; 예상 결과는 PASS 10/10, 침투 0).
한도: 사전 설정 finger (기본: 접촉은 해당 프레임에서 최대 3mm 떨어져 있고
어떤 프레임에서도 최대 2mm 안으로 들어갈 수 있음) 또는 limb (10mm / 10mm), 또는 사용자 정의 숫자.
결과 읽기
요약에는 각 체크의 번호, 최악 프레임, 한도 및 PASS/FAIL이 나열되고, 그 다음 한도를 초과하는 침투가 나열됩니다.
간격은 피부에서 표면까지의 mm 단위: 양수 = 떨어져 있음, 음수 = 안으로 들어감. dots.json의 세부 사항: references/results.md.
- 양수 최악 간격으로 FAIL이 발생한 touch = 접촉하지 않음 (떠 있음); 음수 최대 깊이로 FAIL = 파고들어감.
dots.json의skinMm은 각 점의 자체 피부 반경입니다; 비정상적인 반경은 잘못된 스킨 웨이트 또는 잘못된 바디 메시를 의미하며, 해당 점의 간격은 부정확합니다.- 체크가 선언되지 않은 경우: 요약은 관찰된 접촉 (30mm 이내의 점)을 대신 나열합니다.
세계 프레임 경고
두 개의 FBX 파일이 항상 하나의 세계 프레임을 공유하지는 않습니다 (서로 다른 내보내기 루트 또는 오프셋). 두 명 이상의 캐릭터가 있는 경우 요약은 첫 번째 프레임에서 각 캐릭터의 루트 위치를 출력합니다. 쌍 번호를 신뢰하기 전에 캐릭터들이 서로에 대해 올바른 위치에 서 있는지 확인하세요. 그렇지 않으면 숫자는 의미가 없습니다: 숫자를 이동하지 말고 내보내기를 수정하세요.
시트를 보세요
숫자만으로는 충분하지 않습니다. 보고하기 전에 dots-sheet.png (출력 폴더에 있음)를 여세요:
각 메시는 캐릭터 또는 소품당 하나의 단색으로, 어두운 배경에, 캐릭터당 작은 점,
측정된 쌍은 선으로 연결됨 (노란색 = 통과, 자홍색 = 실패; 거의 0인 간격은 링),
접촉된 표면에 반투명 디스크 (보색, 외곽선 및 법선 화살표),
클로즈업 뷰에서 손바닥, 손목, 머리 및 골반에 XYZ 삼중축 (X 빨강, Y 초록, Z 하늘색),
각도 체크용 화살표, 타일당 캡션 (id, 값, 한도, PASS/FAIL).
측정된 쌍, 화살표, 디스크 외곽선 및 삼중축은 메시 앞에 그려집니다; 작은 점은 뒤에 숨을 수 있습니다.
각 타일이 의도한 부위 (오른손, 오른허벅지, 올바른 프레임)를 보여주는지 확인하세요.
잘못된 점에 대한 통과는 잘못된 답변입니다.
보고
첫 번째 요약 줄, 각 체크의 번호와 한도 및 프레임, 한도를 초과하는 침투, 두 캐릭터가 있는 경우 루트 위치, 그리고 시트에 표시된 내용을 보고하세요. 측정만 수행했다고 말하세요.