Skip to content

Repository files navigation

Anime2.5DRig

デモ: https://852wa.github.io/Anime2.5DRig/

パーツ分けPSDをブラウザにドロップするだけで、自動リギングされて動き出す 2.5D アバターツールです。 従来は手作業だったセットアップ(メッシュ分割・変形・物理設定)を自動化します。インストール不要・全処理クライアントサイド。

デモ / 使い方

  1. このリポジトリを GitHub Pages で公開(Settings → Pages → Branch: main / root)するか、ローカルで:
    python obs_server.py
    # → http://127.0.0.1:8000
    
    (python -m http.server 8000 でも動きます。OBS連携を使う場合は obs_server.py を使用してください)
  2. ページを開き、パーツ分けPSDをドロップ、または「サンプルAを読み込む」「サンプルBを読み込む」を選択。Aは sample2.psd、Bは sample.psd です。左上の「サンプルA」「サンプルB」から、読み込み後もいつでも切り替えられます。
  3. 自動リグが走り、その場でアイドルモーション・まばたき・口パク・髪物理付きで動きます。

v2.0 の新機能

  • OBS連携の強化: 通常ブラウザで開いたPSD・調整・表情・アンカーが、OBSのブラウザソースへ自動で反映されます(sample.psd 固定ではなくなりました)
  • 顔追跡の強化: 左右別のまばたき(ウインク)・眉・笑顔の追跡、正面キャリブレーション、感度・なめらかさ調整、カメラ映像のプレビュー。追跡ライブラリ(MediaPipe FaceMesh)を版固定で同梱し、オフラインでも動作
  • アンカー編集モード: 顔・目・閉じ位置・口・首・胸の基準点をプレビュー上でドラッグして修正
  • 動画書き出し: モーションを元のPSDサイズの透過WebM(またはMP4)で録画
  • 操作性: 元に戻す/やり直す、表情のキー切替、プレビューの拡大・移動、レイヤーのサムネイル・役割表示・ドラッグ並べ替え、モデル診断、行単位の設定検索
  • 自動リグ: 日本語レイヤー名(前髪・白目・瞳など)や see-through の出力名、耳飾り・尻尾の揺れに対応
  • 描画品質: 瞳のクリップを滑らかな縁(アンチエイリアス)に変更。白目を非表示にすると瞳まで消える不具合を修正

詳細は IMPROVEMENTS.md を参照してください。

編集と保存

  • 上部の「PSDを開く」(Ctrl+O)からいつでもモデルを変更できます。読み込み中は進捗が表示され、「読み込みを中止」で取り消せます。新しいPSDが読み込めなかった場合も、編集中のモデルは残ります。
  • 「設定を検索」で目・髪・口などの設定を絞り込みます。一致した行だけが表示されます。セクション見出しはクリック、Enter、Spaceで開閉でき、開閉状態は記憶されます。
  • スライダー右の数値は直接入力できます。スライダーをダブルクリックすると、その項目だけ初期値に戻ります。
  • 変更は「↶ / ↷」または Ctrl+Z / Ctrl+Shift+Z で元に戻せます(パラメーター・表情・レイヤー・アンカー・背景)。
  • 「レイヤー」で表示/非表示、濃さ(不透明度)、奥行き、描画順を調整できます。上が奥・下が手前です。サムネイルをドラッグするか ↑↓ で並べ替え、▸ で濃さ・奥行きを開きます。カードにマウスを乗せると、そのパーツの範囲がプレビューに表示されます。奥行きは首振り時の移動量に影響し、描画順とは別の設定です。
  • 「調整を保存」(Ctrl+S)で、パラメーター・自動動作・背景・レイヤー設定・アンカーをブラウザ内にモデル別で保存します。未保存の変更があるとボタンに「●」が付き、ページを閉じる前に確認されます。同じ内容のPSDを読み込むと復元されます。「保存状態に戻す」で直前の保存状態に戻せます。
  • 別のブラウザ/PCに移すときは「設定JSONを書き出す」を使用します。同じPSDを開いて「設定JSONを読み込む」を押すか、JSONをプレビューへドロップすると適用されます。旧版(v1)の設定JSONも読み込めます。PSDの画像そのものや、カメラ・マイクのON状態は設定JSONに含まれません。PSDを編集し直した場合は別のモデルとして扱います。
  • 「一時停止」(Space)で動きを止め、数値を調整できます。
  • 「軽量PSDを保存」はノイズ除去・トリミングを行ったPSDを保存します。動き・描画順・奥行きなどの調整は設定JSONに保存してください。
  • 表情プリセット中は自動まばたき・ランダム口パクによる上書きを抑えます。カメラ入力を使用するときも、自動まばたき・ランダム口パクより追跡値を優先します。
  • 「モデル情報・診断」に、必要なレイヤーが見つかったか・自動生成したか・未分類のレイヤーがあるかを一覧表示します。

