Skip to content

Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor

19.6 KB
Raw Blame

エージェント向け手順書: 1枚のイラストからメッシュアバターを作る

English · 简体中文

この翻訳と英語版(agent-guide.md)の内容が食い違う場合は、英語版に従ってください。

この手順書は、このリポジトリで作業するコーディングエージェント(Claude Code、Codex、Cursor CLI など)向けです。ユーザーから1枚のイラストを受け取り、アバターを作るよう依頼されたら、エディタで開けてきれいに動くプロジェクトを作ってください。そのあとユーザーがエディタで細かく調整します。

手順は順番に進めてください。各ステップの最後には確認があります。確認は省略しないでください。仕上がりの品質は、自分の出力を実際に見て直せるかどうかで決まります。

始める前に

ツール

Node.js 22.17+、uv で動かす Python 3.10+、Playwright Chromium(npx playwright install chromium)が必要です。最初に npm install を一度実行し、続けて npm run doctor を実行してください。不足しているツールがそれぞれ報告されます。以降のどのステップでも uv、Python、Chromium のいずれかを使うので、警告が出たらこの手順書を進められない状態として扱ってください。

モデル

画像からピクセル座標を読むには高い画像認識能力が必要です。次の組み合わせで動作を確認しています。

エージェント モデル
Claude Code Claude Opus 5.5
Codex GPT-6.1 Sol

自分がどのモデルで動いているかをユーザーに伝えてください。上の表にない場合や分からない場合は、仕上がりが基準に届かないかもしれないことを伝え、推奨する組み合わせを示したうえで、続けるかどうかを確認してください。

画像認識の確認

キャリブレーションテストを実行し、スコアをユーザーに報告してください。

uv run tools/vision-check.py make work/vision-check   # 番号付きの印が入った画像を書き出す
# 画像を読んで答えを JSON で書き(形式はコマンドの出力を参照)、次を実行する:
uv run tools/vision-check.py score work/vision-check answer.json

スコアが不合格なら作業を止め、このモデルが読み取る座標はずれる可能性が高く、以降の作業の大半は手作業で直す必要が生じることをユーザーに伝えてください。

画像

  • PNG 画像を依頼してください。背景が透明で、ほぼ正面を向き、頭と肩が見えているものが理想です。顔が大きく斜めを向いている、手や物が顔を隠している、髪が顔に大きくかかっている場合は、品質が下がることをユーザーに伝えてください。
  • 画像はこのマシンの projects/ の中に置き、コミットしません。コミット、アップロード、ほかの場所へのコピーはしないでください。唯一の例外はステップ6で、ユーザーが同意した場合に限ります。描き起こし差分を作るときは、画像とマスクを画像生成ツールに送ります。

ステップ1 — プロジェクトを作る

uv run tools/new-project.py <path/to/image.png> <name>

projects/<name>/ が作成され、source.png と、画像サイズだけが入った空の rig.draft.json が作られます。各フィールドの意味は docs/rig-fields.md にあります。samples/miko-qipao/rig.json が完成例です。

ステップ2 — 画像を調べる

uv run tools/grid.py projects/<name> --step 50 --out projects/<name>/work/grid-full.png

全体のグリッド画像を見て、ユーザー向けのメモに次のことを書いてください。

  • 顔の中心、頭のてっぺん(髪と髪飾りを含む)、あご先、首、肩の位置
  • どの任意パーツがあるか: 顔の近くの手、お団子、垂れ下がるアクセサリー(房飾り、イヤリング)、肩にかかる長い髪
  • リグでまだ表現できないもの(帽子、メガネ、顔の前に持っている物)。これらは頭や体と一緒に固まったまま動くことをユーザーに伝えてください。

ステップ3 — リグの下書きを作る

rig.draft.json をパーツごとに埋めます。パーツごとに、まずその範囲の拡大グリッドを作って座標を読んでください。全体画像だけから見積もってはいけません。

