Anime2.5DRig/README.md

# Anime2.5DRig

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

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

## デモ / 使い方

1. このリポジトリを GitHub Pages で公開（Settings → Pages → Branch: main / root）するか、ローカルで:
   ```
   python -m http.server 8000
   # → http://localhost:8000
   ```
2. ページを開き、パーツ分けPSDをドロップ（または「sample.psd を読み込む」）。
3. 自動リグが走り、その場でアイドルモーション・まばたき・口パク・髪物理付きで動きます。

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

## 自動で行われること

- [see-through](https://github.com/shitagaki-lab/see-through) の出力PSDをそのまま受け入れ（`mouth`→`mouth_open` 自動リネーム）
- **閉じ目・閉じ口差分が無い場合、汎用差分を自動生成**（アンカーに合わせてスケール・配置し、まつ毛/口の色に自動調整。専用バーで位置・角度を微調整可能）
  - 差分の元絵はリポジトリ直下の `eye_close.psd`（左右両目を1枚・間を空けて）/ `mouth_close.psd` を優先使用。無ければ内蔵データを使用
- 低アルファノイズ除去（連結成分フィルタ）
- 目・眉・まつ毛・閉じ目の**左右自動分離**（連結成分の重心で判定）
- まぶた位置・虹彩中心・口・首ピボットなど**アンカーの自動検出**
- 髪の**房（ストランド）自動検出**（毛先輪郭のピーク検出、1レイヤーにつき最大6房）
- レイヤーごとの深度割当てによる**擬似3D首振り**（パララックス+シアー）
- 房ごとの2重バネ物理（**根元は固く・毛先はふわふわ**）、胸の揺れ、呼吸
- 閉じ目/閉じ口差分の**クロスフェード**、瞳のステンシルクリップ（白目内に制限）

## レイヤー命名規約

レイヤー名（日本語の「のコピー」や全角文字は自動正規化されます）:

| レイヤー名 | 内容 | 必須 | 備考 |
|---|---|---|---|
| `face` | 顔ベース | ◎ | アンカーの基準。これだけは必ず |
| `eyewhite` | 白目（左右両方） | ○ | 左右は自動分離 |
| `irides` | 虹彩（左右両方） | ○ | 視線移動・瞳スケール対象 |
| `eyelash` | まつ毛（開き目） | ○ | |
| `eye_close` | 閉じ目 | ○ | まばたきでクロスフェード |
| `eyebrow` | 眉（左右両方） | ○ | 角度・上下操作対象 |
| `mouth_open` | 開き口 | ○ | 開度で顎が下がる |
| `mouth_close` | 閉じ口 | ○ | |
| `nose` | 鼻 | | |
| `ears` | 耳 | | |
| `earwear` | 耳飾り | | |
| `neck` | 首 | | 上端は頭に追従 |
| `topwear` | 上半身の服 | | 呼吸・胸の揺れ対象 |
| `bottomwear` | 下半身の服 | | |
| `handwear` | 腕・手 | | 腕の高さ操作対象 |
| `headwear` | 帽子・カチューシャ等 | | |
| `front hair` | 前髪 | | 房物理+3ブロック操作 |
| `back hair` | 後髪 | | 房物理 |

- **髪を複数レイヤーに分ける場合**: `front hair_1`, `front hair_2`, `back hair_1` … のように `_連番` を付けると、各レイヤーが独立した房グループとして物理演算されます（房数はレイヤー幅から自動決定）。
- 規約にない名前のレイヤーも読み込まれます（位置から頭部/胴体を推定して追従のみ）。
- レイヤーグループ（フォルダ）は未対応です。フラットな構成にしてください。
- **首（neck）と胴体（topwear）について**: see-through の出力をそのまま使うと首と胴体の前後関係の解決が難しく、動かした際に境目が破綻することがあります。うまくいかない場合は、首を胴体レイヤーに統合した**一体型**（neckレイヤーなし、topwearに首まで含める）にした方が成功しやすいです。
- キャンバスは正方形推奨（768×768〜2048×2048で動作確認）。

## 機能

表情プリセット（笑顔/驚き/ジト目/ウインク左右）、左右独立の目の開き、眉角度（左右独立+対称）、視線、瞳スケール、目/口の「閉じやすさ」しきい値、前髪3ブロック操作と**前髪専用の揺れ・柔らかさ**、腕の高さ/位置、胸の揺れ（強さ・位置調整可）、体の傾き、アイドル/ランダムモーション、ランダム口パク、マイク口パク、マウス追従、**ウェブカメラ追従**（頭XYZ・まばたき左右・口・視線）、背景切替（透過/グリーンバック）。

## 構成

```
index.html      アプリ本体（UI + WebGLランタイム）
lib/rigger.js   自動リグ生成（純TypedArray実装、Node でもテスト可能）
lib/ag-psd.min.js  PSDパーサ（ag-psd, MIT）
lib/genericparts.js  汎用閉じ目・閉じ口差分（内蔵フォールバック）
eye_close.psd    閉じ目差分の元絵（任意・差し替え可）
mouth_close.psd  閉じ口差分の元絵（任意・差し替え可）
sample.psd      サンプルモデル（各自で配置）
```

ランタイムは WebGL1（メッシュワープ+ステンシル）。外部通信はカメラ追従を有効化した時の MediaPipe CDN 読み込みのみです。

## 既知の制限

- 一枚絵の分解はアプリ内では行いません。[see-through公式デモ（HuggingFace Space）](https://huggingface.co/spaces/24yearsold/see-through-demo)等で分割したPSDをドロップしてください（後処理は全自動）
- 口の開きは差分切替+変形の簡易表現（中間差分が増えると滑らかになります）
- 深度は名前ベースの固定テーブル（レイヤー順は PSD のまま尊重）

## License

MIT（同梱の ag-psd も MIT、MediaPipe は Apache-2.0 を CDN 参照）。

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