キーボード・マウス操作

操作 内容
Space 一時停止 / 再生
1〜7 表情プリセット(通常・笑顔・薄目・驚き・ジト目・ウインク左・ウインク右)。同じキーでもう一度押すと解除
0 表情プリセットを解除
Ctrl+Z / Ctrl+Shift+Z(Ctrl+Y) 元に戻す / やり直す
Ctrl+S / Ctrl+O 調整を保存 / PSDを開く
E アンカー編集モード(Esc で終了)
F、ダブルクリック プレビューを全体表示に戻す
B 背景を切り替え
ホイール・ピンチ / ドラッグ プレビューの拡大・縮小 / 移動
? ショートカット一覧

アンカー編集

目・口・首の位置は自動で検出しますが、絵柄によってはずれることがあります。「アンカー編集」(E)を押すと、静止したポーズの上に基準点が表示されます。

  • 顔の中心: 首振りの奥行き・前髪ブロックの境目の基準
  • 左目・右目: 瞳のスケール・視線移動の中心
  • 閉じ位置(青): まぶたが閉じる高さ。ドラッグ中はその目を閉じてプレビューします
  • 口: 口の開閉・スケール・閉じ口の回転の中心
  • 首の回転軸: 頭が回る支点
  • 胸(紫): 胸の揺れの中心(上半身の服レイヤーがある場合)

ドラッグ、または点を選んで矢印キー(1px)/ Shift+矢印キー(10px)で動かします。調整は設定の保存・JSON・OBS同期・元に戻すの対象です。「自動検出の位置に戻す」でリセットできます。

カメラ・マイク

  • 「カメラ追従」をONにすると、頭の向き・まばたき・視線・口の開き・眉・笑顔(口の形)を追跡します。左上に小さなカメラ映像と検出点が表示されます(「カメラ映像を小さく表示」でOFF)。
  • 正面を記録(キャリブレーション): カメラ追従中に、正面を向いて自然な表情で押してください。その顔を基準に判定するため、目が細め・口角が上がり気味などの個人差があっても誤判定しにくくなります。記録はこのブラウザに保存されます。
  • 「左右のまばたきを連動」をOFFにするとウインクを検出します。眉・笑顔の追跡は個別にOFFにできます。
  • 頭・まばたき・口・眉・視線の感度と、動きのなめらかさ(揺れを抑える強さ)を調整できます。
  • 「マイク口パク」は感度とノイズゲート(これ以下の小さな音を無視)を調整でき、入力レベルがメーターに表示されます。
  • 顔追跡には MediaPipe FaceMesh(Apache-2.0)を使用します。lib/vendor/face_mesh/ に同梱しているため、ネット接続が無くても動作し、配布元の更新で挙動が変わることもありません(WebAssembly SIMD 非対応の古いブラウザだけ、同じ版をCDNから取得します)。

カメラ追従とマイク口パクは https または localhost でのみ動作します(ブラウザの権限仕様)。file:// 直開きでもドロップ再生は可能です。

書き出し

  • 「PNG保存」は現在のポーズを元のPSDサイズで書き出します。操作画面は含みません。
  • 「録画」は元のPSDサイズの動画を書き出します。長さ(3〜60秒)・フレームレート(30/60fps)・形式を「書き出し」で選べます。録画中にもう一度押すと、そこまでを保存します。
  • 背景は「透過・グリーンバック・ダーク」から選べ、PNGと動画の両方に使われます。透過を保持できるのはWebM(Chrome / Edge / Firefox)です。MP4は透過しません。