uv run tools/grid.py projects/<name> --region x0,y0,x1,y1 --step 10 --out projects/<name>/work/grid-eyes.png
パーツ 置き方
head 髪と頭の飾りを含めて頭全体を覆う楕円。中心は目より少し上。回転の支点(pivot)は首に置く。weightBand はあご先のすぐ下から始まり、鎖骨のあたりで終わる。
face 鼻、口、両目、見えている耳、眉、あごに小さな楕円を置く。
eyes opening: まつげの内側で、見えている白目と虹彩に沿った多角形。14〜20点で、目尻から始める。roi: まつげと下まぶたの線から 10〜20 px 外側の多角形。この2つは 5 px のグリッドで読む。
mouth 閉じた口を通る線(中心、角度、半分の長さ、反り)と、唇より少し大きい楕円の area。
cheeks 頬の赤みの中心。
strands 揺らしたい髪の房ごとに1本の折れ線。根元から毛先まで4ノード。前髪は3〜5房、横髪は片側2房。
body 胸の楕円、肩ごとに1つの楕円、胸の上部から画像の下端までの呼吸範囲。
buns、accessories、hand ある場合のみ。
mesh、view samples/miko-qipao/rig.json の値から始める。mesh.fine は顔と髪を囲む矩形にする。

下書きでは eyes[*].x0/x1/top/bot を書かないでください。レイヤーを作るツールが計算します。

注意:

  • 目の0番は画像の左側にある目です。角度はラジアンです。
  • head の楕円は影響範囲で、切り抜きではありません。髪と頭の飾りをすべて覆うと肩の上や襟に触れてしまう場合は、髪を覆うほうを優先し、少しの重なりは受け入れてください。
  • 目の roi には、まつげと下まぶたの線がすべて入っていなければなりません。広げると前髪や横髪が入ってしまう場合は、まつげの周りでぴったり囲んだままにし、その目を確認が必要な箇所として挙げてください。
  • 最初の下書きは、ステップ3の確認に通るまでは未検証です。

ステップ3の確認

npm run validate-rig -- projects/<name>/rig.draft.json
uv run tools/overlay.py projects/<name> --rig rig.draft.json --out projects/<name>/work/overlay.png
uv run tools/overlay.py projects/<name> --rig rig.draft.json --part eyes --zoom --out projects/<name>/work/overlay-eyes.png

重ね合わせ画像をすべて見て、ずれているところを直してください。合格の条件:

  • head の楕円が髪と頭の飾りをすべて含み、肩を含まない
  • 各目の opening が、全周で約 2 px 以内の精度で白目の縁に沿っている
  • 各 roi がまつげと下まぶたの線をすべて含んでいる
  • 口の線が描かれた口の上にある
  • strands が肌や背景ではなく髪の上にある

ステップ4 — レイヤーを作る

uv run --with numpy --with pillow --with opencv-python-headless tools/build-layers.py projects/<name> --rig rig.draft.json

projects/<name>/built/ と、完成した projects/<name>/rig.json が書き出されます。

ステップ4の確認

built/hairmask.png と目のレイヤーを開いてください。髪マスクは髪をすべて覆い、顔や服を含まないこと。各目玉レイヤーには白目と虹彩だけが入っていること。

ステップ5 — 動きを確認する

npm run render-poses -- projects/<name>

決まったポーズ(通常、半目と閉じ目、口を開けた状態、左右を向く、上下を向く、頭の傾き、体の傾き、怒り・悲しみ・驚きの表情、髪の揺れの連続画像)でアバターを projects/<name>/review/ に描き出します。一覧画像と、目と口の拡大画像も作ります。

すべてのフレームを見てください。合格の条件:

  • 閉じ目が完全に閉じていて、まつげの線が1本できれいに出ており、虹彩や白目が残っていない
  • ±30°の振り向きや傾きでメッシュが裂けず、あごや耳が欠けず、アクセサリーが曲がらない
  • 口を開けてもあごが伸びない
  • 髪が揺れ、顔と服は動かない

確認用のフレームは画像全体が見えるようにエディタより余白を広く取っています。エディタとの見え方の違いは問題ありません。

不合格のフレームがあれば、下書きの該当パーツを直し、作り直して(ステップ4)もう一度描き出してください。3回繰り返しても直らなければ作業を止め、まだ不合格となっている内容を報告してください。

描き起こし差分がない場合、閉じ目の線の上に元の上まつげや二重の線がうっすら残ることがあります。虹彩と白目が消えていて、薄い線だけが残っている状態なら、リグとしては十分です。ステップ6に進んでください。ステップ6でこの線は消えます。

