From dcf80625e4e44dcefa12352fe4b31cf40aebbbf3 Mon Sep 17 00:00:00 2001 From: Andy Tanguay Date: Sat, 22 Nov 2025 00:35:17 -0500 Subject: [PATCH] Initial commit --- CLAUDE.md | 321 +++++++++++++++++++++++ NODE_PRIORITIES.md | 335 +++++++++++++++++++++++ PLANNING.md | 641 +++++++++++++++++++++++++++++++++++++++++++++ TASKS.md | 484 ++++++++++++++++++++++++++++++++++ 4 files changed, 1781 insertions(+) create mode 100644 CLAUDE.md create mode 100644 NODE_PRIORITIES.md create mode 100644 PLANNING.md create mode 100644 TASKS.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c6b6efe --- /dev/null +++ b/CLAUDE.md @@ -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 diff --git a/NODE_PRIORITIES.md b/NODE_PRIORITIES.md new file mode 100644 index 0000000..567026f --- /dev/null +++ b/NODE_PRIORITIES.md @@ -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 diff --git a/PLANNING.md b/PLANNING.md new file mode 100644 index 0000000..fd4b150 --- /dev/null +++ b/PLANNING.md @@ -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. diff --git a/TASKS.md b/TASKS.md new file mode 100644 index 0000000..ef138e3 --- /dev/null +++ b/TASKS.md @@ -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**