Handkit

Que fait Handkit ?

Les mains sont du JSON : une pose correspond aux angles des articulations plus un placement ; un clip est une série de poses indexées dans le temps ; le cœur du système les transforme en mouvements naturels (ressorts, cascade des doigts, suivi, mouvement de repos) et un moteur les dessine. Tout est déterministe : le même clip produit les mêmes images.

HANDKIT ci-dessous est le dossier Handkit (la racine du dépôt). Exécutez les commandes depuis ce dossier.

Première utilisation : si le dossier Handkit n'existe pas encore, configurez-le (nécessite git, Rust et FFmpeg ; la première compilation prend quelques minutes, lancez-la donc en arrière-plan) :

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)    # seulement pour rendre la vidéo avec fframes

H=$HANDKIT/target/release/handkit          # l'interface en ligne de commande (cargo build --release une fois)
P=$HANDKIT/starters/fframes-clip/target/release/fframes-clip   # le lecteur vidéo
A=$HANDKIT/assets                          # hand_R.glb, hand_L.glb (le maillage handkit les écrit)

La boucle (à faire, dans l'ordre)

1. Commencez par la bibliothèque. $H gestures liste environ 50 poses nommées avec leurs descriptions (poing, index tendu, OK, pouce levé, paix, paume ouverte, pince, cœur avec les mains, cadre photo, poignée de main...). "from": "ok" sur une main reprend la forme d'un geste ; c'est quasiment gratuit. Écrivez les angles des articulations uniquement pour ce qui diffère.
2. Rédigez un clip (minimal, 30 images par seconde) :

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

   Chaque clé reprend la précédente : n'écrivez que ce qui change. t est le moment où la pose arrive ; move est la durée du mouvement (0.12 = un geste rapide) ; "pass": true fait traverser une clé sans s'arrêter. Placez les mains là où elles apparaissent dans l'image avec "place": {"screen": [x, y], "depth": 0.5, "palm_facing": .., "fingers_toward": ..} (x, y sont des fractions de l'image, 0,0 en haut à gauche) et faites entrer le bras depuis un bord avec "elbow_screen": [1.1, 0.9].
3. Vérifiez avant de rendre : $H check clip.json (contacts maintenus, doigts traversant d'autres doigts, vitesses, à-coups, cadrage, coudes visibles). Corrigez ce qu'il indique ; il nomme les clés.
4. Aperçu réduit et peu coûteux : $P --clip clip.json --assets $A strip -n 12 écrit strip.png (consultez-le). frame 2.5s écrit une image complète.
5. Rendez : $P --clip clip.json --assets $A render -o out.mp4 (1920×1080, en secondes). Portrait 1080×1920 : les mêmes commandes avec $HANDKIT/starters/fframes-clip/target-portrait/release/fframes-clip. Fond : --background "#1d1f24", --spotlight 0.5,0.45,0.35,#3a3f48.

Autres possibilités

• Contacts : "goals": [{"touch": ["right.thumb.tip", "right.index.tip"]}], puis $H solve pose.json les satisfait exactement (sortie avec code 2 si impossible). Viser : {"aim": "right.index", "at": [x,y,z]}.
• Apparences : "look" de niveau supérieur : style realistic | toon | spiderverse | arcane | clay, peau light | medium | tan | brown | dark | #rrggbb, outline, motion_blur (sous-images). Ou dans le lecteur : --look spiderverse,skin=brown.
• L'extrémité de l'avant-bras : le squelette s'arrête au coude. Lorsqu'un coude serait visible, utilisez "look": {"arm": "fade"} ou {"arm": {"sleeve": "#1e2a4a", "length": 0.08}} (une manche retroussée).
• Synchroniser une interface utilisateur avec la main : $H track clip.json --site right.index.tip affiche où se trouve un site sur l'écran à chaque image (fractions de l'image), par exemple pour faire réagir un bouton à un tapotement.
• Personnes : mains ana.right, ben.left (n'importe quels noms) ; "people": {"ana": {"look": {"skin": "dark"}, "scale": 1}} (scale 0.75 pour une main d'enfant). Les mains se repoussent au lieu de se traverser ("collide": false pour autoriser le chevauchement).
• Se tenir la main : un objectif {"grip": ["ana.right", "ben.right"], "style": "handshake"} ; styles : handshake, interlaced, cupped, high_five, fist_bump, pinky. Des clés successives avec la même poignée déplacent la paire ensemble, le suiveur prenant quelques images de retard.
• Les deux mains d'une même personne peuvent se joindre, applaudir ou encadrer un plan avec des objectifs touch entre elles.

Recréer une vidéo de référence

Étudiez-la d'abord : ffmpeg -i ref.mp4 -vf fps=4,scale=480:-1 f%03d.png et lisez les images. Une clé par événement visible ; placez les mains avec screen, orientez les avant-bras avec elbow_screen ; synchronisez les clés avec les images. Comparez : python $HANDKIT/tools/motion/compare.py ref.mp4 out.mp4 cmp (une feuille avec les deux aux mêmes instants, et une MP4 côte à côte).

Quand vous avez besoin de plus

$H explain (conventions), $H explain clips, $H explain looks, $H explain <param> (par ex. thumb.cmc_rot), ou $HANDKIT/docs/POSE_SPEC.md. Ne lisez que la partie nécessaire. Plages articulaires brutes : doigts mcp_flex -30..95, pip_flex -5..110, dip_flex -10..85, mcp_abd environ -15..25 ; poignet wrist_flex -80..85, wrist_dev -35..35.

Règles d'or : commencez par la bibliothèque ; peu de clés, un bon timing (les vraies mains bougent en 0.2–0.6 s et marquent une pause) ; vérifiez avant de rendre ; regardez une bande, pas la vidéo entière ; gardez les fichiers petits.