5.1 KiB
Architecture & Contributing Guide
Table of Contents
Architecture & Data Flow
System Overview
UI Editor (JavaScript)
↓
Editor JSON (editor format)
↓
Node.render()
├→ render_pose_image() → IMAGE output
└→ convert_to_pose_keypoint() → POSE_KEYPOINT output
Data Transformation Pipeline
-
User Input → Editor JSON
- Visual keypoint positions (x, y in pixel space)
- Canvas dimensions (width, height)
- Multiple poses per JSON document
-
Image Rendering
- Converts keypoints to image canvas
- Draws OpenPose limb connections
- Applies color mapping per limb
- Outputs RGB image (0-1 float)
-
Keypoint Conversion
- Keeps coordinates in PIXEL space (same as the pose files)
- Adds confidence scores (1.0 for user-placed keypoints)
- Packages into ControlNet-compatible format
File Structure
comfyui-openpose-studio/
├── __init__.py # Plugin registration & API routes
├── nodes.py # Node class & rendering logic
├── pyproject.toml # Package metadata (PEP 621)
├── js/
│ ├── main.js # Main editor controller
│ ├── openpose-canvas2d.js # Native Canvas2D rendering engine
│ ├── comfy-theme-colors.js # UI styling
│ ├── overlays.js # Tab overlay system
│ └── overlays/
│ ├── pose-editor.js # Pose editing UI
│ ├── pose-merger.js # Pose collection builder
│ ├── gallery.js # Pose browser
│ ├── config.js # Settings panel
│ ├── guide.js # Help documentation
│ └── about.js # Version & credits
├── poses/ # Pose JSON files & collections
├── assets/ # Images & QR codes
└── README.md # Main documentation
Contributing Guide
Core Principles
Pull requests must be focused, minimal, and purpose-driven. Avoid large refactors, sweeping changes, or file structure reorganization unless explicitly discussed beforehand.
The current project structure and architecture are intentionally designed for long-term growth. PRs that arbitrarily restructure files, rename modules, or "clean up" code without strong justification will not be accepted.
Before Submitting
Contributors are expected to understand the project before submitting changes. Read the existing code and documentation instead of relying on assumptions.
If using an AI agent (Claude, ChatGPT, Codex, etc.) to assist with development, it is mandatory to explicitly instruct the agent to read and follow the rules defined in AGENTS.md before making any code changes.
What Will Be Rejected
Pull requests generated by AI that:
- Ignore AGENTS.md guidelines
- Apply broad or destructive refactors
- Modify unrelated areas of the codebase
- Rewrite working logic "for style"
...will be rejected without review.
What Will Be Accepted
Acceptable pull requests should:
- Address a single, well-defined issue or improvement
- Keep changes localized and easy to review
- Preserve existing architecture and design decisions
- Explain why the change is needed, not just what was changed
Final Note
The maintainers reserve the right to close PRs that do not follow these guidelines, even if the code appears to work. Quality, maintainability, and respect for existing architecture are paramount.
Have an Idea? Suggestions Welcome!
The author welcomes suggestions, comments, and ideas from the community! You don't need to submit code to contribute.
How to Share Your Ideas
- Open an Issue on GitHub with your suggestion, feature request, or comment
- Describe your use case — understanding how users are using the plugin helps shape its direction
- Share feedback on what works well and what could be improved
- Ask questions — if something is unclear or confusing, let us know!
Types of Contributions We'd Love to Hear About
- ✨ Feature ideas and enhancement suggestions
- 🐛 Bug reports and edge cases you've encountered
- 💭 Workflow improvements or better ways to use the editor
- 📚 Documentation improvements or clarifications
- 🤔 Questions about architecture or design decisions
- 🎯 Use cases and real-world applications you're building
The Issues section is the place for discussion and collaboration. Please don't hesitate to reach out—your input shapes the future of this project and helps make it more useful for everyone.