OBS 透過出力

  1. start_obs.bat をダブルクリックします。ローカルサーバーが起動し、通常ブラウザで編集画面が開きます(カメラを許可してください)。
  2. OBSで「ブラウザ」ソースを追加し、URLを http://127.0.0.1:8000/?obs=1、幅・高さをPSDのサイズに合わせて設定します。編集画面の「OBS連携」にURLとコピーボタンがあります。
  3. 編集画面で開いたPSD・調整・表情プリセット・アンカー・顔追跡・マイク口パクが、そのままOBSに反映されます。後から開いたOBSソースも現在の状態に追いつきます。ヘッダーの「OBS」表示で接続状況(表示中の数)を確認できます。
  • OBS専用表示は背景が完全透過になり、操作パネルやFPS表示は映りません。
  • 編集画面を閉じると、OBSは最後に受け取ったモデル・調整のまま、アイドルモーションで動き続けます。顔追跡が約1.2秒届かない場合も通常の動作に戻ります。
  • 配信中は編集用ブラウザを閉じないでください。顔追跡とOBSへの中継はバックグラウンドでも動き続けるようにしてあります(OBSの後ろに隠れていても可)が、環境によって追従が遅れる場合は最小化を避けてください。
  • 編集画面を使わずにOBSだけで表示する場合は、PSDと設定JSONをこのフォルダに置き、http://127.0.0.1:8000/?obs=1&model=mymodel.psd&settings=mymodel.rig.json のように指定できます(どちらも省略可。省略時は sample.psd)。
  • 「OBS表示へ同期する」をOFFにすると、OBSは最後に送った状態のままになります。

Python 3が必要です。自動検出できない場合は環境変数 ANIME25D_PYTHON に python.exe のパスを設定できます。ポート8000を別のアプリが使用している場合は python obs_server.py --port 8001 --open-browser --camera で起動し、OBSのURLも同じポートに変更してください。

中継は obs_server.py を起動したPC内(127.0.0.1)だけで行い、同じオリジンからの検証済みデータだけを受け付けます。映像・音声そのものは中継しません(顔追跡の数値・マイクの音量・設定・PSDのみ)。PSDは中継サーバーのメモリにだけ置かれ、保存されません。

閉じ目レイヤーに eyeclose2(または eye_close2、閉じ目2)を追加すると、通常の閉じ目と 4:1 の確率で切り替わります。eyeclose2 の閉じ時間は通常瞬きの10倍です。

自動で行われること

  • see-through の出力PSDをそのまま受け入れ(mouth→mouth_open 自動リネーム、hair は顔より上の描画順なら前髪・下なら後髪として扱う)
  • 日本語・英語の別名を自動で認識(前髪・白目・瞳・まつ毛・閉じ目・bangs・iris など。下表参照)
  • 閉じ目・閉じ口差分が無い場合、汎用差分を自動生成(アンカーに合わせてスケール・配置し、まつ毛/口の色に自動調整。専用バーで位置・角度を微調整可能)
    • 差分の元絵はリポジトリ直下の eye_close.psd(左右両目を1枚・間を空けて)/ mouth_close.psd を優先使用。無ければ内蔵データを使用
  • 低アルファノイズ除去(連結成分フィルタ)
  • フォルダ内を含む可視画像レイヤーの再帰読み込み
  • 目・眉・まつ毛・閉じ目の左右自動分離(連結成分の重心で判定)
  • まぶた位置・虹彩中心・口・首ピボットなどアンカーの自動検出(アンカー編集モードで修正可能)
  • 髪の房(ストランド)自動検出(毛先輪郭のピーク検出、1レイヤーにつき最大6房)
  • 耳飾り・尻尾の振り子の揺れ
  • レイヤーごとの深度割当てによる擬似3D首振り(パララックス+シアー)
  • 房ごとの2重バネ物理(根元は固く・毛先はふわふわ)、体の傾きへの追従、胸の揺れ、呼吸
  • 閉じ目/閉じ口差分のクロスフェード、瞳のクリップ(白目の形で滑らかに切り抜き。描画順・白目の濃さ・表示状態に左右されない)

レイヤー命名規約

レイヤー名(日本語の「のコピー」「copy」や全角文字、大文字・小文字、_・-・空白の違いは自動正規化されます):

