Handkit

O que Handkit faz?

Mãos são JSON: uma pose é composta por ângulos de articulações mais uma posição; um clipe é um conjunto de poses indexadas no tempo; o núcleo as transforma em movimentos naturais (molas, cascata de dedos, acompanhamento, movimento ocioso) e um motor as desenha. Tudo é determinístico: o mesmo clipe produz os mesmos quadros.

HANDKIT abaixo é a pasta do Handkit (raiz do repositório). Execute os comandos a partir dela.

Primeiro uso: se ainda não houver a pasta Handkit, configure-a (precisa de git, Rust e FFmpeg; a primeira compilação leva alguns minutos, então execute em segundo plano):

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)    # apenas para renderizar vídeos com fframes

H=$HANDKIT/target/release/handkit          # o CLI (cargo build --release uma vez)
P=$HANDKIT/starters/fframes-clip/target/release/fframes-clip   # o player de vídeo
A=$HANDKIT/assets                          # hand_R.glb, hand_L.glb (o handkit mesh os escreve)

O ciclo (faça isso, em ordem)

1. Comece pela biblioteca. $H gestures lista ~50 poses nomeadas com descrições (punho, apontar, ok, positivo, paz, palma aberta, pinça, coração com as mãos, moldura de câmera, aperto de mão...). "from": "ok" em uma mão assume a forma de um gesto; isso é quase gratuito. Escreva ângulos de articulações apenas para o que difere.
2. Escreva um clipe (mínimo, 30 fps):

   { "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" } } } ] }
   

   Cada keyframe começa do anterior: escreva apenas o que muda. t é quando a pose chega; move é quanto tempo o movimento leva (0.12 = um movimento rápido); "pass": true faz fluir por um keyframe sem parar. Posicione as mãos onde elas aparecem no quadro com "place": {"screen": [x, y], "depth": 0.5, "palm_facing": .., "fingers_toward": ..} (x, y são frações do quadro, 0,0 canto superior esquerdo) e traga o braço de uma borda com "elbow_screen": [1.1, 0.9].
3. Verifique antes de renderizar: $H check clip.json (contatos mantidos, dedos através de dedos, velocidades, estalos, enquadramento, cotovelos no campo de visão). Corrija o que ele disser; ele nomeia os keyframes.
4. Visualize pequeno e barato: $P --clip clip.json --assets $A strip -n 12 escreve strip.png (leia). frame 2.5s escreve um único quadro completo.
5. Renderize: $P --clip clip.json --assets $A render -o out.mp4 (1920x1080, segundos). Retrato 1080x1920: os mesmos comandos com $HANDKIT/starters/fframes-clip/target-portrait/release/fframes-clip. Fundo: --background "#1d1f24", --spotlight 0.5,0.45,0.35,#3a3f48.

O que mais você pode fazer

• Contatos: "goals": [{"touch": ["right.thumb.tip", "right.index.tip"]}], então $H solve pose.json atende exatamente a eles (código de saída 2 se não conseguir). Mirar: {"aim": "right.index", "at": [x,y,z]}.
• Aparências: "look" de nível superior: estilo realistic | toon | spiderverse | arcane | clay, pele light | medium | tan | brown | dark | #rrggbb, outline, motion_blur (subquadros). Ou no player: --look spiderverse,skin=brown.
• A extremidade do antebraço: a estrutura para no cotovelo. Quando um cotovelo aparecer, use "look": {"arm": "fade"} ou {"arm": {"sleeve": "#1e2a4a", "length": 0.08}} (uma manga enrolada).
• Sincronize uma UI com a mão: $H track clip.json --site right.index.tip imprime onde um ponto está na tela a cada quadro (frações do quadro), por exemplo, para fazer um botão reagir a um toque.
• Pessoas: mãos ana.right, ben.left (quaisquer nomes); "people": {"ana": {"look": {"skin": "dark"}, "scale": 1}} (escala 0.75 é a mão de uma criança). As mãos empurram umas às outras em vez de se atravessarem ("collide": false para permitir sobreposição).
• Mãos dadas: um objetivo {"grip": ["ana.right", "ben.right"], "style": "handshake"}; estilos handshake, interlaced, cupped, high_five, fist_bump, pinky. Keyframes em sequência com a mesma pegada movimentam o par junto, com o seguidor arrastando alguns quadros atrás.
• Duas mãos de uma pessoa se entrelaçam, batem palmas ou enquadram uma cena com objetivos touch entre elas.

Recriando um vídeo de referência

Estude-o primeiro: ffmpeg -i ref.mp4 -vf fps=4,scale=480:-1 f%03d.png e leia os quadros. Um keyframe por evento visível; posicione as mãos com screen, aponte os antebraços com elbow_screen; sincronize os keyframes com os quadros. Compare: python $HANDKIT/tools/motion/compare.py ref.mp4 out.mp4 cmp (uma folha de ambos no mesmo tempo e um MP4 lado a lado).

Quando precisar de mais

$H explain (convenções), $H explain clips, $H explain looks, $H explain <param> (por exemplo, thumb.cmc_rot), ou $HANDKIT/docs/POSE_SPEC.md. Leia apenas a parte que precisar. Faixas de articulações brutas: dedos mcp_flex -30..95, pip_flex -5..110, dip_flex -10..85, mcp_abd cerca de -15..25; punho wrist_flex -80..85, wrist_dev -35..35.

Regras práticas: biblioteca primeiro; poucos keyframes, bom tempo (mãos reais se movem em 0.2-0.6 s e seguram); verifique antes de renderizar; observe uma tira, não o vídeo inteiro; mantenha os arquivos pequenos.