ステップ6 — 描き起こし差分(閉じ目、口の形、表情の目)

これらの差分は、Codex の組み込み画像生成(imagegen)で作ります。

描き起こし差分があると、まばたきと口パクがずっと自然になります。依頼データを作ります。

uv run tools/variant-requests.py projects/<name>

projects/<name>/variant-requests/ に、差分ごと(閉じ目 / 半目 / 笑い目、口の あ・半開きの あ・い・お、悲しみ / 驚きの表情の目、怒り / 悲しみの閉じた口)に編集マスク、プロンプト、README を書き出します。

表情の目(eyes_sad、eyes_surprise)と閉じた口(mouth_angry、mouth_sad)は任意で、ユーザーに頼まれたときだけ作ります。目には眉を含まない目のマスクを使います。リグが表情ごとに眉を動かすので、眉まで描くと二重に表示されてしまいます。口には口のマスクを使い、閉じた口のままにします。怒りと半目の表情は eyes_half を使うので、目を別に描く必要はありません。

生成する前にユーザーに確認してください。画像生成では source.png とマスクを生成ツールに送ります。断られたらここで作業を止めます。差分がなくてもアバターは動きます。

  • 画像を生成できる場合(画像生成付きの Codex など)は、プロンプトに従って source.png と各マスクから差分を生成し、projects/<name>/variants/<variant>.png に保存してください。
  • 生成できない場合はここで作業を止め、どのファイルを画像生成ツールに渡し、結果をどこに置けばよいかをユーザーに正確に伝えてください。ファイルを置いたと連絡を受けてから作業を続けてください。

各マスクでは、透明なピクセルは変えてよく、不透明なピクセルは元と完全に同じでなければなりません。多くの生成ツールは画像全体を再圧縮したり、透明な背景を塗りつぶしたり、1ピクセルずらしたりします。そのため build-sprites はマスクの範囲だけを取り込みます。3 px までのずれを補正し、元画像と同じ縦横比の結果は元のサイズに戻し、マスクの縁のすぐ内側で測った一様な色かぶりを取り除き(平らな肌の上ではつぎはぎのように見えるため)、importing the mask area only とログに出します。それでも、画像全体がそれ以上ずれている、マスクの外が描き直されている、描いた内容がマスクの縁からはみ出している、縦横比が違う、といった結果は理由を添えて取り込みを拒否します。拒否された差分は、同じサイズで、マスクの外のピクセルを変えないよう頼んで作り直してください。

続けて:

uv run tools/build-sprites.py projects/<name>

受け入れた差分を built/sprites/ に切り出します。もう一度ポーズを描き出すと(ステップ5)、angry、sad、surprise のフレームに表情の目と口が出ます。

任意 — 衣服の縫い目と段

実験的な全身向けの機能です。項目や動きは今後変わることがあります。

布の seams は腰から裾へ、画像の左から右の順に置き、tiers は描かれたフリルや段の継ぎ目に沿って列を横切る線にします。各 tier は各列と1回だけ交わり、腰から裾の順に並ぶ必要があります。列を交差させたり、グリッドのセルを反転させたりしないでください。seams または tiers を指定するとNリンクの連成振り子を使い、省略すると従来の2リンクのままです。

Studio の「衣服」で線を追加・削除し、頂点をドラッグして調整できます。辺をダブルクリックすると頂点を追加でき、Altを押しながら頂点をクリックすると削除できます。動きのグリッドの変更にはレイヤーの再構築は不要です。tierGain と highModeDamping は 1 から始めてください。前者は描画時だけ段の相対的な曲がりを強め、後者は最低次より高いモードの減衰を変えます。調整後は遅れ、行き過ぎ、収束を連続フレームで確認し、下書きを検証して保存してください。項目と検証条件の詳細は Rig fields を参照してください。

任意 — 脚の体重移動

実験的な全身向けの機能です。項目や動きは今後変わることがあります。

legs があるリグでは、待機中の体重移動は5秒周期、目標値は ±0.7 です。 片側への滑らかなS字の乗せ替えを0.9秒で行い、1.6秒保持してから反対側へ移ります。 legs がないリグの出力は従来どおりです。プレビューの体重移動スライダーでは -1..1 の全範囲を確認できます。項目の詳細は Rig fields を参照してください。