レイヤー名 別名の例 内容 必須 備考
face 顔、輪郭 顔ベース ◎ アンカーの基準。これだけは必ず
eyewhite 白目 白目(左右両方) ○ 左右は自動分離。瞳を切り抜く形
irides 瞳、黒目、iris 虹彩(左右両方) ○ 視線移動・瞳スケール対象
eyelash まつ毛、アイライン まつ毛(開き目) ○
eye_close 閉じ目 閉じ目 ○ まばたきでクロスフェード
eye_close2 / eyeclose2 閉じ目2 長い閉じ目 20%の確率で使用、閉じ時間10倍
eyebrow 眉、眉毛 眉(左右両方) ○ 角度・上下操作対象
mouth_open 口、開き口、mouth 開き口 ○ 開度で顎が下がる
mouth_close 閉じ口 閉じ口 ○
nose 鼻 鼻
ears 耳 耳
earwear ピアス、イヤリング 耳飾り 振り子の揺れ
eyewear 眼鏡、メガネ 眼鏡 頭に追従
facedetail 頬、頬染め、blush 顔の細部
neck 首 首 上端は頭に追従
neckwear ネクタイ、チョーカー 首元の小物
topwear 服、体、上半身 上半身の服 呼吸・胸の揺れ対象
bottomwear スカート、ズボン 下半身の服
handwear 腕、手 腕・手 腕の高さ操作対象
legwear / footwear 脚、靴下 / 靴 脚・靴
headwear 帽子、髪飾り、カチューシャ 頭の飾り
front hair 前髪、bangs 前髪 房物理+3ブロック操作
side hair 横髪、もみあげ 横髪 前髪と同じ揺れ設定
ahoge アホ毛 アホ毛 前髪と同じ揺れ設定
back hair 後ろ髪、後髪 後髪 房物理
hair 髪 髪(前後未指定) 顔より上なら前髪、下なら後髪
tail / wings 尻尾 / 羽、翼 尻尾・翼 尻尾は揺れる
  • 髪を複数レイヤーに分ける場合: front hair_1, front hair_2, 前髪2 … のように連番を付けると、各レイヤーが独立した房グループとして物理演算されます(房数はレイヤー幅から自動決定)。
  • 規約にない名前のレイヤーも読み込まれます(位置から頭部/胴体を推定して追従のみ)。「モデル情報・診断」に未分類として表示されます。
  • レイヤーグループ(フォルダ)内の画像レイヤーにも対応します。非表示のフォルダ・レイヤーは読み込みません。
  • 首(neck)と胴体(topwear)について: see-through の出力をそのまま使うと首と胴体の前後関係の解決が難しく、動かした際に境目が破綻することがあります。うまくいかない場合は、首を胴体レイヤーに統合した一体型(neckレイヤーなし、topwearに首まで含める)にした方が成功しやすいです。
  • キャンバスは正方形推奨(768×768〜2048×2048で動作確認)。

機能

表情プリセット(笑顔/驚き/ジト目/ウインク左右、キー切替)、左右独立の目の開き、眉角度(左右独立+対称)、視線、瞳スケール、目/口の「閉じやすさ」しきい値、前髪3ブロック操作と前髪専用の揺れ・柔らかさ、腕の高さ/位置、胸の揺れ(強さ・位置調整可)、小物の揺れ、体の傾き、アイドル/ランダムモーション、ランダム口パク、マイク口パク(感度・ノイズゲート)、マウス追従、ウェブカメラ追従(頭XYZ・左右のまばたき・口・眉・笑顔・視線、キャリブレーション)、アンカー編集、元に戻す/やり直す、透過PNG・透過動画の書き出し、背景切替(透過/グリーンバック/ダーク)、OBS同期。

構成

