Handkit

Was macht Handkit?

Hände sind JSON: Ein Pose besteht aus Gelenkwinkeln plus einer Positionierung; ein Clip ist eine zeitlich verschlüsselte Abfolge von Posen; der Kern wandelt sie in natürliche Bewegungen um (Federn, Fingerkaskade, Nachlaufen, Leerlauf) und eine Engine rendert sie. Alles ist deterministisch: Derselbe Clip liefert immer dieselben Frames.

HANDKIT unten ist der Handkit-Ordner (der Repo-Stamm). Führe Befehle von dort aus.

Erstmalig: Wenn es noch keinen Handkit-Ordner gibt, richte ihn ein (benötigt git, Rust und FFmpeg; der erste Build dauert ein paar Minuten, also führe ihn im Hintergrund aus):

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)    # nur zum Rendern von Videos mit fframes

H=$HANDKIT/target/release/handkit          # die CLI (cargo build --release einmal)
P=$HANDKIT/starters/fframes-clip/target/release/fframes-clip   # der Video-Player
A=$HANDKIT/assets                          # hand_R.glb, hand_L.glb (handkit mesh schreibt sie)

Der Ablauf (führe dies in dieser Reihenfolge aus)

1. Starte mit der Bibliothek. $H gestures listet ~50 benannte Posen mit Beschreibungen auf (Faust, Zeigen, OK, Daumen hoch, Frieden, gespreizte Handfläche, Pinzette, Herz-Hände, Kamera-Rahmen, Handschlag...). "from": "ok" auf einer Hand übernimmt die Form einer Geste; das ist nahezu kostenlos. Schreibe Gelenkwinkel nur für das, was abweicht.
2. Schreibe einen Clip (minimal, 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" } } } ] }
   

   Jeder Schlüssel beginnt beim vorherigen: Schreibe nur das, was sich ändert. t ist der Zeitpunkt, an dem die Pose ankommt; move ist die Dauer der Bewegung (0.12 = ein schneller Ruck); "pass": true lässt einen Schlüssel durchlaufen, ohne anzuhalten. Platziere Hände dort, wo sie im Bild erscheinen, mit "place": {"screen": [x, y], "depth": 0.5, "palm_facing": .., "fingers_toward": ..} (x, y sind Bildschirmbruchteile, 0,0 oben links) und bringe den Arm von einem Rand herein mit "elbow_screen": [1.1, 0.9].
3. Überprüfe vor dem Rendern: $H check clip.json (gehaltene Kontakte, Finger durch Finger, Geschwindigkeiten, Sprünge, Bildausschnitt, Ellbogen im Sichtfeld). Behebe, was es sagt; es nennt die Schlüssel.
4. Vorschau klein und günstig: $P --clip clip.json --assets $A strip -n 12 schreibt strip.png (lies es). frame 2.5s schreibt einen vollständigen Frame.
5. Rendere: $P --clip clip.json --assets $A render -o out.mp4 (1920x1080, Sekunden). Hochformat 1080x1920: dieselben Befehle mit $HANDKIT/starters/fframes-clip/target-portrait/release/fframes-clip. Hintergrund: --background "#1d1f24", --spotlight 0.5,0.45,0.35,#3a3f48.

Was du sonst noch sagen kannst

• Kontakte: "goals": [{"touch": ["right.thumb.tip", "right.index.tip"]}], dann $H solve pose.json erfüllt sie exakt (exit 2, wenn es nicht möglich ist). Zielen: {"aim": "right.index", "at": [x,y,z]}.
• Looks: Auf oberster Ebene "look": Stil realistic | toon | spiderverse | arcane | clay, Haut light | medium | tan | brown | dark | #rrggbb, outline, motion_blur (Unter-Frames). Oder beim Player: --look spiderverse,skin=brown.
• Das Ende des Unterarms: Das Rig endet am Ellbogen. Wenn ein Ellbogen sichtbar wäre, verwende "look": {"arm": "fade"} oder {"arm": {"sleeve": "#1e2a4a", "length": 0.08}} (ein hochgekrempelter Ärmel).
• Synchronisiere ein UI mit der Hand: $H track clip.json --site right.index.tip gibt aus, wo sich eine Stelle auf dem Bildschirm in jedem Frame befindet (Frame-Bruchteile), z. B. um einen Button auf eine Berührung reagieren zu lassen.
• Personen: Hände ana.right, ben.left (beliebige Namen); "people": {"ana": {"look": {"skin": "dark"}, "scale": 1}} (scale 0.75 ist eine Kinderhand). Hände schieben sich gegenseitig zur Seite, anstatt durchzugehen ("collide": false, um Überlappung zu erlauben).
• Hände halten: Ein Ziel {"grip": ["ana.right", "ben.right"], "style": "handshake"}; Stile: handshake, interlaced, cupped, high_five, fist_bump, pinky. Schlüssel in einer Reihe mit demselben Griff bewegen das Paar zusammen, der Folgende hinkt ein paar Frames hinterher.
• Zwei Hände derselben Person umfassen, klatschen oder rahmen eine Aufnahme mit touch-Zielen zwischen ihnen.

Ein Referenzvideo nachstellen

Studiere es zuerst: ffmpeg -i ref.mp4 -vf fps=4,scale=480:-1 f%03d.png und lies die Frames. Ein Schlüssel pro sichtbarem Ereignis; platziere Hände mit screen, richte Unterarme mit elbow_screen aus; stimme die Schlüssel auf die Frames ab. Vergleiche: python $HANDKIT/tools/motion/compare.py ref.mp4 out.mp4 cmp (ein Blatt mit beiden zu denselben Zeiten und ein nebeneinander angeordnetes MP4).

Wenn du mehr brauchst

$H explain (Konventionen), $H explain clips, $H explain looks, $H explain <param> (z. B. thumb.cmc_rot), oder $HANDKIT/docs/POSE_SPEC.md. Lies nur den Teil, den du brauchst. Roh-Gelenkbereiche: Finger mcp_flex -30..95, pip_flex -5..110, dip_flex -10..85, mcp_abd etwa -15..25; Handgelenk wrist_flex -80..85, wrist_dev -35..35.

Faustregeln: Zuerst die Bibliothek; wenige Schlüssel, gute Zeitsteuerung (echte Hände bewegen sich in 0,2–0,6 s und halten); vor dem Rendern prüfen; einen Streifen ansehen, nicht das ganze Video; Dateien klein halten.