A professional-grade Ultralytics Studio extension designed for production workflows, featuring an intuitive interface, comprehensive pose management, and robust JSON handling. Fully backward compatible with the original Ultralytics Studio distributed via ComfyUI Manager.
- ✨ Features
- 📦 Installation
- 🎯 Usage
- 🔧 Nodes
- ⌨️ Editor Controls & Shortcuts
- 📋 Format Specifications
- 🖼️ Gallery & Pose Management
- 🔀 Pose Merger
- 🖼️ Background Reference
⚠️ Known Limitations- 🔍 Troubleshooting
- 🤝 Contributing
- 💙 Funding & Support
- 📄 License
✨ Core Capabilities
- Real-time OpenPose keypoint editing with visual feedback
- 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)
✨ Planned Features & Roadmap
Important
Many planned features depend on funding for AI tokens. For the full roadmap and upcoming work, please check TODO.md..
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-Ultralytics-Studio/issues
- ComfyUI (recent build)
- Python 3.10+
- Clone this repository into
ComfyUI/custom_nodes/. - Restart ComfyUI.
- Confirm nodes appear under
image > Ultralytics Studio.
- Add the Ultralytics Studio node to your workflow
- Click the node's preview canvas to open the editor UI
- Select a pose from the presets or gallery to insert into canvas
- Adjust keypoints by dragging them on the canvas
- Click Apply to render the pose. This will create the serialized JSON in the node.
- Connect the
imageoutput to subsequent image nodes - Connect the
kpsoutput to ControlNet/OpenPose compatible nodes
Category: image
- Input:
Pose JSON(STRING) — standard OpenPose-style JSON. - Options:
render body— include body in the rendered preview/output imagerender 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 dataKPS— 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.
| 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 |
- Click: Select keypoint
- Drag: Move keypoint to new position
- Scroll: Zoom in/out on canvas (TO-DO)
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.
This editor fully supports Ultralytics COCO-17 (body) editing.
It also supports OpenPose face and hands data in a pass-through manner: if your JSON includes face and/or hand keypoints, they are preserved (not removed) and the Python node can render them correctly. However, editing face and hand keypoints is not available yet (planned for upcoming updates).
COCO-17 uses 17 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 canvasc: confidence (commonly0..1;0can be used for "missing" points)
Keypoint order (index -> name):
| Index | Name |
|---|---|
| 0 | Nose |
| 1 | Left Eye |
| 2 | Right Eye |
| 3 | Left Ear |
| 4 | Right Ear |
| 5 | Left Shoulder |
| 6 | Right Shoulder |
| 7 | Left Elbow |
| 8 | Right Elbow |
| 9 | Left Wrist |
| 10 | Right Wrist |
| 11 | Left Hip |
| 12 | Right Hip |
| 13 | Left Knee |
| 14 | Right Knee |
| 15 | Left Ankle |
| 16 | Right Ankle |
Note
COCO refers to the Common Objects in Context keypoint convention/dataset naming widely used in pose estimation. "COCO-17" here means the Ultralytics body layout with 17 keypoints.
A typical single-pose OpenPose-style JSON includes canvas dimensions and one people entry with pose_keypoints_2d:
{
"canvas_width": 512,
"canvas_height": 512,
"people": [
{
"pose_keypoints_2d": [0, 0, 0, 0, 0, 0 /* ... 17 * 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.
- 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
The Gallery tab provides visual browsing of all available poses with live preview thumbnails. It automatically discovers and organizes poses without manual configuration.
The Gallery supports three display modes:
- Large — larger previews for quick visual selection
- Medium — balanced preview size and density
- Tiles — compact grid with extra metadata (e.g. canvas size, keypoint counts, and other pose details)
- 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
- Single-pose JSON: Individual OpenPose JSON files
- Pose Collections: Multi-pose JSON files (each pose shown separately)
- Nested directories: Poses in subdirectories automatically grouped
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.
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
- Add Files: Load individual or collection JSON files
- Preview: Each pose shown with thumbnail
- Configure: Optionally exclude face/hand components
- Export: Save as combined collection or individual files
| 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 |
- 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.
Warning
Nodes 2.0 is currently not supported. Please disable Nodes 2.0 for now.
- Hand & Face Editing
- Issue: Editor currently limited to body keypoints (0-17)
- Status: Planned for future release
- Workaround: Use Pose Merger to manually edit hand/face JSON before importing
- 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
- Nodes 2.0 Compatibility
- Issue: The node does not behave correctly when ComfyUI "Nodes 2.0" is enabled.
- Status: Planned fix, but it is a large and time-consuming refactor.
- Note: This project is developed using paid AI agents. Once funding is available to purchase additional AI tokens, I intend to prioritize Nodes 2.0 support.
- Workaround: Disable Nodes 2.0 for now.
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
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 17 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-Ultralytics-Studio
✓ Check __init__.py exists and imports correctly
✓ Restart ComfyUI fully (not just reload page)
✓ Check ComfyUI console for import errors
For guidelines on contributing, pull requests guidelines, architectural details, and development information, see CONTRIBUTING.md. If using an AI agent to assist with development, ensure it reads AGENTS.md before making any code changes.
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
Prefer scanning? Show QR codes
Ko-fi
|
PayPal
|
USDC (Arbitrum) 
|
Show USDC address
0xe36a336fC6cc9Daae657b4A380dA492AB9601e73
[!WARNING] Send USDC on Arbitrum One only. Transfers sent on any other network will not arrive and may be permanently lost.
MIT License - see LICENSE file for full text.
Summary:
- ✓ Free for commercial use
- ✓ Free for private use
- ✓ Modify and distribute
- ✓ Include license and copyright notice
- ComfyUI - Core framework
- comfyui_controlnet_aux - ControlNet support
- OpenPose - Original pose detection
- ComfyUI Custom Nodes Guide
- OpenPose Models & Keypoints
- Canvas 2D API - Rendering engine
Maintained by: andreszs
Status: Active Development