Handkit は何をしますか？
手はJSONで表現します。ポーズは関節角度と配置の組み合わせ、クリップは時間経過に伴うポーズのキーフレームです。コアエンジンがこれを自然な動き（バネ、指の連鎖、フォロースルー、アイドル）に変換し、描画エンジンがレンダリングします。すべて決定論的で、同じクリップからは常に同じフレームが生成されます。
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 write）
ループ（この順序で実行）
- ライブラリから始める。
$H gesturesで約50の名前付きポーズとその説明（fist、point、ok、thumbs_up、peace、spread_palm、pinch、heart_hands、camera_frame、handshake...）を一覧表示できます。手に"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で1フレームを出力します。 - レンダリングする。
$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。
その他の設定
- 接触:
"goals": [{"touch": ["right.thumb.tip", "right.index.tip"]}]と指定し、$H solve pose.jsonを実行すると、接触条件を正確に満たします（不可能な場合は exit 2）。照準:{"aim": "right.index", "at": [x,y,z]}。 - ルック: トップレベルの
"look": stylerealistic | toon | spiderverse | arcane | clay、skinlight | 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で、指定したサイトの画面上の位置（フレームの割合）を全フレーム出力します。例えば、ボタンにタップを反応させるなどに利用できます。 - 人物: 手に
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 でフレームを書き出し、読みます。目に見えるイベントごとに1つのキーを設定し、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秒で静止する）; レンダリング前にチェック; 全体動画ではなくストリップで確認; ファイルサイズを小さく保つ。