# OpenPose Studio for ComfyUI 🤸
OpenPose Studio is an advanced ComfyUI extension for creating, editing, previewing, and organizing OpenPose poses with a streamlined interface. It makes it easy to adjust keypoints visually, save and load pose files, browse pose presets and galleries, manage pose collections, merge multiple poses, and export clean JSON data for use in ControlNet and other pose-driven workflows.
---
## Table of Contents
- ✨ [Features](#features)
- 📱 [Responsive Mobile Interface](#responsive-mobile-interface)
- 📦 [Installation](#installation)
- 🎯 [Usage](#usage)
- 🖐️ [Hand Editing](#hand-editing)
- 🔧 [Nodes](#nodes)
- ⌨️ [Editor Controls & Shortcuts](#editor-controls--shortcuts)
- 📋 [Format Specifications](#format-specifications)
- 🖼️ [Gallery & Pose Management](#gallery--pose-management)
- 🔀 [Pose Merger](#pose-merger)
- 🎨 [Render](#render)
- 🖼️ [Background Reference](#background-reference)
- 🗺️ [Areas Input](#areas-input)
- 🔗 [Pose Keypoint Input](#pose-keypoint-input)
- ⚠️ [Known Limitations](#known-limitations)
- 🔍 [Troubleshooting](#troubleshooting)
- 🤝 [Contributing](#contributing)
- 💙 [Funding & Support](#funding--support)
- 📄 [License](#license)
---
## Features
✨ **Core Capabilities**
- Real-time OpenPose keypoint editing with visual feedback
- Individual hand keypoint editing in a focused, zoomed hand editor
- Modern native Canvas rendering engine (faster, smoother, fewer moving parts)
- Interactive editing UX: clear active selection + pose hover preselection
- Constrained transforms so keypoints don’t drift out of canvas bounds
- JSON import/export for single poses and pose collections
- Standard OpenPose JSON export (portable to other tools)
- Legacy JSON compatibility (can load and correctly edit older non-standard JSON)
✨ **Advanced Features**
- **Render Toggles**: Optionally render Body / Hands / Face
- **Pose Gallery**: Browse and preview poses from `poses/`
- **Pose Collections**: Multi-pose JSON files shown as individual selectable poses
- **Pose Merger**: Combine multiple JSON files into organized collections
- **Quick Cleanup Actions**: Remove Face keypoints and/or Left/Right Hand keypoints when present
- **Optional Cleanup on Export**: Remove Face and/or Hands keypoints when exporting pose packs
- **Background Overlay System**: Selectable contain/cover modes with opacity control
- **Undo**: Full editing history during session
✨ **Data Handling**
- Automatic pose file discovery from `poses/` (including subdirectories)
- Validation and error recovery for malformed JSON files
- Support for partial poses (subset of body keypoints)
- Pixel-space coordinates matching pose files for seamless compatibility
✨ **UI & Integration**
- Fully responsive layout: adapts to any window size in real time and stays centered
- Auto-fit scaling when the canvas would not otherwise fit on screen
- Improved canvas visuals: background grid + center axes styled similarly to Blender
- Persistence across restarts: gallery view mode + background overlay settings restored on launch
- Native ComfyUI integrations: toasts + dialogs (with safe fallback)
## Responsive Mobile Interface
OpenPose Studio is fully responsive and touch-friendly on mobile browsers. The Editor keeps the canvas usable on narrow screens, exposes Preset and COCO keypoint tools as focused views, and provides a compact Gallery with multiple thumbnail densities.
Canvas editing, preset controls, missing-keypoint management, and the Small Icons gallery view on Android.
---
If you have an idea for a new feature, I would love to hear it — we may be able to implement it quickly. Please submit feedback, ideas, or suggestions via the repository Issues page: https://github.com/andreszs/comfyui-openpose-studio/issues
## Installation
### Requirements
- ComfyUI (recent build)
- Python 3.10+
### Option 1: Native Extension Manager (recommended)
1. Open ComfyUI's native **Extension Manager**, then open **Nodes Manager**.
2. Search for `openpose-studio` and select **OpenPose Studio**.
3. Click **Install** and restart ComfyUI when the installation finishes.
### Option 2: Manual installation
Open a terminal in `ComfyUI/custom_nodes/` and clone the repository:
```bash
git clone https://github.com/andreszs/comfyui-openpose-studio.git
```
Restart ComfyUI after cloning the repository.
### Verify the installation
Confirm that **OpenPose Studio** appears in the node menu under `image > OpenPose Studio`.
---
## Usage
### Basic Workflow
1. Add the **OpenPose Studio** node to your workflow
2. Click the node's preview canvas to open the editor UI
3. Select a pose from the presets or gallery to insert into canvas
4. Adjust keypoints by dragging them on the canvas
5. Click **Apply** to render the pose. This will create the serialized JSON in the node.
6. Connect the `image` output to subsequent image nodes
7. Connect the `kps` output to ControlNet/OpenPose compatible nodes
### Editor Preview
### Hand Editing
Imported OpenPose hands can be transformed as a group or refined one keypoint at a time. Select a hand on the canvas to display its transform box and use the surrounding handles to resize, rotate, mirror, or open the focused hand editor.
You can also open the focused editor directly from the pencil icon beside **Left hand** or **Right hand** in the sidebar. In this view, drag keypoints 1–20 to adjust the fingers while keypoint 0 remains the locked hand anchor. Hovering a sidebar entry highlights its matching point. Use the check button to apply the entire hand-editing session as one undoable change, or use the close button or **Escape** to discard it.
---
## Nodes
### OpenPose Studio
**Category:** `image`
- **Input:** `Pose JSON` (STRING) — standard OpenPose-style JSON.
- **Optional Inputs:**
- `areas` (`CONDITIONING_AREAS`) — area overlay data; connect the `areas_out` output of a [Conditioning Pipeline (Combine)](https://github.com/andreszs/comfyui-lora-pipeline) node to visualize conditioning regions on the canvas
- `pose_keypoint` (`POSE_KEYPOINT`) — detected pose data; connect the output of a **DWPose Estimator** node to load upstream-detected poses directly into the editor
- **Options:**
- `render body` — include body in the rendered preview/output image
- `render hands` — include hands in the rendered preview/output image (if present in the JSON)
- `render face` — include face in the rendered preview/output image (if present in the JSON)
- **Outputs:**
- `IMAGE` — Rendered pose visualization as RGB image (float32, 0-1 range)
- `JSON` — OpenPose-style pose JSON with canvas dimensions and people array containing keypoint data
- `KPS` — Keypoint data in POSE_KEYPOINT format, compatible with ControlNet
- **UI:** Click the node preview to open the interactive editor. Use the **open editor** button (pencil icon) to edit the pose directly.
#### Node Screenshot
---
## Editor Controls & Shortcuts
### Keyboard Shortcuts
| Control | Action |
|---------|--------|
| **Enter** | Apply pose and close editor |
| **Escape** | Cancel and discard changes |
| **Ctrl+Z** | Undo last action |
| **Ctrl+Y** | Redo last undone action |
| **Delete** | Remove selected keypoint |
### Canvas Interactions
- **Click**: Select keypoint
- **Drag**: Move keypoint to new position
- **Scroll**: Zoom in/out on canvas (TO-DO)
### Background Reference
Load reference images (e.g., anatomy guides, photo references) as non-destructive overlays during pose editing. Use **Contain** mode to fit images within the canvas or **Cover** mode to fill the canvas. Adjust opacity as needed.
- **Load Image**: Import reference image from disk
- **Contain/Cover**: Choose scaling mode
- **Opacity**: Adjust transparency (0-100%)
> [!NOTE]
> Background images persist during the ComfyUI session but are **not** saved in workflows.
### Areas Input
The **areas** input is an **optional** connection that overlays conditioning area boundaries on the canvas during pose editing.
Connect the `areas_out` output of the [**Conditioning Pipeline (Combine)**](https://github.com/andreszs/comfyui-lora-pipeline) node from the [ComfyUI-LoRA-Pipeline](https://github.com/andreszs/comfyui-lora-pipeline) repository to visualize which regions each area targets while you position your poses.
Each area is displayed as a labeled badge on the canvas. Click any badge to **enable or disable** that area individually, letting you focus on the regions relevant to your current pose.
This combination is particularly useful when building multi-character workflows: [ComfyUI-LoRA-Pipeline](https://github.com/andreszs/comfyui-lora-pipeline) handles the per-area conditioning and LoRA assignment, while OpenPose Studio keeps the pose placement accurate within each region. The result is a straightforward, non-destructive setup where both per-area and per-pose LoRAs can be applied simultaneously without interference. If you are not yet familiar with area-based conditioning, the [ComfyUI-LoRA-Pipeline](https://github.com/andreszs/comfyui-lora-pipeline) extension is designed exactly for this kind of workflow and pairs well with this node.
For a real-world example of all three repos working together — area conditioning, OpenPose control, and style layering — see this [step-by-step workflow guide](https://www.andreszsogon.com/building-a-multi-character-comfyui-workflow-with-area-conditioning-openpose-control-and-style-layering/).
### Pose Keypoint Input
The **pose_keypoint** input is an **optional** connection that lets OpenPose Studio consume pose data detected upstream in your workflow.
Connect the output of a **DWPose Estimator** node to this input. The detected keypoints are loaded directly into the editor, where you can inspect, refine, or extend them before rendering.
---
## Format Specifications
This editor fully supports **OpenPose COCO-18 (body)** editing and individual **OpenPose hand keypoint** editing. Face keypoints are preserved and rendered but remain pass-through data and cannot currently be edited individually.
### OpenPose COCO-18 keypoints (body)
COCO-18 uses **18 body keypoints**. The pose is stored as a flat array named `pose_keypoints_2d` with the pattern:
`[x0, y0, c0, x1, y1, c1, ...]`
Where each keypoint has:
- `x`, `y`: pixel coordinates in the canvas
- `c`: confidence (commonly `0..1`; `0` can be used for “missing” points)
Keypoint order (index → name):
| Index | Name |
|------:|------|
| 0 | Nose |
| 1 | Neck |
| 2 | Right Shoulder |
| 3 | Right Elbow |
| 4 | Right Wrist |
| 5 | Left Shoulder |
| 6 | Left Elbow |
| 7 | Left Wrist |
| 8 | Right Hip |
| 9 | Right Knee |
| 10 | Right Ankle |
| 11 | Left Hip |
| 12 | Left Knee |
| 13 | Left Ankle |
| 14 | Right Eye |
| 15 | Left Eye |
| 16 | Right Ear |
| 17 | Left Ear |
> [!NOTE]
> **COCO** refers to the *Common Objects in Context* keypoint convention/dataset naming widely used in pose estimation. “COCO-18” here means the OpenPose body layout with 18 keypoints.
### Minimal JSON shape
A typical single-pose OpenPose-style JSON includes canvas dimensions and one `people` entry with `pose_keypoints_2d`:
```json
{
"canvas_width": 512,
"canvas_height": 512,
"people": [
{
"pose_keypoints_2d": [0, 0, 0, 0, 0, 0 /* ... 18 * 3 values total ... */]
}
]
}
```
> [!NOTE]
> The editor can handle partial poses (some keypoints missing). Missing points are typically represented as 0,0,0. You can also delete distal keypoints using the Pose Editor.
### Further reading
- History & context: "What is OpenPose — Exploring a milestone in pose estimation" — an approachable article explaining how OpenPose was introduced and its impact on pose estimation: https://www.ultralytics.com/blog/what-is-openpose-exploring-a-milestone-in-pose-estimation
### JSON format: Standard vs Legacy
- **OpenPose Studio:** reads/writes **standard OpenPose-style JSON** and also accepts older non-standard (legacy) JSON.
Practical notes:
- Pasting standard JSON into the OpenPose Studio node will render preview immediately.
---
## Gallery & Pose Management
### Overview
The **Gallery** tab provides visual browsing of all available poses with live preview thumbnails. It automatically discovers and organizes poses without manual configuration.
### View modes
The Gallery supports four display modes:
- **Large** — larger previews for quick visual selection
- **Medium** — balanced preview size and density
- **Small** — dense icon grid optimized for narrow and mobile layouts
- **Tiles** — compact grid with extra metadata (e.g. **canvas size**, **keypoint counts**, and other pose details)
### Features
- **Auto-discovery**: Scans `poses/` directory on startup
- **Nested organization**: Subdirectory names become group labels
- **Live preview**: Thumbnail rendering for each pose
- **Search/filter**: Find poses by name or group
- **One-click load**: Select a pose to load into editor
### Supported File Types
- **Single-pose JSON**: Individual OpenPose JSON files
- **Pose Collections**: Multi-pose JSON files (each pose shown separately)
- **Nested directories**: Poses in subdirectories automatically grouped
### Deterministic Behavior
Gallery ordering and discovery is fully deterministic:
- No random shuffling
- Consistent alphabetical sorting
- Root poses listed first, then grouped poses
- Immediate reload of all JSON poses upon opening the Editor window.
---
## Pose Merger
### Purpose
The **Pose Merger** tab consolidates multiple individual pose JSON files into organized pose collection files. This is useful for:
- Converting large pose libraries into single files
- Cleaning pose data (removing face/hand keypoints)
- Reorganizing and renaming poses
- Distributing pose packs efficiently
### Workflow
1. **Add Files**: Load individual or collection JSON files
2. **Preview**: Each pose shown with thumbnail
3. **Configure**: Optionally exclude face/hand components
4. **Export**: Save as combined collection or individual files
### Key Capabilities
| Feature | Use Case |
|---------|----------|
| **Load Multiple Files** | Bulk import from file system |
| **Component Filtering** | Remove unnecessary face/hand data |
| **Collection Expansion** | Extract poses from existing collections |
| **Batch Renaming** | Assign meaningful names during export |
| **Selective Export** | Choose which poses to include |
### Output Options
- **Combined Collection**: Single JSON with all poses
- **Individual Files**: One file per pose (for compatibility)
Both output formats are automatically picked up by Gallery and Pose Selector.
---
## Render
The **Render** module lets you customize how the OpenPose stickman is rendered when the workflow executes. It includes body, hands, and face styling controls such as line width, keypoint radius, and keypoint color for hands/face.
Render settings are saved locally in this browser's local storage, not in the workflow. Changing them affects subsequent workflow executions.
---
## Known Limitations
> [!NOTE]
> Nodes 2.0 is supported. If the preview canvas or editor button is missing, check browser cache, frontend loading, and installation logs.
### Current Limitations & Workarounds
1. **Face Editing**
- Face keypoints are preserved and rendered, but cannot currently be edited individually in the canvas.
2. **Resolution Consistency**
- Issue: Pose Merger doesn't auto-unify resolution across collection exports
- Status: Needs careful implementation to avoid clipping
- Workaround: Pre-scale poses to target resolution before importing
3. **Nodes 2.0 Compatibility**
- Status: Supported in current versions.
- Note: If the editor UI does not appear, the most likely causes are stale browser cache, failed frontend module loading, or an incomplete installation.
- Troubleshooting: Fully restart ComfyUI, hard-refresh the browser, and check the browser console plus ComfyUI startup log.
### Error Recovery
The plugin includes defensive error handling:
- Invalid JSON files skip silently in Gallery
- Rendering errors return blank images instead of crashing
- Missing metadata falls back to safe defaults
- Malformed keypoints are filtered during rendering
---
## Troubleshooting
### Common Issues & Solutions
**Poses not appearing in Gallery**
```
✓ Confirm files exist in poses/ directory
✓ Verify JSON is valid (use online JSON validator)
✓ Check file extension is .json (case-sensitive on Linux)
✓ Restart ComfyUI to trigger discovery
✓ Check browser console (F12) for error messages
```
**JSON import fails**
```
✓ Validate JSON structure (must have "pose_keypoints_2d" or equivalent)
✓ Ensure coordinates are valid numbers, not strings
✓ Confirm minimum 18 keypoints for body poses
✓ Check for malformed escape sequences in JSON
```
**Blank output image**
```
✓ Verify pose is selected and contains valid keypoints
✓ Check canvas dimensions (width/height) are reasonable (100-2048px)
✓ Click Apply to render after making changes
✓ Check for NaN or infinite values in coordinates
```
**Background reference not persisting**
```
✓ Enable third-party cookies/storage in browser
✓ Check browser localStorage settings
✓ Try incognito mode to isolate issue
✓ Clear browser cache and try again
```
**Node not appearing in ComfyUI**
```
✓ Verify clone location: ComfyUI/custom_nodes/comfyui-openpose-studio
✓ Check __init__.py exists and imports correctly
✓ Restart ComfyUI fully (not just reload page)
✓ Check ComfyUI console for import errors
```
---
## Contributing
For guidelines on contributing, pull requests guidelines, architectural details, and development information, see [CONTRIBUTING.md](./CONTRIBUTING.md). If using an AI agent to assist with development, ensure it reads [AGENTS.md](../AGENTS.md) before making any code changes.
---
## Funding & Support
### Why Your Support Matters
This plugin is developed and maintained independently, with regular use of **paid AI agents** to speed up debugging, testing, and quality-of-life improvements. If you find it useful, financial support helps keep development moving steadily.
Your contribution helps:
* Fund AI tooling for faster fixes and new features
* Cover ongoing maintenance and compatibility work across ComfyUI updates
* Prevent development slowdowns when usage limits are reached
> [!TIP]
> Not donating? A GitHub star ⭐ still helps a lot by improving visibility and helping more users
### 💙 Support This Project
Prefer scanning? Show QR codes
Ko-fi
|
PayPal
|
USDC (Arbitrum) ⚠️
|
Show USDC address
```text
0xe36a336fC6cc9Daae657b4A380dA492AB9601e73
```
> [!WARNING]
> Send USDC on Arbitrum One only. Transfers sent on any other network will not arrive and may be permanently lost.
---
## License
MIT License - see [LICENSE](../LICENSE) file for full text.
**Summary:**
- ✓ Free for commercial use
- ✓ Free for private use
- ✓ Modify and distribute
- ✓ Include license and copyright notice
---
## Additional Resources
### Related Projects
- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) - Core framework
- [comfyui_controlnet_aux](https://github.com/Kosinkadink/ComfyUI-Advanced-ControlNet) - ControlNet support
- [OpenPose](https://github.com/CMU-Perceptual-Computing-Lab/openpose) - Original pose detection
### Documentation
- [ComfyUI Custom Nodes Guide](https://github.com/comfyanonymous/ComfyUI/blob/main/docs/)
- [OpenPose Models & Keypoints](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/02_Output.md)
- [Canvas 2D API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) - Rendering engine
### Troubleshooting Guides
- [ComfyUI Installation Issues](https://github.com/comfyanonymous/ComfyUI/wiki/Installation)
- [Node Registration & Loading](https://github.com/comfyanonymous/ComfyUI/blob/main/docs/CONTRIBUTING.md)
- [Browser Developer Tools](https://developer.chrome.com/docs/devtools/)
---
**Maintained by:** andreszs
**Status:** Active Development
