Handkit

¿Qué hace Handkit?

Las manos son JSON: una pose son ángulos de articulaciones más una ubicación; un clip son poses marcadas en el tiempo; el núcleo las convierte en movimiento natural (resortes, cascada de dedos, seguimiento, inactividad) y un motor las dibuja. Todo es determinista: el mismo clip produce los mismos fotogramas.

HANDKIT abajo es la carpeta de Handkit (la raíz del repositorio). Ejecuta los comandos desde ella.

Primer uso: si aún no existe la carpeta Handkit, configúrala (necesita git, Rust y FFmpeg; la primera compilación toma unos minutos, así que ejecútala en 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)    # solo para renderizar video con fframes

H=$HANDKIT/target/release/handkit          # la CLI (cargo build --release una vez)
P=$HANDKIT/starters/fframes-clip/target/release/fframes-clip   # el reproductor de video
A=$HANDKIT/assets                          # hand_R.glb, hand_L.glb (handkit mesh los escribe)

El bucle (haz esto, en orden)

1. Comienza desde la biblioteca. $H gestures lista ~50 poses con nombre y descripciones (puño, señalar, ok, pulgar_arriba, paz, palma_abierta, pellizco, manos_corazón, marco_cámara, apretón_de_manos...). "from": "ok" en una mano toma la forma de un gesto; eso es casi gratis. Escribe ángulos de articulaciones solo para lo que difiera.
2. Escribe un clip (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 clave comienza desde la anterior: escribe solo lo que cambia. t es cuándo llega la pose; move es cuánto dura el movimiento (0.12 = un chasquido); "pass": true fluye a través de una clave sin detenerse. Coloca las manos donde aparecen en el fotograma con "place": {"screen": [x, y], "depth": 0.5, "palm_facing": .., "fingers_toward": ..} (x, y son fracciones del fotograma, 0,0 arriba a la izquierda) y trae el brazo desde un borde con "elbow_screen": [1.1, 0.9].
3. Verifica antes de renderizar: $H check clip.json (contactos sostenidos, dedos a través de dedos, velocidades, saltos, encuadre, codos en vista). Corrige lo que dice; nombra las claves.
4. Mira pequeño y barato: $P --clip clip.json --assets $A strip -n 12 escribe strip.png (léelo). frame 2.5s escribe un fotograma completo.
5. Renderiza: $P --clip clip.json --assets $A render -o out.mp4 (1920x1080, segundos). Retrato 1080x1920: los mismos comandos con $HANDKIT/starters/fframes-clip/target-portrait/release/fframes-clip. Fondo: --background "#1d1f24", --spotlight 0.5,0.45,0.35,#3a3f48.

Qué más puedes decir

• Contactos: "goals": [{"touch": ["right.thumb.tip", "right.index.tip"]}], luego $H solve pose.json las cumple exactamente (código de salida 2 si no puede). Apuntar: {"aim": "right.index", "at": [x,y,z]}.
• Looks: "look" a nivel superior: estilo realistic | toon | spiderverse | arcane | clay, piel light | medium | tan | brown | dark | #rrggbb, outline, motion_blur (subfotogramas). O en el reproductor: --look spiderverse,skin=brown.
• El final del antebrazo: el rig se detiene en el codo. Cuando un codo se vería, usa "look": {"arm": "fade"} o {"arm": {"sleeve": "#1e2a4a", "length": 0.08}} (una manga arremangada).
• Sincroniza una UI con la mano: $H track clip.json --site right.index.tip imprime dónde está un sitio en la pantalla cada fotograma (fracciones de fotograma), p. ej., para hacer que un botón reaccione a un toque.
• Personas: manos ana.right, ben.left (cualquier nombre); "people": {"ana": {"look": {"skin": "dark"}, "scale": 1}} (escala 0.75 es la mano de un niño). Las manos se empujan entre sí en lugar de atravesarse ("collide": false para permitir superposición).
• Tomarse de las manos: un objetivo {"grip": ["ana.right", "ben.right"], "style": "handshake"}; estilos handshake (apretón), interlaced (entrelazados), cupped (en copa), high_five (choca esos cinco), fist_bump (choque de puños), pinky (meñique). Las claves en una fila con el mismo agarre mueven el par junto, el seguidor retrasado unos fotogramas.
• Dos manos de una persona se juntan, aplauden o forman un encuadre con objetivos touch entre ellas.

Recreando un video de referencia

Estúdialo primero: ffmpeg -i ref.mp4 -vf fps=4,scale=480:-1 f%03d.png y lee los fotogramas. Una clave por evento visible; coloca las manos con screen, apunta los antebrazos con elbow_screen; temporiza las claves con los fotogramas. Compara: python $HANDKIT/tools/motion/compare.py ref.mp4 out.mp4 cmp (una hoja de ambos en los mismos tiempos, y un MP4 lado a lado).

Cuando necesites más

$H explain (convenciones), $H explain clips, $H explain looks, $H explain <param> (p. ej. thumb.cmc_rot), o $HANDKIT/docs/POSE_SPEC.md. Lee solo la parte que necesites. Rangos de articulaciones en bruto: dedos mcp_flex -30..95, pip_flex -5..110, dip_flex -10..85, mcp_abd aprox. -15..25; muñeca wrist_flex -80..85, wrist_dev -35..35.

Reglas prácticas: biblioteca primero; pocas claves, buen tiempo (las manos reales se mueven en 0.2-0.6 s y se detienen); verifica antes de renderizar; mira una tira, no el video completo; mantén los archivos pequeños.