nodes/aTanguay-ComfyUI_Detonate
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Andy Tanguay
2025-11-22 00:35:17 -05:00
parent 879bcd83ce
commit dcf80625e4
4 changed files with 1781 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+321
View File
@@ -0,0 +1,321 @@
# Guide for Claude - ComfyUI_Detonate Project
This document provides context for future Claude sessions working on this project.
---
## Project Summary
**ComfyUI_Detonate** is a custom node package for ComfyUI that brings professional compositing tools from Nuke and DaVinci Fusion to the ComfyUI platform. The goal is to provide VFX compositors with familiar, industry-standard nodes for traditional compositing workflows alongside AI image generation.
---
## Key Project Documents
### Primary References
1. **[PLANNING.md](PLANNING.md)** - Complete project vision, architecture, and roadmap
2. **[TASKS.md](TASKS.md)** - Detailed task checklist for implementation
3. **[NODE_PRIORITIES.md](NODE_PRIORITIES.md)** - 43 nodes prioritized by importance
### Quick Reference
- **Language:** Python 3.8+
- **Framework:** ComfyUI Custom Node API
- **Core Libraries:** PyTorch, NumPy, Pillow
- **Target:** Professional compositors and VFX artists
---
## Project Status
**Current Phase:** Phase 1 - Planning Complete ✓
**Completed:**
- Project vision and goals defined
- Architecture designed
- Technology stack selected
- 43 nodes researched and prioritized
- Development roadmap created
**Next Steps:**
1. Create directory structure
2. Set up `pyproject.toml` and `requirements.txt`
3. Implement utility modules (`tensor_utils.py`, `image_processing.py`, `color_math.py`)
4. Create `__init__.py` with node registration system
5. Begin implementing Priority 1 nodes (Merge, Transform, Blur, Grade, Premult/Unpremult)
---
## Technical Architecture
### Directory Structure
```
ComfyUI_Detonate/
├── __init__.py # Node registration
├── nodes/ # Node implementations
│ ├── compositing/ # Merge operations
│ ├── color/ # Color correction
│ ├── keying/ # Keying tools
│ ├── transform/ # Transforms
│ ├── filter/ # Blur, sharpen, etc.
│ ├── matte/ # Matte operations
│ ├── channel/ # Channel ops
│ ├── time/ # Time operations
│ └── 3d/ # 3D compositing
├── utils/ # Shared utilities
│ ├── tensor_utils.py
│ ├── image_processing.py
│ └── color_math.py
├── tests/ # Unit tests
├── examples/ # Example workflows
├── web/js/ # Frontend extensions
├── pyproject.toml # Package metadata
├── requirements.txt # Dependencies
└── README.md # Documentation
```
### ComfyUI Node Structure
Every node must implement:
```python
class NodeName:
CATEGORY = "detonate/category"
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"image": ("IMAGE",),
}
}
RETURN_TYPES = ("IMAGE",)
FUNCTION = "process"
def process(self, image):
# Processing logic
return (image,)
```
### Image Tensor Format
- **Shape:** `[B, H, W, C]` (Batch, Height, Width, Channels)
- **Type:** `torch.Tensor` (Float32)
- **Range:** 0.0 - 1.0
- **Channels:** C=3 (RGB) or C=4 (RGBA)
---
## Development Guidelines
### Code Standards
- Use **black** for formatting
- Use **flake8** for linting
- Add docstrings to all public functions
- Include type hints where helpful
- Keep functions focused and modular
### Node Implementation Pattern
1. Create node class in appropriate `nodes/` subdirectory
2. Implement required class attributes (CATEGORY, INPUT_TYPES, RETURN_TYPES, FUNCTION)
3. Implement processing method
4. Handle batch processing correctly
5. Add validation and error handling
6. Register node in `__init__.py`
7. Write unit tests
8. Create example workflow
### Testing
- Write unit tests for all nodes
- Test with various image sizes (1080p, 4K)
- Test batch processing
- Test edge cases (1x1 images, empty batches)
- Verify alpha channel handling
### Performance
- Use PyTorch operations (vectorized)
- Avoid Python loops over pixels
- Leverage GPU when available
- Target: <100ms for 1080p, <500ms for 4K
---
## Common Operations Reference
### Alpha Handling
```python
# Premultiply
result_rgb = rgb * alpha
# Unpremultiply (handle division by zero)
result_rgb = rgb / (alpha + 1e-7)
```
### Blend Modes
```python
# Over compositing
result = fg + bg * (1 - fg_alpha)
# Screen
result = 1 - (1 - fg) * (1 - bg)
# Multiply
result = fg * bg
```
### Color Space Conversion
```python
# RGB to HSV
hsv = torch.tensor(cv2.cvtColor(rgb.numpy(), cv2.COLOR_RGB2HSV))
# HSV to RGB
rgb = torch.tensor(cv2.cvtColor(hsv.numpy(), cv2.COLOR_HSV2RGB))
```
---
## Nuke/Fusion Equivalents
Quick reference for compositor familiarity:
| Function | Nuke | Fusion | Detonate |
|----------|------|--------|----------|
| Compositing | Merge | Merge | Merge |
| Color Grading | Grade | ColorCorrector | Grade |
| Blur | Blur | Blur | Blur |
| Keying | Keylight | DeltaKeyer | ChromaKeyer |
| Transform | Transform | Transform | Transform |
| Matte Ops | FilterErode | MatteControl | MatteControl |
| Channels | Shuffle | ChannelBooleans | Shuffle |
| Premult | Premult | (in Merge) | Premult |
---
## Priority 1 Nodes (Implement First)
These 8 nodes form the core toolkit:
1. **Merge** - Compositing with blend modes (Over, Under, Plus, Screen, Multiply)
2. **Transform** - Translate, rotate, scale, skew
3. **Blur** - Gaussian blur with X/Y controls
4. **Grade** - Lift/Gamma/Gain color correction
5. **Premultiply** - Multiply RGB by alpha
6. **Unpremultiply** - Divide RGB by alpha
7. **Shuffle** - Channel reordering
8. **ColorCorrect** - Quick saturation/contrast/gamma adjustments
---
## Dependencies
### Required
```
torch>=2.0.0
numpy>=1.20.0
pillow>=9.0.0
```
### Optional (for advanced features)
```
opencv-python>=4.5.0
scikit-image>=0.19.0
scipy>=1.7.0
```
---
## Workflow for New Sessions
1. **Check TASKS.md** - See what's completed and what's next
2. **Review relevant nodes in NODE_PRIORITIES.md** - Understand priority and complexity
3. **Reference PLANNING.md** - For architecture and design decisions
4. **Implement incrementally** - One node at a time, with tests
5. **Update TASKS.md** - Mark completed items
---
## Common Pitfalls to Avoid
### Image Handling
- ❌ Don't assume C=3 (check for alpha channel)
- ❌ Don't modify input tensors in-place
- ❌ Don't forget batch dimension
- ✅ Always return tuple matching RETURN_TYPES
- ✅ Handle edge cases (empty images, 1x1 pixels)
### Performance
- ❌ Don't use Python loops over pixels
- ❌ Don't load entire image to CPU unnecessarily
- ✅ Use PyTorch operations (vectorized)
- ✅ Keep tensors on GPU when possible
### Alpha Compositing
- ❌ Don't assume images are premultiplied
- ❌ Don't ignore alpha channel in blend modes
- ✅ Document premult requirements
- ✅ Handle straight vs premultiplied correctly
### Node Registration
- ❌ Don't forget to add to NODE_CLASS_MAPPINGS
- ❌ Don't use spaces in CATEGORY names
- ✅ Use consistent naming conventions
- ✅ Provide meaningful display names
---
## Questions to Ask the User
When implementing nodes:
1. "Should this node expect premultiplied or straight alpha?"
2. "What edge behavior do you want? (black/clamp/repeat)"
3. "Do you want GPU acceleration for this operation?"
4. "Should this support batch processing?"
5. "Any specific Nuke/Fusion behavior to match?"
---
## Useful Resources
- **ComfyUI Docs:** https://docs.comfy.org/
- **PyTorch Docs:** https://pytorch.org/docs/stable/
- **Nuke Docs:** https://learn.foundry.com/nuke/
- **Fusion Docs:** https://documents.blackmagicdesign.com/UserManuals/Fusion_Manual.pdf
- **Porter-Duff Compositing:** https://en.wikipedia.org/wiki/Alpha_compositing
---
## Development Phases Timeline
- **Phase 1:** Foundation (2 weeks) - Directory structure, utils, registration
- **Phase 2:** Core Nodes (3 weeks) - Merge, Transform, Blur, Grade, etc.
- **Phase 3:** Keying (2 weeks) - ChromaKeyer, LumaKeyer, MatteControl
- **Phase 4:** Advanced (2 weeks) - Color curves, filters
- **Phase 5:** Transforms (2 weeks) - CornerPin, GridWarp, Displace
- **Phase 6:** Time Ops (1 week) - FrameHold, TimeOffset
- **Phase 7:** Testing (2 weeks) - Comprehensive tests, docs
- **Phase 8:** Release (1 week) - Publishing, community
**Total estimated time to v1.0: ~16 weeks**
---
## Success Criteria
**Phase 1 Complete:** Package loads in ComfyUI without errors
**Phase 2 Complete:** Can composite basic greenscreen shot with color correction
**Phase 3 Complete:** Professional keying workflow functional
**v1.0 Release:** 30+ nodes implemented, tested, and documented
---
## Notes for Claude
- Always check [TASKS.md](TASKS.md) and update checkboxes as you complete work
- Reference [NODE_PRIORITIES.md](NODE_PRIORITIES.md) for node complexity estimates
- Follow the architecture defined in [PLANNING.md](PLANNING.md)
- Write clean, modular, well-documented code
- Test thoroughly before marking tasks complete
- Ask for clarification when Nuke/Fusion behavior is ambiguous
- Keep the user informed of progress and any blockers
---
**Last Updated:** 2025-01-21
**Current Phase:** Planning Complete, Ready for Phase 1 Implementation
NODE_PRIORITIES.md
+335
View File
@@ -0,0 +1,335 @@
# ComfyUI_Detonate - Node Implementation Priority List
This document outlines the priority order for implementing nodes based on professional compositor workflows and daily usage patterns.
---
## Priority Tier 1: Essential Daily Tools (Must Have)
These nodes are used in virtually every compositing session and form the foundation of all workflows.
### 1. Merge (Compositing)
**Nuke:** Merge | **Fusion:** Merge
- **Operations:** Over, Under, Plus, Screen, Multiply, Stencil, Mask, Atop
- **Importance:** Core of all compositing work
- **Complexity:** Medium (alpha math, multiple blend modes)
### 2. Transform
**Nuke:** Transform | **Fusion:** Transform
- **Features:** Translate, Rotate, Scale, Skew, Motion Blur
- **Importance:** Every shot needs positioning/scaling
- **Complexity:** Medium (2D transforms, motion blur optional first pass)
### 3. Blur
**Nuke:** Blur | **Fusion:** Blur
- **Features:** Gaussian blur with X/Y separation, quality controls
- **Importance:** Used constantly for softening, glows, depth
- **Complexity:** Low (standard Gaussian implementation)
### 4. Grade
**Nuke:** Grade | **Fusion:** ColorCorrector
- **Features:** Lift/Gamma/Gain for Master + RGB channels
- **Importance:** Primary color correction tool
- **Complexity:** Medium (proper color math with shadows/mids/highlights)
### 5. Premultiply / Unpremultiply
**Nuke:** Premult/Unpremult | **Fusion:** (built into Merge)
- **Features:** Multiply/divide RGB by alpha
- **Importance:** Critical for proper alpha handling
- **Complexity:** Low (simple math operation)
### 6. Shuffle
**Nuke:** Shuffle/Shuffle2 | **Fusion:** ChannelBooleans
- **Features:** Reorder channels, copy between layers
- **Importance:** Constant channel manipulation needs
- **Complexity:** Medium (channel routing logic)
### 7. ColorCorrect
**Nuke:** ColorCorrect | **Fusion:** ColorCorrector (basic mode)
- **Features:** Saturation, Contrast, Gamma, Gain, Offset
- **Importance:** Quick color adjustments
- **Complexity:** Low (basic color math)
### 8. Erode / Dilate
**Nuke:** Erode/Dilate | **Fusion:** ErodeDilate
- **Features:** Matte expansion/contraction
- **Importance:** Essential for matte cleanup
- **Complexity:** Low (morphological operations)
---
## Priority Tier 2: High-Frequency Professional Tools
Used in most professional compositing shots, especially for keying and effects work.
### 9. ChromaKeyer (Basic)
**Nuke:** Keyer | **Fusion:** ChromaKeyer
- **Features:** Green/blue screen keying with spill suppression
- **Importance:** Greenscreen work is extremely common
- **Complexity:** High (color space keying, spill removal)
### 10. LumaKeyer
**Nuke:** Keyer (luma mode) | **Fusion:** LumaKeyer
- **Features:** Luminance-based key generation
- **Importance:** Quick matte creation from brightness
- **Complexity:** Low (threshold-based)
### 11. MatteControl
**Nuke:** (FilterErode + Blur combination) | **Fusion:** MatteControl
- **Features:** Contract, Expand, Blur, Gamma for mattes
- **Importance:** All-in-one matte refinement
- **Complexity:** Medium (combines multiple operations)
### 12. Clamp
**Nuke:** Clamp | **Fusion:** (in ColorCorrector)
- **Features:** Constrain values to min/max range
- **Importance:** Prevent out-of-range values
- **Complexity:** Low (simple clamping)
### 13. Saturation
**Nuke:** Saturation | **Fusion:** ColorCorrector (saturation)
- **Features:** Direct saturation control
- **Importance:** Frequent color adjustment
- **Complexity:** Low (HSV conversion and adjustment)
### 14. Invert
**Nuke:** Invert | **Fusion:** Channel Booleans (invert)
- **Features:** Invert color/channel values
- **Importance:** Quick matte/color inversion
- **Complexity:** Low (1 - value)
### 15. Copy / ChannelCopy
**Nuke:** Copy/ShuffleCopy | **Fusion:** ChannelBooleans
- **Features:** Copy channels between streams
- **Importance:** Channel management in complex comps
- **Complexity:** Medium (multi-stream channel operations)
---
## Priority Tier 3: Regular Use Tools
Important tools used frequently but not in every shot.
### 16. CornerPin
**Nuke:** CornerPin2D | **Fusion:** CornerPositioner
- **Features:** 4-point perspective mapping
- **Importance:** Screen replacements, tracking integration
- **Complexity:** High (perspective transform math)
### 17. Defocus
**Nuke:** Defocus/ZDefocus | **Fusion:** Defocus
- **Features:** Lens-style defocus blur
- **Importance:** Realistic depth of field effects
- **Complexity:** High (bokeh simulation)
### 18. DirectionalBlur
**Nuke:** DirectionalBlur | **Fusion:** DirectionalBlur
- **Features:** Motion-style blur in specified direction
- **Importance:** Motion effects, speed lines
- **Complexity:** Low (directional sampling)
### 19. Sharpen
**Nuke:** Sharpen | **Fusion:** Sharpen
- **Features:** Image sharpening
- **Importance:** Detail enhancement
- **Complexity:** Low (unsharp mask variant)
### 20. HueCorrect / ColorCurves
**Nuke:** HueCorrect | **Fusion:** ColorCurves
- **Features:** Hue-based saturation/color adjustment
- **Importance:** Selective color correction
- **Complexity:** High (hue-based curves)
### 21. Glow
**Nuke:** Glow | **Fusion:** Glow
- **Features:** Highlight blooming effects
- **Importance:** Common VFX element
- **Complexity:** Medium (threshold + blur + composite)
### 22. DifferenceKeyer
**Nuke:** Difference | **Fusion:** DeltaKeyer (difference mode)
- **Features:** Difference matte generation
- **Importance:** Clean plate differencing
- **Complexity:** Low (image subtraction)
### 23. Constant / Background
**Nuke:** Constant | **Fusion:** Background
- **Features:** Solid color/gradient generation
- **Importance:** Creating mattes, backgrounds
- **Complexity:** Low (color fill)
### 24. EdgeDetect
**Nuke:** EdgeDetect | **Fusion:** Filter (Sobel/Laplacian)
- **Features:** Edge extraction
- **Importance:** Matte creation, effects
- **Complexity:** Low (edge detection filters)
---
## Priority Tier 4: Specialized Tools
Used in specific workflows or advanced compositing tasks.
### 25. FrameHold
**Nuke:** FrameHold | **Fusion:** TimeStretcher (hold)
- **Features:** Hold single frame
- **Importance:** Freeze frames in sequences
- **Complexity:** Low (frame caching)
### 26. TimeOffset
**Nuke:** TimeClip | **Fusion:** TimeStretcher
- **Features:** Time offset/loop
- **Importance:** Sequence timing adjustments
- **Complexity:** Low (frame index offset)
### 27. VectorBlur
**Nuke:** VectorBlur | **Fusion:** VectorMotionBlur
- **Features:** Motion blur from vector/motion channels
- **Importance:** Realistic motion blur from 3D renders
- **Complexity:** High (vector-based sampling)
### 28. GridWarp
**Nuke:** GridWarp | **Fusion:** GridWarp
- **Features:** Manual grid-based warping
- **Importance:** Custom distortions, warping effects
- **Complexity:** High (mesh deformation)
### 29. LensDistortion
**Nuke:** LensDistortion | **Fusion:** LensDistort
- **Features:** Add/remove lens distortion
- **Importance:** Camera matching, undistortion
- **Complexity:** High (lens model math)
### 30. IDistort / Displace
**Nuke:** IDistort | **Fusion:** Displace
- **Features:** Displace pixels using displacement map
- **Importance:** Refraction, heat distortion effects
- **Complexity:** High (displacement mapping)
### 31. Median
**Nuke:** Median | **Fusion:** Median (via Filter)
- **Features:** Noise reduction filter
- **Importance:** Despeckle, noise reduction
- **Complexity:** Low (median filtering)
### 32. Remove Channels
**Nuke:** Remove | **Fusion:** ChannelBooleans (remove)
- **Features:** Remove unwanted channels
- **Importance:** Clean up channel bloat
- **Complexity:** Low (channel removal)
### 33. Ramp / Gradient
**Nuke:** Ramp/Radial | **Fusion:** Background (gradient)
- **Features:** Linear and radial gradients
- **Importance:** Gradient generation for effects
- **Complexity:** Low (gradient math)
### 34. Noise
**Nuke:** Noise | **Fusion:** FastNoise
- **Features:** Procedural noise generation
- **Importance:** Grain, texture generation
- **Complexity:** Low (Perlin/simplex noise)
### 35. Text
**Nuke:** Text/Text2 | **Fusion:** Text+
- **Features:** Text generation
- **Importance:** Slates, labels, graphics
- **Complexity:** Medium (font rendering)
---
## Priority Tier 5: Advanced/Specialized (Future Phases)
Professional tools for specific advanced workflows.
### 36. Stabilize
**Nuke:** Stabilize2D | **Fusion:** Tracker (stabilize)
- **Requires:** Tracking implementation first
- **Complexity:** High
### 37. Tracker (2D Point)
**Nuke:** Tracker | **Fusion:** Tracker
- **Complexity:** Very High (tracking algorithm)
### 38. PlanarTracker
**Nuke:** PlanarTracker | **Fusion:** PlanarTracker
- **Complexity:** Very High (planar tracking)
### 39. SplineWarp
**Nuke:** SplineWarp | **Fusion:** (GridWarp variant)
- **Complexity:** High (spline-based deformation)
### 40. Kronos / OpticalFlow
**Nuke:** Kronos | **Fusion:** OpticalFlow
- **Features:** Frame interpolation via optical flow
- **Complexity:** Very High (optical flow algorithm)
### 41. 3D Nodes (Camera, Lights, Scene, Card)
**Nuke:** Camera2, Light, Scene, Card | **Fusion:** Camera3D, Lights, Merge3D, ImagePlane3D
- **Complexity:** High (3D rendering integration)
### 42. ScanlineRender / Renderer3D
**Nuke:** ScanlineRender | **Fusion:** Renderer3D
- **Complexity:** Very High (3D rendering)
### 43. Advanced Keyers (Primatte, IBK)
**Nuke:** Primatte, IBK, Keylight | **Fusion:** Primatte, UltraKeyer
- **Complexity:** Very High (professional keying algorithms)
---
## Implementation Strategy
### Phase 1 Focus: Tier 1 (Nodes 1-8)
Delivers a functional compositing toolkit suitable for basic professional work.
**Target:** 2-3 weeks
### Phase 2 Focus: Tier 2 (Nodes 9-15)
Adds professional keying and color tools.
**Target:** 2-3 weeks
### Phase 3 Focus: Tier 3 (Nodes 16-24)
Expands to advanced effects and transforms.
**Target:** 3-4 weeks
### Phase 4 Focus: Tier 4 (Nodes 25-35)
Covers specialized workflows.
**Target:** 3-4 weeks
### Phase 5+: Tier 5 (Nodes 36-43)
Advanced professional features (long-term roadmap).
**Target:** Future releases
---
## Node Complexity Reference
**Low Complexity:** 1-3 days implementation
- Direct mathematical operations
- Simple filters
- Basic channel operations
**Medium Complexity:** 3-7 days implementation
- Multiple parameters and modes
- Compound operations
- Color space conversions
**High Complexity:** 1-2 weeks implementation
- Complex algorithms
- Multiple interdependent features
- Optimization required
**Very High Complexity:** 2+ weeks implementation
- Advanced algorithms (tracking, optical flow)
- 3D rendering integration
- Patent/proprietary algorithm alternatives needed
---
## Success Criteria by Tier
**Tier 1 Complete:** Can composite basic greenscreen shot with color correction
**Tier 2 Complete:** Professional-quality keying and matte workflows
**Tier 3 Complete:** Advanced effects and transforms available
**Tier 4 Complete:** Specialized workflows covered
**Tier 5 Complete:** Feature parity with commercial compositors
PLANNING.md
+641
View File
@@ -0,0 +1,641 @@
# ComfyUI_Detonate - Planning Document
## Vision
### Project Overview
ComfyUI_Detonate is a comprehensive custom node package for ComfyUI that brings traditional compositing workflows from industry-standard software (Nuke and DaVinci Fusion) to the ComfyUI platform. The project aims to bridge the gap between traditional VFX compositing and modern AI-powered image generation workflows by implementing familiar node-based compositing tools within ComfyUI's ecosystem.
**Core Goals:**
- Provide professional compositors with familiar tools in ComfyUI
- Enable traditional compositing techniques alongside AI workflows
- Maintain naming conventions and workflows from Nuke/Fusion where possible
- Create a comprehensive, production-ready compositing toolkit
### Target Users
**Primary Audience:**
- Professional compositors transitioning from Nuke or DaVinci Fusion to ComfyUI
- VFX artists seeking to combine traditional compositing with AI generation
- Motion designers and video editors familiar with node-based workflows
- Technical directors building hybrid AI/traditional pipelines
**User Needs:**
- Familiar node names and behaviors from traditional compositing software
- Professional-grade color correction, keying, and masking tools
- Robust transform, tracking, and warping capabilities
- Industry-standard merge/blend operations
- Seamless integration with existing ComfyUI workflows
### Key Features
**Core Compositing Nodes:**
- Advanced merge operations (Over, Under, Plus, Screen, Multiply, Stencil, etc.)
- Professional color correction tools (Grade, ColorCorrect, Hue controls)
- Industry-standard keying nodes (Primatte, Keylight-style, Delta keying)
- Transform and geometric manipulation (Transform, CornerPin, Stabilize)
- Comprehensive filter operations (Blur, Defocus, Sharpen, Directional blur)
**Matte & Masking:**
- Edge operations (Erode/Dilate, MatteControl)
- Rotoscoping and shape tools
- Advanced matte refinement
**Channel Operations:**
- Channel shuffle and manipulation
- Premultiply/Unpremultiply operations
- Channel copy and removal
**Time & Tracking:**
- 2D point tracking
- Frame hold and time manipulation
- Motion blur and vector operations
**3D Compositing:**
- 3D scene integration
- Camera and light support
- Basic 3D geometry handling
### Success Metrics
- **Adoption:** Number of installations via ComfyUI Manager
- **Completeness:** Coverage of top 50 most-used Nuke/Fusion nodes
- **Usability:** Positive feedback from professional compositors
- **Performance:** Nodes execute efficiently without blocking ComfyUI workflows
- **Documentation:** Comprehensive examples and tutorials for each node category
- **Community:** Active user base contributing feedback and use cases
---
## Architecture
### High-Level Architecture
ComfyUI_Detonate follows ComfyUI's standard custom node architecture pattern:
```
ComfyUI/
└── custom_nodes/
└── ComfyUI_Detonate/
├── __init__.py # Node registration
├── nodes/ # Node implementations
│ ├── compositing/ # Merge operations
│ ├── color/ # Color correction nodes
│ ├── keying/ # Keying operations
│ ├── transform/ # Transform & geometry
│ ├── filter/ # Blur, sharpen, etc.
│ ├── matte/ # Matte operations
│ ├── channel/ # Channel manipulation
│ ├── time/ # Time operations
│ └── 3d/ # 3D compositing
├── utils/ # Shared utilities
│ ├── image_processing.py # Common image ops
│ ├── color_math.py # Color space utilities
│ └── tensor_utils.py # PyTorch helpers
├── web/ # Frontend extensions
│ └── js/
│ └── detonate.js # Custom UI behaviors
├── tests/ # Unit tests
├── examples/ # Example workflows
├── pyproject.toml # Package metadata
├── requirements.txt # Dependencies
└── README.md # Documentation
```
### Component Structure
**Node Categories:**
1. **Compositing** (`nodes/compositing/`)
- Merge nodes with blend modes
- Alpha operations
- Layer blending
2. **Color** (`nodes/color/`)
- Grade node (lift/gamma/gain)
- ColorCorrect (basic adjustments)
- Saturation, Hue, Clamp
- Color space conversions
3. **Keying** (`nodes/keying/`)
- Chroma keyers (green/blue screen)
- Luma keying
- Difference keying
- Key refinement tools
4. **Transform** (`nodes/transform/`)
- 2D transforms (translate, rotate, scale)
- Corner pinning
- Stabilization
- Lens distortion
5. **Filter** (`nodes/filter/`)
- Blur variants (Gaussian, defocus, directional)
- Sharpen and unsharp mask
- Edge detection
- Median filtering
6. **Matte** (`nodes/matte/`)
- Erode/Dilate operations
- Matte control (contract, expand, blur, gamma)
- Edge operations
7. **Channel** (`nodes/channel/`)
- Shuffle operations
- Channel copy/merge
- Premultiply/Unpremultiply
- Channel removal
8. **Time** (`nodes/time/`)
- Frame hold
- Time offset
- Speed changes
- Optical flow (if feasible)
9. **3D** (`nodes/3d/`)
- Basic 3D scene support
- Camera integration
- Card/plane geometry
**Utility Layer:**
- Shared image processing functions
- Color mathematics and conversions
- Tensor manipulation helpers
- Common validation routines
### Data Flow
**Standard Node Processing Pattern:**
```
Input (IMAGE tensor [B,H,W,C])
↓
Validation & Type Checking
↓
Premultiply (if needed)
↓
Processing Logic
↓
Unpremultiply (if needed)
↓
Output (IMAGE tensor [B,H,W,C])
```
**ComfyUI Integration Flow:**
```
User creates workflow in ComfyUI UI
↓
Detonate nodes process IMAGE tensors
↓
Nodes can connect to/from native ComfyUI nodes
↓
Output to Save Image or other nodes
```
**Data Types:**
- Primary: `IMAGE` (torch.Tensor [B,H,W,C] with C=3 RGB or C=4 RGBA)
- Secondary: `MASK` (torch.Tensor [H,W] or [B,C,H,W])
- Auxiliary: `FLOAT`, `INT`, `STRING` for parameters
### Integration Points
**ComfyUI Core:**
- Uses standard ComfyUI IMAGE tensor format
- Follows ComfyUI node registration pattern
- Compatible with ComfyUI's execution engine
- Integrates with ComfyUI Manager for installation
**Native ComfyUI Nodes:**
- Receives output from LoadImage, VAEDecode, etc.
- Outputs to SaveImage, VAEEncode, etc.
- Works alongside existing custom node packages
**External Libraries:**
- PyTorch for tensor operations
- NumPy for mathematical operations
- OpenCV for advanced image processing (optional)
- Pillow for image I/O utilities
**Frontend:**
- JavaScript extensions for enhanced UI
- Custom widgets for complex parameters
- Visual feedback for processing state
---
## Technology Stack
### Backend (Primary Development)
- **Language:** Python 3.8+
- **Core Framework:** ComfyUI Custom Node API
- **Tensor Operations:** PyTorch 2.0+
- **Numerical Computing:** NumPy 1.20+
- **Image Processing:**
- Pillow 9.0+ (basic I/O)
- OpenCV (optional, for advanced operations)
- scikit-image (optional, for specific filters)
### Frontend (Optional Extensions)
- **Language:** JavaScript (ES6+)
- **Framework:** ComfyUI's built-in extension system
- **UI Integration:** ComfyUI's LiteGraph-based node editor
- **APIs Used:**
- `app.js` - Core application API
- `api.js` - Backend communication
- Custom widget creation
### ComfyUI Integration
- **Node Registration:** `NODE_CLASS_MAPPINGS` and `NODE_DISPLAY_NAME_MAPPINGS`
- **Data Types:**
- IMAGE (torch.Tensor [B,H,W,C])
- MASK (torch.Tensor)
- FLOAT, INT, STRING, BOOLEAN
- **Execution:** ComfyUI's graph execution engine
- **Installation:** ComfyUI Manager compatible
### Core Libraries & Dependencies
**Required:**
```
torch>=2.0.0
numpy>=1.20.0
pillow>=9.0.0
```
**Optional (for advanced features):**
```
opencv-python>=4.5.0 # Advanced image processing
scikit-image>=0.19.0 # Scientific image processing
scipy>=1.7.0 # Scientific computing
colour-science>=0.4.0 # Color space conversions
```
### Development & Testing
- **Version Control:** Git
- **Package Management:** pip, pyproject.toml
- **Testing Framework:** pytest
- **Code Quality:**
- black (formatting)
- flake8 (linting)
- mypy (type checking - optional)
### Image Processing Pipeline
- **Color Spaces:** RGB, RGBA, HSV, LAB support
- **Bit Depth:** Float32 (0.0-1.0 range, matching ComfyUI standard)
- **Alpha Handling:** Premultiplied and straight alpha support
- **Batch Processing:** Full batch dimension support for efficiency
---
## Required Tools & Dependencies
### Development Environment
- [ ] **Python 3.8+** - Core development language
- [ ] **Git** - Version control
- [ ] **Code Editor** - VS Code recommended with Python extension
- [ ] **ComfyUI CLI** - `pip install comfy-cli` for scaffolding
### ComfyUI Setup
- [ ] **ComfyUI** - Latest stable version from [comfyanonymous/ComfyUI](https://github.com/comfyanonymous/ComfyUI)
- [ ] **ComfyUI Manager** (optional) - For easy installation/updates
- [ ] **Test Images** - Sample images for node testing
- [ ] **Python Environment** - Virtual environment (venv/conda) recommended
### Python Dependencies (Development)
```bash
# Core dependencies
pip install torch>=2.0.0
pip install numpy>=1.20.0
pip install pillow>=9.0.0
# Development tools
pip install pytest # Testing
pip install black # Code formatting
pip install flake8 # Linting
pip install mypy # Type checking (optional)
# Optional for advanced features
pip install opencv-python # Advanced image ops
pip install scikit-image # Scientific image processing
pip install scipy # Math operations
```
### Testing Tools
- [ ] **pytest** - Unit testing framework
- [ ] **pytest-cov** - Code coverage reporting
- [ ] **Test workflows** - ComfyUI workflow JSON files for integration testing
- [ ] **Sample images** - Test assets (green screen footage, mattes, etc.)
### Development Workflow Tools
- [ ] **comfy node scaffold** - CLI tool for generating node boilerplate
- [ ] **Hot reload** - ComfyUI restart required for code changes
- [ ] **Browser DevTools** - For frontend debugging (if adding JS extensions)
### Documentation Tools
- [ ] **Markdown editor** - For documentation
- [ ] **Workflow screenshots** - For example documentation
- [ ] **Docstrings** - In-code documentation following Python standards
### Distribution & Publishing
- [ ] **GitHub repository** - For version control and distribution
- [ ] **pyproject.toml** - Modern Python packaging metadata
- [ ] **ComfyUI Manager submission** - For easy user installation
- [ ] **ComfyUI Registry** - Optional registration at registry.comfy.org
### Reference Materials
- [ ] **Nuke documentation** - For node behavior reference
- [ ] **Fusion documentation** - For node behavior reference
- [ ] **ComfyUI docs** - https://docs.comfy.org/
- [ ] **Example custom nodes** - Study existing implementations
---
## Development Phases
### Phase 1: Foundation & Infrastructure (Week 1-2)
**Goal:** Set up project structure and core utilities
- [ ] Initialize repository structure with proper directories
- [ ] Create `pyproject.toml` and `requirements.txt`
- [ ] Set up `__init__.py` with node registration system
- [ ] Implement `utils/` module:
- `tensor_utils.py` - Batch handling, type conversions
- `image_processing.py` - Common image operations
- `color_math.py` - Color space utilities
- [ ] Create base test framework
- [ ] Document coding standards and contribution guidelines
**Deliverable:** Working project skeleton that loads in ComfyUI
### Phase 2: Core Compositing Nodes (Week 3-5)
**Goal:** Implement essential daily-use nodes
**Priority 1 - Most Critical:**
- [ ] Merge node with blend modes (Over, Under, Plus, Screen, Multiply)
- [ ] Transform (translate, rotate, scale with motion blur)
- [ ] Blur (Gaussian with separate X/Y)
- [ ] Grade (lift/gamma/gain with master + RGB controls)
- [ ] Premultiply/Unpremultiply
**Priority 2 - High Usage:**
- [ ] ColorCorrect (saturation, contrast, gamma, offset)
- [ ] Erode/Dilate
- [ ] Shuffle (channel operations)
- [ ] Clamp (min/max value control)
**Deliverable:** Working compositor toolkit for basic workflows
### Phase 3: Keying & Matte Operations (Week 6-7)
**Goal:** Professional keying tools
- [ ] Basic ChromaKeyer (green/blue screen)
- [ ] LumaKeyer (luminance-based)
- [ ] MatteControl (contract, expand, blur, gamma for mattes)
- [ ] DifferenceKeyer (difference matte generation)
- [ ] Key refinement utilities
**Deliverable:** Complete keying pipeline
### Phase 4: Advanced Color & Filters (Week 8-9)
**Goal:** Professional color and filter tools
**Color:**
- [ ] HueCorrect/ColorCurves
- [ ] Saturation controls
- [ ] Invert
- [ ] Color space conversions
**Filters:**
- [ ] Defocus (lens-style)
- [ ] DirectionalBlur
- [ ] Sharpen/Unsharp Mask
- [ ] Median filter
- [ ] EdgeDetect
**Deliverable:** Advanced color grading and filtering
### Phase 5: Transform & Warping (Week 10-11)
**Goal:** Geometric manipulation tools
- [ ] CornerPin (4-point perspective)
- [ ] GridWarp (manual warping)
- [ ] LensDistortion (add/remove)
- [ ] IDistort/Displace (displacement mapping)
- [ ] Stabilize (if tracking data available)
**Deliverable:** Full transform and warping toolkit
### Phase 6: Time Operations (Week 12)
**Goal:** Temporal effects
- [ ] FrameHold
- [ ] TimeOffset
- [ ] TimeSpeed (retiming)
- [ ] VectorBlur (motion vectors)
**Deliverable:** Time manipulation nodes
### Phase 7: Testing & Documentation (Week 13-14)
**Goal:** Production-ready package
- [ ] Comprehensive unit tests for all nodes
- [ ] Integration tests with example workflows
- [ ] Performance profiling and optimization
- [ ] Complete README with examples
- [ ] Per-node documentation
- [ ] Tutorial workflows
- [ ] Video demonstrations (optional)
**Deliverable:** Fully tested and documented package
### Phase 8: Publishing & Community (Week 15+)
**Goal:** Release and support
- [ ] Submit to ComfyUI Manager
- [ ] Register on ComfyUI Registry
- [ ] Create GitHub releases
- [ ] Set up issue templates
- [ ] Community feedback integration
- [ ] Bug fixes and refinements
**Deliverable:** Public release v1.0.0
---
## Notes & Considerations
### Technical Constraints
**ComfyUI Limitations:**
- Node updates require ComfyUI restart (no hot reload)
- IMAGE tensors must maintain [B,H,W,C] shape convention
- Limited UI customization compared to standalone applications
- JavaScript extensions have access restrictions
**Performance Constraints:**
- All processing must be reasonably fast for interactive use
- Batch operations should leverage vectorization
- Memory usage must be reasonable for typical image sizes (1080p-4K)
- Avoid blocking operations that freeze the UI
**Compatibility:**
- Must work with ComfyUI's PyTorch-based IMAGE format
- Should handle both RGB (3-channel) and RGBA (4-channel) images
- Need to support batch processing (batch dimension in tensors)
- Color values are 0.0-1.0 float range (not 0-255)
**Alpha/Premultiplication:**
- ComfyUI doesn't have strict premultiplication conventions
- Need explicit Premult/Unpremult nodes like Nuke
- Must document which nodes expect premultiplied vs straight alpha
- Merge operations should handle alpha correctly
### Security Considerations
**Input Validation:**
- Validate all user inputs (ranges, types, file paths)
- Prevent division by zero in mathematical operations
- Handle edge cases (empty images, single pixel images, etc.)
- Sanitize file paths if implementing file I/O
**Dependency Security:**
- Use well-maintained, trusted libraries only
- Pin dependency versions in requirements.txt
- Regularly update for security patches
- Avoid unnecessary dependencies that increase attack surface
**User Safety:**
- No arbitrary code execution from user inputs
- No network requests without explicit user consent
- Clear warnings for destructive operations
- Safe error handling (don't expose system internals)
### Performance Requirements
**Target Performance:**
- 1080p images: <100ms per node operation
- 4K images: <500ms per node operation
- Batch processing: Linear scaling with batch size
- Memory usage: <2x input image size
**Optimization Strategies:**
- Use PyTorch operations instead of Python loops
- Leverage GPU acceleration where available
- Implement efficient algorithms (avoid O(n²) when O(n) exists)
- Cache expensive computations when possible
- Use in-place operations to reduce memory allocation
**Profiling:**
- Regular performance testing with various image sizes
- Memory profiling to detect leaks
- Bottleneck identification and optimization
- Comparison with reference implementations (Nuke/Fusion)
### Future Enhancements
**Phase 2 Features:**
- 3D compositing nodes (Camera, Lights, Geometry)
- Advanced keyers (Primatte, professional-grade algorithms)
- Planar tracking and transforms
- Optical flow retiming
- Lens distortion with specific camera models
- Advanced color science (ACES, OCIO integration)
**Advanced Capabilities:**
- Motion vector generation and manipulation
- Deep compositing (if ComfyUI supports depth data)
- Multi-channel EXR support
- Cryptomatte integration
- Smart matte generation using AI
- Temporal coherence for video sequences
**Workflow Improvements:**
- Preset library for common operations
- Node macros/gizmos (compound nodes)
- Expression support for parameter linking
- Curve editors for advanced controls
- Comparative viewers (A/B comparison)
**Community Features:**
- User-submitted node requests
- Community presets and workflows
- Integration with other popular ComfyUI packages
- Cross-platform workflow exchange with Nuke/Fusion
**Documentation:**
- Interactive tutorials
- Video walkthrough series
- Comparison guides (Nuke → Detonate, Fusion → Detonate)
- Best practices for hybrid AI/traditional workflows
---
## References & Resources
### Official Documentation
- [ComfyUI Documentation](https://docs.comfy.org/)
- [ComfyUI GitHub](https://github.com/comfyanonymous/ComfyUI)
- [ComfyUI Custom Node Walkthrough](https://docs.comfy.org/custom-nodes/walkthrough)
- [ComfyUI Manager](https://github.com/ltdrdata/ComfyUI-Manager)
- [ComfyUI Registry](https://registry.comfy.org/)
- [ComfyUI CLI](https://github.com/Comfy-Org/comfy-cli)
### Node Development Resources
- [Suzie1's Custom Node Guide](https://github.com/Suzie1/ComfyUI_Guide_To_Making_Custom_Nodes)
- [Example Node Template](https://github.com/comfyanonymous/ComfyUI/blob/master/custom_nodes/example_node.py.example)
- [ComfyUI-Impact-Pack](https://github.com/ltdrdata/ComfyUI-Impact-Pack) - Reference implementation
- [ComfyUI-KJNodes](https://github.com/kijai/ComfyUI-KJNodes) - Example custom nodes
- [WAS Node Suite](https://github.com/WASasquatch/was-node-suite-comfyui) - Comprehensive example
### Traditional Compositing References
- [The Foundry Nuke Documentation](https://learn.foundry.com/nuke/)
- [Blackmagic Fusion Documentation](https://documents.blackmagicdesign.com/UserManuals/Fusion_Manual.pdf)
- [VFXPedia](https://www.vfxpedia.com/) - VFX knowledge base
- [Nuke to Fusion Translation](https://github.com/statixVFX/nuke2fusion) - Node equivalency reference
### Related Projects
- **Existing ComfyUI Packages:**
- ComfyUI-Advanced-ControlNet
- ComfyUI-VideoHelperSuite
- ComfyUI_Comfyroll_CustomNodes
- ComfyUI-Manager (for distribution)
- **Compositing Tools:**
- Natron - Open source compositing (similar to Nuke)
- Blender Compositor - Node-based compositing reference
### Research & Technical Resources
**Image Processing:**
- [PyTorch Documentation](https://pytorch.org/docs/stable/index.html)
- [OpenCV Documentation](https://docs.opencv.org/)
- [scikit-image](https://scikit-image.org/)
- [Pillow Documentation](https://pillow.readthedocs.io/)
**Color Science:**
- [Colour Science for Python](https://www.colour-science.org/)
- [ACES Documentation](https://acescentral.com/)
- [OpenColorIO](https://opencolorio.org/)
**Compositing Algorithms:**
- "Compositing Digital Images" (Porter & Duff, 1984) - Alpha compositing paper
- "Digital Compositing for Film and Video" (Steve Wright) - Industry reference book
- [Alpha Compositing on Wikipedia](https://en.wikipedia.org/wiki/Alpha_compositing)
### Community & Support
- [ComfyUI Discord](https://discord.gg/comfyui) - Community support
- [ComfyUI Subreddit](https://www.reddit.com/r/comfyui/)
- [ComfyUI Workflows](https://comfyworkflows.com/) - Workflow sharing
- GitHub Issues - For bug reports and feature requests (when published)
---
## Appendix: Common Node Mapping
### Quick Reference: Nuke/Fusion → Detonate
| Category | Nuke | Fusion | Detonate (Planned) |
|----------|------|--------|-------------------|
| **Merge** | Merge | Merge | Merge |
| **Color** | Grade | ColorCorrector | Grade |
| **Blur** | Blur | Blur | Blur |
| **Key** | Keylight | DeltaKeyer | ChromaKeyer |
| **Transform** | Transform | Transform | Transform |
| **Matte** | FilterErode | MatteControl | MatteControl |
| **Channel** | Shuffle | ChannelBooleans | Shuffle |
| **Premult** | Premult | (in Merge) | Premult |
See full node comparison in research documentation.
TASKS.md
+484
View File
@@ -0,0 +1,484 @@
# ComfyUI_Detonate - Development Tasks
This is a working task list for tracking implementation progress. Check off items as they're completed.
---
## Phase 1: Foundation & Infrastructure
### Project Setup
- [ ] Initialize directory structure
- [ ] Create `nodes/` directory
- [ ] Create `nodes/compositing/` directory
- [ ] Create `nodes/color/` directory
- [ ] Create `nodes/keying/` directory
- [ ] Create `nodes/transform/` directory
- [ ] Create `nodes/filter/` directory
- [ ] Create `nodes/matte/` directory
- [ ] Create `nodes/channel/` directory
- [ ] Create `nodes/time/` directory
- [ ] Create `nodes/3d/` directory
- [ ] Create `utils/` directory
- [ ] Create `tests/` directory
- [ ] Create `examples/` directory
- [ ] Create `web/js/` directory
### Package Configuration
- [ ] Create `pyproject.toml` with project metadata
- [ ] Create `requirements.txt` with dependencies
- [ ] Create `README.md` with project overview
- [ ] Create `LICENSE` file
- [ ] Create `.gitignore` for Python/ComfyUI
### Core Infrastructure
- [ ] Implement `__init__.py` with node registration system
- [ ] Create `utils/tensor_utils.py`
- [ ] Batch handling utilities
- [ ] Type conversion functions
- [ ] Tensor validation helpers
- [ ] Create `utils/image_processing.py`
- [ ] Common image operations
- [ ] Alpha channel handling
- [ ] Image format conversions
- [ ] Create `utils/color_math.py`
- [ ] RGB/HSV conversions
- [ ] Premultiply/unpremultiply utilities
- [ ] Color space conversion helpers
### Testing Setup
- [ ] Set up pytest configuration
- [ ] Create test utilities and fixtures
- [ ] Create sample test images
- [ ] Document testing procedures
### Documentation
- [ ] Create coding standards document
- [ ] Create contribution guidelines
- [ ] Document node development template
---
## Phase 2: Core Compositing Nodes (Priority 1)
### 1. Merge Node
- [ ] Implement base Merge node class
- [ ] Add "Over" blend mode (A over B)
- [ ] Add "Under" blend mode
- [ ] Add "Plus" blend mode (additive)
- [ ] Add "Screen" blend mode
- [ ] Add "Multiply" blend mode
- [ ] Add "Stencil" blend mode
- [ ] Add "Mask" blend mode
- [ ] Add "Atop" blend mode
- [ ] Add mix/opacity control
- [ ] Handle alpha channels correctly
- [ ] Add unit tests for Merge node
- [ ] Create example workflow
### 2. Transform Node
- [ ] Implement base Transform node class
- [ ] Add translate (X/Y position)
- [ ] Add rotate (degrees)
- [ ] Add scale (uniform and X/Y separate)
- [ ] Add center point control
- [ ] Add skew controls
- [ ] Add filter quality options (nearest, bilinear, bicubic)
- [ ] Add motion blur (optional for v1)
- [ ] Handle edge modes (black, clamp, repeat)
- [ ] Add unit tests for Transform node
- [ ] Create example workflow
### 3. Blur Node
- [ ] Implement base Blur node class
- [ ] Add Gaussian blur algorithm
- [ ] Add separate X/Y blur size controls
- [ ] Add quality/iteration controls
- [ ] Optimize for performance (GPU acceleration)
- [ ] Handle alpha channels correctly
- [ ] Add unit tests for Blur node
- [ ] Create example workflow
### 4. Grade Node
- [ ] Implement base Grade node class
- [ ] Add Lift controls (Master + RGB)
- [ ] Add Gamma controls (Master + RGB)
- [ ] Add Gain controls (Master + RGB)
- [ ] Add Offset controls (Master + RGB)
- [ ] Implement proper color math (shadows/mids/highlights)
- [ ] Add black point/white point clamps
- [ ] Add reverse toggle
- [ ] Add unit tests for Grade node
- [ ] Create example workflow
### 5. Premultiply / Unpremultiply Nodes
- [ ] Implement Premultiply node
- [ ] Multiply RGB by alpha
- [ ] Handle edge cases (alpha = 0)
- [ ] Implement Unpremultiply node
- [ ] Divide RGB by alpha
- [ ] Handle division by zero
- [ ] Add clipping options
- [ ] Add unit tests
- [ ] Create example workflow
---
## Phase 2: Core Compositing Nodes (Priority 2)
### 6. ColorCorrect Node
- [ ] Implement base ColorCorrect node class
- [ ] Add Saturation control
- [ ] Add Contrast control
- [ ] Add Gamma control
- [ ] Add Gain control
- [ ] Add Offset control
- [ ] Add unit tests for ColorCorrect node
- [ ] Create example workflow
### 7. Erode / Dilate Node
- [ ] Implement Erode node
- [ ] Add size parameter
- [ ] Implement morphological erosion
- [ ] Optimize for performance
- [ ] Implement Dilate node
- [ ] Add size parameter
- [ ] Implement morphological dilation
- [ ] Optimize for performance
- [ ] Add unit tests
- [ ] Create example workflow
### 8. Shuffle Node
- [ ] Implement base Shuffle node class
- [ ] Add channel selection (R, G, B, A, 0, 1)
- [ ] Add output channel mapping
- [ ] Support multi-channel operations
- [ ] Handle missing alpha channels
- [ ] Add unit tests for Shuffle node
- [ ] Create example workflow
### 9. Clamp Node
- [ ] Implement base Clamp node class
- [ ] Add minimum value control
- [ ] Add maximum value control
- [ ] Add per-channel clamping option
- [ ] Add unit tests for Clamp node
- [ ] Create example workflow
---
## Phase 3: Keying & Matte Operations
### 10. ChromaKeyer Node (Basic)
- [ ] Implement base ChromaKeyer node class
- [ ] Add key color picker
- [ ] Add acceptance (tolerance) control
- [ ] Add suppression angle control
- [ ] Implement basic chroma keying algorithm
- [ ] Add spill suppression
- [ ] Add edge softness/blur
- [ ] Add unit tests for ChromaKeyer node
- [ ] Create example workflow with green screen
### 11. LumaKeyer Node
- [ ] Implement base LumaKeyer node class
- [ ] Add threshold controls (min/max)
- [ ] Add softness/falloff controls
- [ ] Add invert option
- [ ] Add unit tests for LumaKeyer node
- [ ] Create example workflow
### 12. MatteControl Node
- [ ] Implement base MatteControl node class
- [ ] Add contract control
- [ ] Add expand control
- [ ] Add blur control
- [ ] Add gamma control
- [ ] Combine operations efficiently
- [ ] Add unit tests for MatteControl node
- [ ] Create example workflow
### 13. DifferenceKeyer Node
- [ ] Implement base DifferenceKeyer node class
- [ ] Add clean plate input
- [ ] Add threshold control
- [ ] Add softness control
- [ ] Implement difference matte generation
- [ ] Add unit tests for DifferenceKeyer node
- [ ] Create example workflow
---
## Phase 4: Advanced Color & Filters
### 14. Saturation Node
- [ ] Implement base Saturation node class
- [ ] Add saturation amount control
- [ ] Use HSV color space conversion
- [ ] Preserve luminance correctly
- [ ] Add unit tests for Saturation node
- [ ] Create example workflow
### 15. Invert Node
- [ ] Implement base Invert node class
- [ ] Add per-channel invert options
- [ ] Add RGB/Alpha separate controls
- [ ] Add unit tests for Invert node
- [ ] Create example workflow
### 16. HueCorrect / ColorCurves Node
- [ ] Implement base HueCorrect node class
- [ ] Add hue range selection
- [ ] Add saturation adjustment per hue
- [ ] Add value/lightness adjustment per hue
- [ ] Implement curve-based controls
- [ ] Add unit tests
- [ ] Create example workflow
### 17. Defocus Node
- [ ] Implement base Defocus node class
- [ ] Add defocus amount control
- [ ] Implement bokeh-style blur
- [ ] Add quality controls
- [ ] Optimize for performance
- [ ] Add unit tests for Defocus node
- [ ] Create example workflow
### 18. DirectionalBlur Node
- [ ] Implement base DirectionalBlur node class
- [ ] Add angle control
- [ ] Add distance control
- [ ] Add quality/samples control
- [ ] Add unit tests for DirectionalBlur node
- [ ] Create example workflow
### 19. Sharpen Node
- [ ] Implement base Sharpen node class
- [ ] Add amount control
- [ ] Implement unsharp mask algorithm
- [ ] Add size control
- [ ] Add unit tests for Sharpen node
- [ ] Create example workflow
### 20. EdgeDetect Node
- [ ] Implement base EdgeDetect node class
- [ ] Add Sobel edge detection
- [ ] Add Laplacian option
- [ ] Add threshold control
- [ ] Add unit tests for EdgeDetect node
- [ ] Create example workflow
### 21. Median Filter Node
- [ ] Implement base Median node class
- [ ] Add kernel size control
- [ ] Implement median filtering
- [ ] Optimize for performance
- [ ] Add unit tests for Median node
- [ ] Create example workflow
---
## Phase 5: Transform & Warping
### 22. CornerPin Node
- [ ] Implement base CornerPin node class
- [ ] Add 4 corner point controls
- [ ] Implement perspective transform
- [ ] Add filter quality options
- [ ] Add unit tests for CornerPin node
- [ ] Create example workflow
### 23. GridWarp Node
- [ ] Implement base GridWarp node class
- [ ] Add grid resolution controls
- [ ] Implement mesh deformation
- [ ] Add control point manipulation
- [ ] Add unit tests for GridWarp node
- [ ] Create example workflow
### 24. LensDistortion Node
- [ ] Implement base LensDistortion node class
- [ ] Add distortion amount control
- [ ] Implement barrel/pincushion distortion
- [ ] Add center point control
- [ ] Add unit tests for LensDistortion node
- [ ] Create example workflow
### 25. Displace Node
- [ ] Implement base Displace node class
- [ ] Add displacement map input
- [ ] Add X/Y scale controls
- [ ] Add channel mapping options
- [ ] Add unit tests for Displace node
- [ ] Create example workflow
---
## Phase 6: Time Operations
### 26. FrameHold Node
- [ ] Implement base FrameHold node class
- [ ] Add frame number control
- [ ] Implement frame caching
- [ ] Add unit tests for FrameHold node
- [ ] Create example workflow
### 27. TimeOffset Node
- [ ] Implement base TimeOffset node class
- [ ] Add offset amount control
- [ ] Add loop mode options
- [ ] Add unit tests for TimeOffset node
- [ ] Create example workflow
### 28. VectorBlur Node (Advanced)
- [ ] Implement base VectorBlur node class
- [ ] Add motion vector input
- [ ] Add blur amount control
- [ ] Implement vector-based sampling
- [ ] Add unit tests for VectorBlur node
- [ ] Create example workflow
---
## Phase 7: Additional Utilities
### 29. Constant/Background Node
- [ ] Implement base Constant node class
- [ ] Add color picker
- [ ] Add width/height controls
- [ ] Add gradient options (optional)
- [ ] Add unit tests for Constant node
- [ ] Create example workflow
### 30. Copy/ChannelCopy Node
- [ ] Implement base ChannelCopy node class
- [ ] Add source/target channel selection
- [ ] Support multiple channel copies
- [ ] Add unit tests for ChannelCopy node
- [ ] Create example workflow
### 31. Remove Channels Node
- [ ] Implement base Remove node class
- [ ] Add channel selection options
- [ ] Add unit tests for Remove node
- [ ] Create example workflow
### 32. Noise Generator Node
- [ ] Implement base Noise node class
- [ ] Add Perlin/Simplex noise options
- [ ] Add frequency/scale controls
- [ ] Add octaves/detail controls
- [ ] Add unit tests for Noise node
- [ ] Create example workflow
### 33. Ramp/Gradient Node
- [ ] Implement base Ramp node class
- [ ] Add linear gradient
- [ ] Add radial gradient
- [ ] Add color controls
- [ ] Add direction/angle controls
- [ ] Add unit tests for Ramp node
- [ ] Create example workflow
---
## Phase 8: Testing & Documentation
### Comprehensive Testing
- [ ] Write unit tests for all utility functions
- [ ] Write integration tests for common workflows
- [ ] Test with various image sizes (1080p, 4K)
- [ ] Test batch processing functionality
- [ ] Performance profiling and benchmarking
- [ ] Memory leak testing
- [ ] Edge case testing (1x1 images, huge images, etc.)
### Documentation
- [ ] Complete README.md with installation instructions
- [ ] Document each node with parameters and examples
- [ ] Create tutorial workflows for common use cases
- [ ] Basic compositing workflow
- [ ] Green screen keying workflow
- [ ] Color grading workflow
- [ ] Matte refinement workflow
- [ ] Create comparison guide (Nuke → Detonate)
- [ ] Create comparison guide (Fusion → Detonate)
- [ ] Record video demonstrations (optional)
### Code Quality
- [ ] Run black formatter on all Python files
- [ ] Run flake8 linter and fix issues
- [ ] Add docstrings to all public functions
- [ ] Add type hints (optional)
- [ ] Code review and refactoring
---
## Phase 9: Publishing & Release
### Pre-Release
- [ ] Final testing pass
- [ ] Update version to 1.0.0
- [ ] Create CHANGELOG.md
- [ ] Write comprehensive README.md
- [ ] Create example workflow gallery
### GitHub Setup
- [ ] Create release v1.0.0
- [ ] Tag release in git
- [ ] Create issue templates
- [ ] Create pull request template
- [ ] Add contributing guidelines
### Distribution
- [ ] Submit to ComfyUI Manager
- [ ] Register on ComfyUI Registry (optional)
- [ ] Announce on ComfyUI Discord/Reddit
- [ ] Monitor for bug reports and feedback
### Post-Release
- [ ] Address initial bug reports
- [ ] Gather user feedback
- [ ] Plan next features based on requests
- [ ] Regular maintenance and updates
---
## Future Phases (Post v1.0)
### Advanced Features (v2.0)
- [ ] Tracking nodes (2D Point Tracker)
- [ ] Planar tracking
- [ ] Stabilization
- [ ] Optical flow retiming
- [ ] 3D compositing nodes
- [ ] Advanced keyers (Primatte-style)
- [ ] ACES/OCIO color management
- [ ] EXR multi-channel support
### Community Features
- [ ] User-submitted node requests
- [ ] Preset library system
- [ ] Node macro/gizmo system
- [ ] Expression support
---
## Notes
**Priority Levels:**
- Phase 1-2: Critical for basic functionality (MVP)
- Phase 3-4: Professional features
- Phase 5-6: Advanced capabilities
- Phase 7-9: Polish and release
- Future: Enhancement and expansion
**Completion Tracking:**
Mark items as complete using `[x]` as you finish them.
**Estimated Timeline:**
- Phase 1: 2 weeks
- Phase 2: 3 weeks
- Phase 3-4: 4 weeks
- Phase 5-6: 4 weeks
- Phase 7-9: 3 weeks
- **Total: ~16 weeks to v1.0**