index.html           画面構成
lib/app.css          スタイル・レスポンシブレイアウト
lib/app.js           編集UI・アニメーション・OBS表示
lib/renderer.js      WebGL描画(メッシュ・瞳マスク)
lib/runtime.js       入力/設定検証・履歴・メッシュ上限・バネ計算
lib/face-features.js 顔ランドマーク→表情パラメーター(キャリブレーション・フィルタ)
lib/devices.js       カメラ(MediaPipe FaceMesh)・マイク入力
lib/recorder.js      動画書き出し
lib/obs-sync.js      編集画面とOBS表示の同期
lib/psd-worker.js    PSDの解析と自動リグ(バックグラウンド処理)
lib/rigger.js        自動リグ生成(純TypedArray実装、Node でもテスト可能)
lib/ag-psd.min.js    PSDパーサ(ag-psd, MIT)
lib/genericparts.js  汎用閉じ目・閉じ口差分(内蔵フォールバック)
lib/vendor/face_mesh MediaPipe FaceMesh 0.4.1633559619(Apache-2.0、同梱)
eye_close.psd        閉じ目差分の元絵(任意・差し替え可)
mouth_close.psd      閉じ口差分の元絵(任意・差し替え可)
sample2.psd          サンプルA
sample.psd           サンプルB(OBS専用表示の初期モデル)
obs_server.py        ローカル配信・OBSへの中継(追跡値・設定・PSD)
start_obs.bat        Windows用の起動バッチ
tests/               Node・Python・ブラウザの回帰テスト

ランタイムは WebGL1(メッシュワープ+瞳用のマスクテクスチャ)。PSDはブラウザ内で処理し、外部のサーバーへアップロードしません(OBS連携時のみ、同じPC内の obs_server.py へ送ります)。

開発時の検証

追加パッケージなしで Node.js 18以降とPython 3のテストを実行できます。

npm test            # = node tests/*.test.js + python -m unittest

ブラウザのテストは2通りです。

  • ローカルサーバーを起動して http://localhost:8000/tests/browser.html を開き「テストを実行」。合成したテストPSDと仮想入力で、設定保存・履歴・アンカー・検索・拡大・PNG/動画の透過・瞳クリップ・入力の取消・描画復旧・狭い画面など47項目を検証します(実際のカメラ・マイクにはアクセスしません)。
  • npm install --no-save playwright && npx playwright install chromium の後に npm run test:browser。上記に加えて、obs_server.py を起動して編集画面→OBS表示の同期(モデル・表情・スライダー・アンカー・後から開いたOBS)と、偽のWebカメラ映像(tests/fixtures/face.y4m)を使った実際の顔追跡・キャリブレーション・OBSへの中継を検証します。

GitHub Actions(.github/workflows/test.yml)でも同じテストを実行します。

既知の制限

  • 一枚絵の分解はアプリ内では行いません。see-through公式デモ(HuggingFace Space)等で分割したPSDをドロップしてください(後処理は全自動)
  • 口の開きは差分切替+変形の簡易表現(中間差分が増えると滑らかになります)
  • 初期深度は名前ベースですが、読み込み後にレイヤーごとに調整できます。
  • PSDはRGB・8bit/チャンネル、128MB以下、2400万画素以下、一辺16384px以下に対応します。さらに、レイヤー合計画素数・解析メモリ・端末のGPU上限によって読み込めるサイズが制限されます。
  • フォルダの可視性は反映します。グループ合成、不透明度のグループ継承、特殊な描画モード、調整レイヤー、マスク効果の完全な再現は対象外です。必要な効果は画像パーツへ統合してください。
  • file:// 直開きでは解析がメインスレッドになり、解析中に中断できない場合があります。進捗・中断・カメラ・OBS連携を使う場合はlocalhostまたはHTTPSで開いてください。
  • 設定保存にはブラウザのローカルストレージを使用します。プライベートモード・容量制限等で保存できない場合はJSONを書き出してください。
  • 透過動画はWebMのみです。Safariなど透過WebMを書き出せないブラウザでは、背景色付きで書き出してください。
  • 顔追跡の精度は照明・カメラ・眼鏡などに左右されます。うまく判定できないときは「正面を記録」と感度調整を試してください。

License

MIT(同梱の ag-psd も MIT、MediaPipe FaceMesh は Apache-2.0 で lib/vendor/face_mesh/ に同梱)。

一枚絵のレイヤー分解には shitagaki-lab/see-through(Apache-2.0, SIGGRAPH 2026)の利用を想定しています。本ツールは同プロジェクトの出力PSDの後処理・リギングを担う独立したサードパーティ製ツールであり、see-through のコード・モデルは同梱していません。 サンプルPSD の絵の権利は各作者に帰属します。 自作モデルを配布する場合はご自身の権利物をお使いください。

Releases

Packages

Contributors

Languages