腰のひねりを加える場合は、twist を3〜6度から試してください。指定範囲は 0..15 度です。乗せ替えと保持中に、肩が一部逆向きに回り、頭の正面形状が保たれ、足と衣服の付け根が離れないことを確認してください。省略または 0 なら従来の出力を保ちます。Studio の「脚・体重移動」で調整でき、レイヤーの再構築は不要です。

任意 — 下ろした腕の動き

実験的な全身向けの機能です。項目や動きは今後変わることがあります。

両腕を体から離して下ろし、腕と胴体の間に透明な隙間がある画像にだけ rig.arms を設定してください。 腕が体に触れている、体の前にある、腰に手を当てている、腕を組んでいる画像や、胸から上の画像では省略します。 表現できるのは小さな振りと肘の曲げです。腕を上げたり、腕の後ろに隠れた部分を補ったりはできません。 ネイティブランタイムは現在 arms とそのパラメータを無視します。この機能には WebGL ランタイムを使ってください。

前の手順の座標校正と拡大グリッドを使います。画像左右の shoulder を袖の内側の脇に近い位置、 elbow を肘、wrist を手の付け根に置き、y 座標がこの順に増えるようにしてください。 各腕の split は脇の少し下から指先より下まで、透明な隙間を通る線にします。 画像左の腕では肘・手首より右側、画像右の腕では左側に置きます。 布がある場合は base_cloth.png も確認してください。スカートを除いた画像の腕の輪郭と切り抜きの残りが、動かせる範囲に影響します。 線を肌・袖・ブレスレットの上に置かないでください。

最初は既定値の swing: 4、bend: 6(度)、inward: 0.4 を使います。 下書きを検証し、腕の重ね合わせ画像を確認してからポーズを描き出してください。

npm run validate-rig -- projects/<name>/rig.draft.json
uv run tools/overlay.py projects/<name> --rig rig.draft.json --part arms --zoom --out projects/<name>/work/overlay-arms.png
npm run render-poses -- projects/<name>

描き出すときは、構築済みプロジェクトの rig.json にも同じ腕の設定を入れてください。 Studio の「体」から「腕」を選び、関節の点と左右の境界線を調整します。 辺のダブルクリックで点を追加でき、Alt を押しながら点をクリックすると削除できます。 待機動作を止め、4 つの腕スライダーで動きを確認してください。これらの編集にはレイヤーの再構築は不要です。 保存後に開き直し、変更が残っていることを確認してください。 「全身の対応状況」には、設定がなくても脚・腕・布の状態を表示します。未設定の部位は通常の動きのままです。

rest、7 種類の腕の固定ポーズ、arm-cycle-0..9、arm-idle-0..10 をすべて確認します。 静止時の絵が変わらず、袖がつながり、肘が滑らかに曲がり、手がスカートに隠れないことが合格条件です。 衣服が手首を隠す場合は動きの上限を下げてください。腕を動かすと元のブレスレットや袖の断片が現れる場合は、切り抜き画像を直します。 Live では「体の動きを認識」を有効にし、腕の力を抜いた姿勢を登録します。 左右反転の両方を試し、片側の手首や肘を隠したときに、その部位が滑らかに待機動作に戻ることを確認してください。 上限と追跡の仕様は Rig fields を参照してください。

ステップ7 — 引き渡す

ユーザーに次のことを伝えてください。

  • プロジェクトの開き方: npm run dev を実行し、「プロジェクトを開く」の一覧から projects/<name> を選ぶか、そのフォルダを選ぶ
  • 自信がなく、最初に確認してほしいパーツ
  • この画像でリグが表現できないもの
  • 目や手の輪郭を編集したら、リグを保存して、レイヤーの作り直しをエージェントに頼む必要があること

してはいけないこと

  • 拡大グリッドを使わずに、全体画像から座標を見積もる。
  • 重ね合わせやポーズの確認を飛ばす、または画像を見ずに成功と報告する。
  • 目の opening にまつげや肌を入れる、または閉じ目で虹彩が見える状態にする。
  • ユーザーの画像や、そこから作ったものをコミット、アップロード、コピーする。
  • 新しい画像を通すために samples/ や reference/ を書き換える。