3D Pose Editor — ComfyUI Custom Node

An interactive 3D pose editor node for ComfyUI.
Load VRM / GLB / GLTF models directly in the browser, drag bones to pose them, and output the result to your workflow.

ComfyUI 上で動作するインタラクティブな 3D ポーズエディタノードです。
VRM・GLB・GLTF モデルをブラウザから直接読み込み、ボーンをドラッグ操作してポーズを付け、そのままワークフローに出力できます。

---

English

Features / Buttons

Row 1 (capture / timer / camera / model)

| Button | Function | |--------|----------| | 📸 Capture | Send current pose as PNG to node output | | ⏱ | Timer capture toggle — auto-captures every timer_interval seconds | | RC | Reset camera | | OT / PR | Toggle Orthographic / Perspective camera | | VRM | Load VRM / GLB / GLTF file from local disk | | CC | Color correction ON/OFF (sRGB + ACES Filmic) |

Row 2 (pose / library / lights / background)

| Button | Function | |--------|----------| | RP | Reset pose | | ↔ | Mirror pose (flip left ↔ right) | | ⬇️ | Download current pose as JSON file | | 💾 | Save current pose to poses/ folder | | 📂 | Load pose file (.json / .vroidpose) | | 📚 | Open Pose Library | | 💡 | Open Light Editor | | BG | Load background image from local disk | | ✕ | Clear background image and background color | | 🎨 | Scene background color picker |

Row 3 (file name)

Displays the name of the currently loaded VRM / GLB / GLTF file.

Timer Capture (⏱)

Click ⏱ to start / stop the timer.

