Anime2.5DRig-K/README.md

# Anime2.5DRig - Koibumi Actor 2.5D Lab

[852wa/Anime2.5DRig](https://github.com/852wa/Anime2.5DRig) をベースに、PSD パーツ分けキャラクターをブラウザ上で 2.5D 的に動かす実験 fork です。

元プロジェクトの「PSD をドロップすると自動リグされ、その場で動く」軽さはそのままに、顔・髪・胸まわりの立体感、キャラクターごとの調整値保存、デコ見せ/分け前髪への対応を追加しています。

オリジナル: <https://852wa.github.io/Anime2.5DRig/>

## この fork について

このリポジトリは、オリジナルの Anime2.5DRig の自動リグ、WebGL メッシュワープ、髪物理、表情操作を土台にした研究用ラボです。

主なテーマは、従来のレイヤー深度によるパララックス表現を、顔バウンディングボックスに合わせた楕円体シェル投影へ拡張し、より大きな首振りや横顔の説得力を出すことです。

## 追加機能

### 3Dシェル首振り

「疑似3D」セクションの `3Dシェル` で、従来のパララックス方式と新しい楕円体シェル方式をブレンドできます。

頭部グループの頂点を顔にフィットした楕円体の殻へ持ち上げ、ヨー/ピッチ回転後に透視投影して戻すことで、輪郭の回り込み、奥側の短縮、鼻先・顎先の先行感が出ます。

### 横顔カーブ

「横顔カーブ」セクションで、額・鼻根・鼻先・上唇・顎の 5 点をドラッグして横顔プロファイルを調整できます。

カーブは Catmull-Rom 補間で評価され、`鼻の高さ`、`顎の高さ`、`Eライン` のスライダーとも一方向同期します。カーブ設定は localStorage に保存されます。

### 髪シェルと生え際固定

前髪は HEAD より少し大きい HAIR シェルに乗り、`前髪の浮き` と `前髪のふくらみ` で額からの浮き方を調整できます。

デコ見せや分け前髪では、生え際が額から浮くと破綻して見えるため、「前髪」セクションに `生え際を固定` を追加しました。

固定領域は `密着域 中心X/Y`、`密着域 幅/高さ` で矩形指定します。矩形内は顔と同じ HEAD シェルへ完全追従し、`境界ぼかし` の外側だけが髪シェルへ戻ります。`密着域を表示` を使うと、前髪メッシュ上に固定範囲の境界を表示できます。

### 前髪の頭頂回り込み

`頭頂回り込み` スライダーで、前髪上部を手前に出っ張らせず、画面上で頭頂側へ丸く寄せられます。

生え際固定領域は固定を優先するため、根元を揺らさずに上側だけ回り込ませる調整ができます。

### 胸カーブと胸まわり

「胸カーブ」セクションで、首元から腰までの側面プロファイルを調整できます。

胸先、下乳、腰へ向かう張り出しをカーブで持たせ、体の回転時に近い側/遠い側の胸の見え方を変えます。`張り出し(手前)`、`引っ張り(奥)`、`胸中央`、`左/右乳首 位置` でモデルごとの見え方を詰められます。

### 調整値 JSON

「ユーティリティ」セクションの `調整値を書出` / `調整値を読込` で、全スライダー値、横顔カーブ、胸カーブ、生え際固定 ON/OFF を JSON として外部保存できます。

PSD 本体と調整値を分けて管理できるため、キャラクターごとのチューニングを後から再読み込みできます。

### キャンバス録画

「ユーティリティ」セクションの `録画開始` で、表示中のキャラクターキャンバスを WebM として録画できます。もう一度押すと録画を停止し、`.webm` ファイルとして保存します。

録画されるのはキャンバス部分のみです。スライダー UI も含めて撮りたい場合は、OS 側の画面録画を使ってください。

### ポーズプリセット

「現在を保存」で全スライダー値をスナップショットし、localStorage に保存できます。

保存したポーズはクリックで適用、Shift+クリックで削除できます。`連続再生` では保存順にイージング付きで巡回し、アイドル・まばたき・口パクを重ねて待機モーションとして使えます。

## 使い方

ローカルで開く場合:

```sh
python -m http.server 8000
```

その後、ブラウザで `http://localhost:8000` を開きます。

1. パーツ分け PSD をページへドロップ、または `PSDファイルを選ぶ` から読み込みます。
2. 自動リグが走り、表情、首振り、髪物理、呼吸、胸揺れが有効になります。
3. `疑似3D`、`横顔カーブ`、`前髪`、`胸カーブ` をモデルに合わせて調整します。
4. 必要に応じて `調整値を書出` で JSON を保存します。

カメラ追従とマイク口パクは、ブラウザの権限仕様により HTTPS または localhost でのみ動作します。

## PSD レイヤー命名規約

レイヤー名は日本語の「のコピー」や全角文字をある程度正規化して読み込みます。基本的には以下の名前を使います。

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

髪を複数レイヤーに分ける場合は、`front hair_1`、`front hair_2`、`back hair_1` のように `_連番` を付けると、各レイヤーが独立した房グループとして物理演算されます。

レイヤーグループは未対応です。PSD はフラットなレイヤー構成にしてください。

## 自動で行われること

- 低アルファノイズ除去
- 目・眉・まつ毛・閉じ目の左右自動分離
- まぶた位置、虹彩中心、口、首ピボットなどのアンカー自動検出
- 髪の房ストランド自動検出
- レイヤー名ベースの深度割り当て
- WebGL メッシュワープ
- 髪の 2 重バネ物理
- 呼吸、胸揺れ、腕操作
- 閉じ目/閉じ口差分のクロスフェード
- 瞳のステンシルクリップ

## サンプル PSD について

公開や配布に使う PSD は、自作または使用許諾を確認できるものを使ってください。

この lab では、公開用に使いやすい確認素材として `original-adult-sample.psd` と調整値 JSON を用意しています。

### オリジナルサンプル

1. `original-adult-sample.psd` を読み込みます。
2. 「ユーティリティ」→ `調整値を読込` から `original-adult-sample_tuning_2026-07-11T03-03-18.json` を読み込みます。

この組み合わせは、デコ見せ/分け前髪の生え際固定、頭頂回り込み、3D シェル調整の確認用です。

### 852wa 版 sample.psd 用の調整値

1. `sample.psd` を読み込みます。
2. 「ユーティリティ」→ `調整値を読込` から `sample_tuning_2026-07-11T03-05-58.json` を読み込みます。

`sample.psd` は元プロジェクト由来の動作確認サンプルです。公開や再配布の範囲は、元プロジェクトのライセンスとサンプル素材の扱いを確認してください。

## 既知の制限

- 一枚絵からの自動パーツ分解は未対応です。パーツ分け PSD が必要です。
- 主線はテクスチャに描かれた線のため、深い角度では輪郭位置とずれます。
- 遮蔽はレイヤー描画順が基本で、深度バッファによる本格的な前後判定はしていません。
- 楕円体の半径、最大回転角、髪シェルの厚みは経験的な初期値です。
- 口の開きは差分切替と簡易変形です。中間差分が増えるとより滑らかになります。
- レイヤー名にない独自パーツも読み込めますが、細かな専用変形は付きません。

## 構成

```text
index.html          アプリ本体 UI + WebGL ランタイム
lib/rigger.js       自動リグ生成
lib/ag-psd.min.js   PSD パーサ ag-psd
original-adult-sample.psd                         オリジナル動作確認サンプル
original-adult-sample_tuning_2026-07-11T03-03-18.json  オリジナルサンプル用調整値
sample.psd                                      852wa 版 sample.psd
sample_tuning_2026-07-11T03-05-58.json          sample.psd 用調整値
```

ランタイムは WebGL1 です。外部通信は、カメラ追従を有効化したときの MediaPipe CDN 読み込みのみです。

## 謝辞

この fork は [852wa/Anime2.5DRig](https://github.com/852wa/Anime2.5DRig) の分かりやすい構造と自動リグ実装の上に成り立っています。

PSD をブラウザへドロップするだけで動く、という元実装の体験があったからこそ、3D シェルや生え際固定の実験まで自然に拡張できました。素晴らしいツールを公開してくださった 852wa さんに感謝します。

## License

MIT。

同梱ライブラリの ag-psd は MIT、カメラ追従で参照する MediaPipe は Apache-2.0 です。