Handkit은(는) 무엇을 하나요?
손은 JSON입니다: 포즈(pose) 는 관절 각도와 배치(placement)를 포함하며; 클립(clip) 은 시간에 따라 키프레임으로 지정된 포즈들의 집합입니다; 코어는 이들을 자연스러운 움직임(스프링, 손가락 캐스케이드, 후속 동작, 아이들 동작)으로 변환하고 엔진이 이를 그립니다. 모든 것은 결정론적입니다: 동일한 클립은 동일한 프레임을 생성합니다.
HANDKIT은 Handkit 폴더(저장소 루트)를 나타냅니다. 이 폴더에서 명령어를 실행하세요.
처음 사용: Handkit 폴더가 아직 없으면 설정합니다 (git, Rust 및 FFmpeg 필요; 첫 빌드는 몇 분 걸리므로 백그라운드에서 실행하세요):
HANDKIT=${HANDKIT:-$HOME/.handkit}
[ -d "$HANDKIT" ] || git clone --depth 1 https://github.com/Ayushmaniar/3d-accurate-hands "$HANDKIT"
cd "$HANDKIT" && cargo build --release -p handkit-cli
(cd starters/fframes-clip && cargo build --release) # fframes로 비디오 렌더링에만 필요
H=$HANDKIT/target/release/handkit # CLI (cargo build --release 한 번)
P=$HANDKIT/starters/fframes-clip/target/release/fframes-clip # 비디오 플레이어
A=$HANDKIT/assets # hand_R.glb, hand_L.glb (handkit mesh가 씀)
작업 순서 (이 순서대로 하세요)
- 라이브러리에서 시작하세요.
$H gestures는 ~50개의 이름 있는 포즈와 설명(주먹, 검지, 확인, 엄지척, 평화, 손바닥 펼침, 꼬집음, 하트 손, 카메라 프레임, 악수...)을 나열합니다. 한 손에"from": "ok"를 사용하면 제스처의 형태를 가져옵니다; 거의 공짜입니다. 다른 부분에 대해서만 관절 각도를 작성하세요. - 클립을 작성하세요 (최소, 30fps):
{ "version": 1, "fps": 30, "camera": { "position": [0, 0.12, 0.6], "target": [0, 0.1, 0], "fov": 30 }, "look": { "style": "realistic", "skin": "medium" }, "keys": [ { "t": 0, "hands": { "right": { "from": "fist", "place": { "wrist": [0, 0, 0], "palm_facing": [0, 0, 1], "fingers_toward": [0, 1, 0] } } } }, { "t": 0.8, "hands": { "right": { "from": "spread_palm" } } }, { "t": 1.6, "ease": "snappy", "hands": { "right": { "from": "point" } } } ] }t는 포즈가 도착하는 시간입니다;move는 움직임이 걸리는 시간입니다(0.12 = 빠른 움직임);"pass": true는 키에서 멈추지 않고 통과합니다. 손을 프레임에 나타날 위치에 배치하려면"place": {"screen": [x, y], "depth": 0.5, "palm_facing": .., "fingers_toward": ..}(x, y는 프레임의 분수, 0,0은 왼쪽 위)를 사용하고, 가장자리에서 팔을 가져오려면"elbow_screen": [1.1, 0.9]를 사용하세요. - 렌더링 전에 확인하세요:
$H check clip.json(접촉 유지, 손가락이 손가락 통과, 속도, 팝, 프레이밍, 팔꿈치 보임). 지적하는 내용을 수정하세요; 키 이름을 알려줍니다. - 작고 저렴하게 미리보기:
$P --clip clip.json --assets $A strip -n 12는 strip.png를 씁니다(읽어보세요).frame 2.5s는 하나의 전체 프레임을 씁니다. - 렌더링:
$P --clip clip.json --assets $A render -o out.mp4(1920x1080, 초 단위). 세로 1080x1920: 동일한 명령어에$HANDKIT/starters/fframes-clip/target-portrait/release/fframes-clip을 사용하세요. 배경:--background "#1d1f24",--spotlight 0.5,0.45,0.35,#3a3f48.
그 외에 지정할 수 있는 것
- 접촉(Contacts):
"goals": [{"touch": ["right.thumb.tip", "right.index.tip"]}], 그런 다음$H solve pose.json이 정확히 접촉을 만족시킵니다(불가능하면 exit 2). 조준:{"aim": "right.index", "at": [x,y,z]}. - 룩(Looks): 최상위
"look": 스타일realistic | toon | spiderverse | arcane | clay, 피부light | medium | tan | brown | dark | #rrggbb,outline,motion_blur(서브 프레임). 또는 플레이어에서:--look spiderverse,skin=brown. - 팔뚝의 끝: 리그는 팔꿈치에서 멈춥니다. 팔꿈치가 보일 때는
"look": {"arm": "fade"}또는{"arm": {"sleeve": "#1e2a4a", "length": 0.08}}(걸린 소매)를 사용하세요. - UI를 손에 동기화:
$H track clip.json --site right.index.tip은 매 프레임마다 사이트가 화면상 어디에 있는지 출력합니다(프레임 분수), 예를 들어 버튼이 탭에 반응하도록 만들 수 있습니다. - 사람(People): 손
ana.right,ben.left(임의 이름);"people": {"ana": {"look": {"skin": "dark"}, "scale": 1}}(scale 0.75는 아이의 손). 손은 서로 통과하지 않고 밀쳐냅니다("collide": false로 겹침 허용). - 손 잡기: 목표
{"grip": ["ana.right", "ben.right"], "style": "handshake"}; 스타일: handshake, interlaced, cupped, high_five, fist_bump, pinky. 동일한 그립을 가진 연속된 키는 쌍을 함께 움직이며, 뒤따르는 손은 몇 프레임 지연됩니다. - 한 사람의 두 손:
touch목표를 사용하여 맞잡거나, 박수 치거나, 샷을 구성할 수 있습니다.
참조 비디오 재현
먼저 연구하세요: ffmpeg -i ref.mp4 -vf fps=4,scale=480:-1 f%03d.png 그리고 프레임을 읽으세요. 보이는 이벤트마다 하나의 키를 지정하고; screen으로 손을 배치하고, elbow_screen으로 팔뚝 방향을 조준하세요; 키 시간을 프레임에 맞추세요. 비교: python $HANDKIT/tools/motion/compare.py ref.mp4 out.mp4 cmp (두 영상을 같은 시간에 보여주는 시트와 나란히 보는 MP4).
더 필요한 경우
$H explain (규칙), $H explain clips, $H explain looks, $H explain <param>
(예: thumb.cmc_rot), 또는 $HANDKIT/docs/POSE_SPEC.md. 필요한 부분만 읽으세요.
원시 관절 범위: 손가락 mcp_flex -30..95, pip_flex -5..110, dip_flex -10..85,
mcp_abd 약 -15..25; 손목 wrist_flex -80..85, wrist_dev -35..35.
경험 법칙: 라이브러리 우선; 키는 적게, 좋은 타이밍(실제 손은 0.2-0.6초에 움직이고 멈춤); 렌더링 전에 확인; 전체 비디오가 아닌 스트립을 보세요; 파일을 작게 유지하세요.