| State | Color | Behavior | |-------|-------|----------| | OFF | Grey (#555) | No auto-capture | | ON — waiting | Dark red (#7b0000) | Auto-captures every N seconds | | ON — firing | Bright red (#e74c3c) | Flashes for 300 ms on each capture |

The interval is read from the timer_interval node parameter (1 – 3600 s, default 5 s).
While the timer is running, the 📸 Capture button does not flash — only the ⏱ button changes colour.

Installation

Option A: ComfyUI Manager (Recommended)

1. Open ComfyUI Manager and click "Install Custom Nodes".
2. Search for comfyui-vrm-pose-editor.
3. Click Install and restart ComfyUI.

Option B: Manual

1. Place the 3dpose_custom_cm folder inside ComfyUI/custom_nodes/.
2. Restart ComfyUI.
3. Add the "3D Pose Editor" node (category: 3D Pose) from the node menu.

Camera Controls

| Action | Result | |--------|--------| | Left drag | Rotate camera | | Ctrl + Left drag | Pan | | Right drag | Pan | | Scroll wheel | Zoom (default) | | Ctrl + Right drag | Zoom — only when the "Ctrl+Right drag zoom" switch is ON in the Light Editor (see below) | | Alt + Left drag | Zoom (Node 2.0 mode) | | Click gizmo X/Y/Z axis | Snap to that view direction |

On some PCs the scroll wheel does not zoom (mouse/driver dependent). Open the Light Editor (💡) and toggle 🖱 Ctrl+Right drag zoom in the top scene bar to switch from wheel zoom to Ctrl+Right-drag zoom.

Bone Controls

Drag the blue control points on each bone joint.

| Action | Rotation | |--------|----------| | Left / Right drag | Y-axis | | Up / Down drag | X-axis | | Alt + Up / Down drag | Z-axis |

Loading Models

Click the VRM button to select a local .vrm / .glb / .gltf file.
The model is automatically scaled and centred.

• VRM: bones detected via @pixiv/three-vrm HumanBone.
• GLB / GLTF: works with any skeleton-based model.

Default Model

Place one of the following files in the js/ folder to auto-load on startup:

| Filename | Format | |----------|--------| | model.glb | GLB | | model.vrm | VRM | | model.gltf | GLTF |

Priority: model.glb → model.vrm → model.gltf. If none exist, the editor starts without a model.

Pose Library (📚)

Click the 📚 button on any node to open the Pose Library.

• Pose files (.json / .vroidpose) stored in the poses/ folder are displayed as thumbnails.
• Subdirectory filtering: create subfolders inside poses/ to organise poses by category; select a folder from the dropdown to filter.
• Click a thumbnail to apply the pose immediately.
• Right-click for more options:
  • ↔️ Mirror & Apply
  • ⭐ Add / Remove Favorites
  • 📝 Edit Memo
  • ✏️ Rename File
  • 🖼 Regenerate Thumbnail (Front / Back)
• 💾 Save: saves the current editor pose to the poses/ folder as p_HHMMSS.json.
• Thumbnails are auto-generated using the loaded VRM model and cached server-side.

Pose Save / Load

| Button | Action | |--------|--------| | ⬇️ | Download pose as pose.json (browser download) | | 💾 | Save pose to poses/p_HHMMSS.json on the server | | 📂 | Load pose file (or drop onto canvas) |

Supported formats:

| Format | Description | |--------|-------------| | .json (own format) | Saved by ⬇️ or 💾 | | .vroidpose | VRoid Studio pose file (body / arms / legs; finger presets not supported) |

VRM0 / VRM1 Compatibility

Pose JSON is saved in version 2 format (quaternion + vrmVersion tag).
Cross-version conversion (VRM0 ↔ VRM1) is applied automatically on load.
Legacy version 1 (Euler angles) files are still supported.

Mirror Pose (↔)

Click ↔ on the node (or right-click → ↔️ Mirror & Apply in the Pose Library) to flip the current pose left ↔ right.
Left/Right bone pairs are swapped and quaternions are YZ-flipped (qx, -qy, -qz, qw).

Light Editor (💡)

Click 💡 on any node to open the Light Editor panel.

• 3D preview with live bone / camera / light-helper interaction (actual WebGL canvas, not a copy).
• Multiple lights: add any number of lights. Types: ☀ Sun (Directional), 💡 Point, 🔦 Spot, ▭ Box (RectArea), 🌐 Ambient.
• Per-light settings: color, intensity, position XYZ, target XYZ (Directional / Spot), angle & penumbra (Spot), distance & decay (Point / Spot), shadow (Directional only).
• Drag the yellow sphere in the preview to reposition a light in 3D.
• Shadow note: Only DirectionalLight supports castShadow. SpotLight / PointLight shadows are incompatible with the VRM MToon shader.
• Shadow quality: None / Soft PCF / Hard selector.
• 🖱 Ctrl+Right drag zoom: Toggle in the top scene bar. OFF (default) = scroll wheel zoom. ON = disables wheel zoom and lets you zoom by Ctrl+Right-dragging on empty space — useful when the scroll wheel doesn't zoom on some PCs/mice. This setting also applies to the main preview canvas outside the Light Editor.
• 📚 Library: Save and recall complete light presets (all lights + Ground / BG Wall / Shadow settings).

Light Library (📚)

Click 📚 Library in the Light Editor header to open the Library panel.

| Action | Description | |--------|-------------| | 💾 Save Current | Save all current settings as a named preset | | Click a preset card | Apply saved settings immediately | | Right-click a card | Rename or delete the preset | | Search field | Filter presets by name | | ↺ Reload | Refresh the preset list from the server |

Presets are stored server-side in .light_library/ inside the node folder.
They persist across browser restarts and are available on any machine sharing the same ComfyUI server.

Note: Texture images are not saved in presets (binary data is excluded).
All numeric settings (color, intensity, positions, Ground/Wall/Shadow values) are saved and restored.

Ground & Background Wall

| Control | Function | |---------|----------| | 🟫 Ground ON/OFF | Toggle ground plane (receives shadows) | | Y slider | Ground height | | 🖼 BG Wall ON/OFF | Toggle background wall (receives shadows) | | Z slider | Wall depth | | 🎨 Color picker | Surface color | | 📁 Tex | Load image texture (tiled) | | Tile | Texture repeat count | | 🕶 SC | Shadow Catcher — surface becomes transparent, shows shadows only | | 影濃度 / Opacity | Shadow darkness (0.01 – 1.0) |

Aspect Ratio Frame

When output_size_mode is Custom, a letterbox overlay is drawn in real time to show the output crop area.
Capture outputs only the framed region — no stretching.

Shape Keys

Click the Shape Keys header at the bottom of the node to expand the panel.
Adjust morphs / expressions with sliders (0.0 – 1.0) in real time.

Color Correction (CC)

Toggle sRGB color space + ACES Filmic tone mapping.
Enable if VRoid Studio / Blender models appear too dark.

---

日本語

機能・ボタン一覧

1行目（キャプチャ・タイマー・カメラ・モデル）

| ボタン | 機能 | |--------|------| | 📸 Capture | 現在のポーズを PNG としてノード出力に送信 | | ⏱ | タイマーキャプチャのトグル（timer_interval 秒ごとに自動キャプチャ） | | RC | カメラをリセット | | OT / PR | Orthographic / Perspective カメラを切り替え | | VRM | VRM / GLB / GLTF ファイルをローカルから読み込む | | CC | カラー補正 ON/OFF（sRGB + ACES Filmic） |

2行目（ポーズ・ライブラリ・ライト・背景）

| ボタン | 機能 | |--------|------| | RP | ポーズをリセット | | ↔ | ポーズを左右反転 | | ⬇️ | 現在のポーズを JSON ファイルとしてダウンロード | | 💾 | 現在のポーズを poses/ フォルダに保存 | | 📂 | ポーズファイルを読み込む（.json / .vroidpose） | | 📚 | ポーズライブラリを開く | | 💡 | ライトエディタを開く | | BG | 背景画像をローカルから読み込む | | ✕ | 背景画像および背景色をクリア | | 🎨 | シーン背景色ピッカー |

3行目（ファイル名）

現在読み込まれている VRM / GLB / GLTF のファイル名を表示。

タイマーキャプチャ（⏱）

⏱ ボタンをクリックしてタイマーを開始 / 停止します。

| 状態 | 色 | 動作 | |------|----|----| | OFF | グレー（#555） | 自動キャプチャなし | | ON — 待機中 | 暗い赤（#7b0000） | N 秒ごとに自動キャプチャ | | ON — 実行瞬間 | 明るい赤（#e74c3c） | 300ms 点灯して暗い赤に戻る |

間隔は timer_interval ノードパラメータ（1〜3600 秒、デフォルト 5 秒）で指定します。
タイマー動作中は 📸 Capture ボタンは変化せず、⏱ ボタンのみ色が変わります。

インストール

Option A: ComfyUI Manager（推奨）

1. ComfyUI Manager を開き、「カスタムノードをインストール」 をクリック。
2. comfyui-vrm-pose-editor を検索。
3. Install をクリックして ComfyUI を再起動。

Option B: 手動インストール

1. 3dpose_custom_cm フォルダを ComfyUI/custom_nodes/ に配置。
2. ComfyUI を再起動。
3. ノードメニューから "3D Pose Editor"（カテゴリ: 3D Pose）を追加。

カメラ操作

| 操作 | 動作 | |------|------| | 左ドラッグ | カメラ回転 | | Ctrl + 左ドラッグ | パン（平行移動） | | 右ドラッグ | パン（平行移動） | | ホイール | ズーム（既定） | | Ctrl + 右ドラッグ | ズーム — ライトエディタの「Ctrl+右ドラッグでズーム」スイッチが ON のときのみ有効（後述） | | Alt + 左ドラッグ | ズーム（Node2.0 モード時） | | ビューギズモ軸クリック | その方向へスナップ |

PC 環境によってはマウスホイールでズームできない場合があります（マウス・ドライバ依存）。ライトエディタ（💡） を開き、上部の Scene バーにある 🖱 Ctrl+右ドラッグでズーム をトグルすると、ホイールズームから Ctrl+右ドラッグズームに切り替えられます。

ボーン操作

ボーン上の青い点（コントロールポイント）をドラッグします。

| 操作 | 動作 | |------|------| | 左右ドラッグ | Y 軸回転 | | 上下ドラッグ | X 軸回転 | | Alt + 上下ドラッグ | Z 軸回転 |

ポーズライブラリ（📚）

ノード上の 📚 ボタンをクリックするとポーズライブラリが開きます。

• poses/ フォルダ内のポーズファイル（.json / .vroidpose）をサムネイル一覧で表示。
• サブディレクトリフィルター: poses/ 内にサブフォルダを作成してポーズをカテゴリ分けし、ドロップダウンで絞り込み。
• サムネイルをクリックするとポーズを即時適用。
• 右クリックでメニュー:
  • ↔️ Mirror & Apply（左右反転して適用）
  • ⭐ お気に入り追加 / 解除
  • 📝 メモ編集
  • ✏️ ファイル名変更
  • 🖼 サムネイル再生成（正面 / 背面）
• 💾 Save: 現在のエディタのポーズを poses/p_HHMMSS.json として保存。
• サムネイルは読み込み済み VRM を使ってオフスクリーンで自動生成・キャッシュ。

ライトエディタ（💡）

ノードの 💡 ボタンをクリックするとライトエディタが開きます。

• 3D プレビュー: 実際の WebGL canvas を埋め込み（コピーではない）。ボーン操作・カメラ操作・ライトヘルパードラッグがプレビュー内でネイティブに動作。
• 複数ライト: 任意の数を追加可能。タイプ: ☀ Sun (Directional) / 💡 Point / 🔦 Spot / ▭ Box (RectArea) / 🌐 Ambient。
• ライト設定: 色・強度・位置 XYZ・ターゲット XYZ（Directional/Spot）・角度＆ペナンブラ（Spot）・距離＆減衰（Point/Spot）・シャドウ（Directional のみ）。
• 黄色球体をドラッグしてプレビュー内でライトを 3D 移動。
• シャドウ注意: DirectionalLight のみ castShadow 対応。SpotLight/PointLight のシャドウは VRM MToon シェーダーと非互換。
• 🖱 Ctrl+右ドラッグでズーム: 上部の Scene バーにあるトグルスイッチ。OFF（既定）＝マウスホイールでズーム。ON＝ホイールズームを無効化し、何もない場所での Ctrl+右ドラッグでズームできるようにする。マウスやドライバの相性でホイールズームが効かない環境向け。この設定はライトエディタ外のメインプレビューキャンバスにも適用される。
• 📚 Library: ライト設定プリセット（全ライト ＋ Ground / BG Wall / Shadow 設定）の保存・呼び出し。

ライトライブラリ（📚）

ライトエディタのヘッダーにある 📚 Library ボタンをクリックするとライブラリパネルが開きます。

| 操作 | 内容 | |------|------| | 💾 Save Current | 現在の全設定をプリセット名を付けて保存 | | プリセットカードをクリック | 保存済みの設定を即時適用 | | プリセットカードを右クリック | 名前変更・削除 | | 検索フィールド | 名前で絞り込み | | ↺ リロード | サーバーから一覧を再読み込み |

プリセットはサーバー側の .light_library/ フォルダに保存されます（ノードフォルダ内）。
ブラウザを再起動しても残り、同じ ComfyUI サーバーを使う別のマシンからも利用できます。

注意: テクスチャ画像はプリセットに保存されません。
色・強度・位置・Ground/Wall/Shadow のすべての数値設定は保存・復元されます。

地面・背景壁

| コントロール | 機能 | |------------|------| | 🟫 Ground ON/OFF | 地面（影を受ける）の表示切替 | | Y スライダー | 地面の高さ | | 🖼 BG Wall ON/OFF | 背景壁（影を受ける）の表示切替 | | Z スライダー | 壁の奥行き | | 🎨 カラーピッカー | 面の色 | | 📁 Tex | テクスチャ画像読み込み（タイル表示） | | Tile | テクスチャの繰り返し数 | | 🕶 SC | シャドウキャッチャー — 面を透明にして影のみ表示 | | 影濃度 | 影の暗さ（0.01 〜 1.0） |

ポーズ左右反転（↔）

ノードの ↔ ボタン、またはポーズライブラリの右クリックメニュー ↔️ Mirror & Apply で現在のポーズを左右反転します。
Left/Right ボーンペアを入れ替え、クォータニオンを YZ 反転 (qx, -qy, -qz, qw) して適用します。

デフォルトモデルの設定

js/ フォルダに以下のいずれかを配置すると起動時に自動ロードされます。

| ファイル名 | 形式 | |-----------|------| | model.glb | GLB | | model.vrm | VRM | | model.gltf | GLTF |

優先順位: model.glb → model.vrm → model.gltf

---

Node I/O

| Item | Type | Description | |------|------|-------------| | background_image | IMAGE (optional) | Background composited with the captured pose on the Python side | | output_size_mode | Standard / Background / Custom | Output resolution mode | | custom_width / custom_height | INT | Output size in Custom mode | | timer_interval | INT | Timer capture interval in seconds (1 – 3600, default 5) | | output: image | IMAGE | Captured pose image (Torch tensor) |

---

Technical Specs

• Frontend: JavaScript + Three.js r160 + @pixiv/three-vrm 2.1.0 (bundled locally)
• Backend: Python — Base64 PNG → PIL → Torch Tensor
• Pose Library API: aiohttp routes registered via @PromptServer.instance.routes
• Light Library API: GET/POST /light_library/* — presets stored in .light_library/ as l_HHMMSS.json
• Capture: letterbox-cropped to output aspect ratio (no stretching)
• Camera: Perspective (FOV 45°) / Orthographic toggle
• Pose JSON: version 2 (quaternion + vrmVersion tag, VRM0/VRM1 cross-compatible)
• VRM0 quaternion: Unity left-hand → Three.js right-hand (x, y, -z, -w)
• VRM1 quaternion: VRM0 conversion + VRM0→VRM1 (x, -y, z, -w)
• Pose mirror: Left↔Right bone swap + YZ-flip (qx, -qy, -qz, qw)
• Lights: managed multi-light system (Directional / Point / Spot / RectArea / Ambient); shadow restricted to DirectionalLight (VRM MToon constraint)
• Ground / BG Wall: MeshStandardMaterial (opaque) or ShadowMaterial (shadow catcher); color, texture, tile, height/depth adjustable
• Background color: scene.background = THREE.Color via color picker; transparent by default
• Zoom mode: wheel zoom (default) or Ctrl+Right-drag zoom, toggled from the Light Editor scene bar (editor.getZoomMode() / setZoomMode()). Persisted in localStorage (vrmPoseEditor_zoomMode), shared across all ComfyUI nodes and pages on the same origin
• Light presets: full scene snapshot (all lights + Ground/Wall/Shadow values); texture images excluded; stored server-side as JSON files
• Core module: js/pose_editor_core.js exports initPoseEditor3D() with zero ComfyUI dependency, so it can be imported directly from external pages (e.g. /extensions/comfyui-vrm-pose-editor/pose_editor_core.js) alongside light_editor.js / pose_library.js

---

License

MIT License