Luminance Stack Processor - ComfyUI Custom Nodes

Professional HDR (High Dynamic Range) processing nodes for ComfyUI using the Debevec Algorithm for merging multiple exposure images into a single high dynamic range image.

Version: 1.0.1 | Release Date: 2025-01-20

🎯 Features

• Multiple HDR Algorithms: Supports Mertens Exposure Fusion (default), Debevec, and Robertson algorithms
• Two Processing Modes:
  • 3-Stop Processor: Merges EV+2, EV+0, EV-2 exposures
  • 5-Stop Processor: Merges EV+4, EV+2, EV+0, EV-2, EV-4 exposures
• 16-bit Linear Output: Outputs 16-bit linear colorspace images with maximum dynamic range preservation
• Automatic Camera Response Function: Estimates and applies camera response curves
• Fallback Safety: Gracefully handles errors with fallback to middle exposure
• ComfyUI Integration: Seamless integration with ComfyUI workflows

📋 Requirements

• ComfyUI (includes NumPy and PyTorch)
• Python 3.8+
• OpenCV (cv2) >= 4.8.0

🚀 Installation

1. Clone or Download this repository to your ComfyUI custom nodes directory:

   # Method 1: Clone directly into ComfyUI custom nodes directory
   cd ComfyUI/custom_nodes/
   git clone https://github.com/sumitchatterjee13/Luminance-Stack-Processor.git luminance-stack-processor
   
   # Method 2: Download ZIP and extract to:
   # ComfyUI/custom_nodes/luminance-stack-processor/
   

2. Install Dependencies:

   For ComfyUI Portable (Recommended):

   # Navigate to your ComfyUI portable directory and use embedded Python
   cd path/to/ComfyUI_windows_portable
   python_embeded\python.exe -m pip install opencv-python>=4.8.0
   

   For Standard ComfyUI Installation:

   # Use your system Python or ComfyUI's virtual environment
   pip install opencv-python>=4.8.0
   

   Or install from requirements.txt:

   # For portable version
   python_embeded\python.exe -m pip install -r requirements.txt
   
   # For standard installation
   pip install -r requirements.txt
   

3. Restart ComfyUI to load the new nodes

🎨 Usage

Luminance Stack Processor (3 Stops)

Perfect for standard HDR bracketing with 3 exposures:

Inputs:

• ev_plus_2: Overexposed image (+2 EV)
• ev_0: Normal exposure image (0 EV)
• ev_minus_2: Underexposed image (-2 EV)
• exposure_step: (Optional) EV step size (default: 2.0)
• hdr_algorithm: (Optional) Algorithm to use: "mertens" (default), "debevec", "robertson"

Output:

• hdr_image: Merged 16-bit linear HDR image

Luminance Stack Processor (5 Stops)

For extended dynamic range with 5 exposures:

Inputs:

• ev_plus_4: Most overexposed image (+4 EV)
• ev_plus_2: Overexposed image (+2 EV)
• ev_0: Normal exposure image (0 EV)
• ev_minus_2: Underexposed image (-2 EV)
• ev_minus_4: Most underexposed image (-4 EV)
• exposure_step: (Optional) EV step size (default: 2.0)
• hdr_algorithm: (Optional) Algorithm to use: "mertens" (default), "debevec", "robertson"

Output:

• hdr_image: Merged 16-bit linear HDR image

🔬 How It Works

The nodes implement multiple HDR algorithms with EV0-Based Blending as the default (preserves natural appearance):

1. Analyzes Multiple Exposures: Takes differently exposed 8-bit images of the same scene
2. Estimates Camera Response Function: Determines how the camera sensor responds to light
3. Recovers Scene Radiance: Calculates the actual light values in the scene
4. Merges to HDR: Combines all exposures into a single high dynamic range image
5. Linear 16-bit Output: Outputs 16-bit linear colorspace data preserving full HDR range

🎯 HDR Algorithm Options:

EV0-Based Blending (Default - Recommended)

• Perfect for natural look: Uses EV0 as base appearance, adds dynamic range from other exposures
• Zero contrast change: Output looks exactly like EV0 with enhanced highlight/shadow detail
• Seamless blending: Uses luminance masks for smooth transitions
• Best of both worlds: Natural EV0 appearance + extended dynamic range data

Mertens Exposure Fusion

• Good alternative: Produces natural-looking results similar to Adobe Lightroom
• Automatic blending: No tone mapping needed, enhanced EV0-like appearance
• Fastest processing: No camera response function estimation required
• May add contrast: Can make images slightly more contrasty than original

Debevec Algorithm (Classic HDR)

• Industry standard: Original HDR reconstruction method from 1997
• True scene radiance: Recovers actual physical light values with automatic tone mapping
• Natural output: Now includes Reinhard tone mapping for proper brightness and colors
• Research accurate: Mathematically precise with practical usability improvements

Robertson Algorithm

• Alternative approach: Different camera response function estimation method
• Similar to Debevec: But with different mathematical approach

📸 Best Practices

For Capturing Source Images:

• Use a tripod for perfect alignment
• Keep the same white balance across all exposures
• Use manual focus to prevent focus shifts
• Capture in RAW format when possible
• Use exposure compensation or manual mode

EV (Exposure Value) Guidelines:

• 3-Stop: +2, 0, -2 EV (4x range)
• 5-Stop: +4, +2, 0, -2, -4 EV (16x range)
• Adjust exposure_step parameter if using different increments

Algorithm Selection Guide:

• Use EV0-Based (Default): When you want to keep the exact look of your EV0 image with enhanced dynamic range
• Use Mertens: For natural HDR look similar to Adobe Lightroom (may add some contrast)
• Use Debevec: For scientific/research work requiring precise scene radiance values
• Use Robertson: Alternative to Debevec with different mathematical approach

⚙️ Technical Details

• Algorithms: EV0-Based Blending (default), Mertens Exposure Fusion, Debevec, Robertson
• Input Format: 8-bit ComfyUI IMAGE tensors (0-1 float range from 8-bit sources)
• Output Format: 16-bit linear colorspace images for extended dynamic range
• Processing: OpenCV's createCalibrateDebevec() and createMergeDebevec()
• Memory: Efficient processing with automatic cleanup
• Error Handling: Graceful fallbacks with detailed logging

🔧 Troubleshooting

Common Issues:

1. "Module not found" error:

   • Ensure all dependencies are installed: pip install -r requirements.txt
   • Restart ComfyUI completely

2. Color inversion or wrong colors:

   • EV0-Based algorithm (default) - uses original EV0 colors, no issues expected
   • Mertens algorithm - produces natural colors, no issues expected
   • Debevec algorithm - now includes automatic Reinhard tone mapping for proper colors
   • Robertson algorithm - also includes tone mapping for natural appearance

3. Image too bright or too dark:

   • EV0-Based (default) - keeps exact brightness of your EV0 image
   • All other algorithms produce proper brightness levels automatically
   • Mertens - natural brightness similar to Adobe Lightroom
   • Debevec/Robertson - include automatic Reinhard tone mapping for proper brightness

4. Poor HDR results:

   • Ensure input images are properly exposed (not all over/under)
   • Check that images are aligned (use tripod)
   • Verify EV differences match your capture method
   • For EV0-Based: Make sure the EV0 image is your desired base appearance
   • Try different algorithms: EV0-Based preserves natural look, Mertens for more artistic results

5. Memory issues:

   • Process smaller images first
   • Ensure adequate RAM available
   • Close unnecessary applications

Debug Information:

The nodes provide detailed logging. Check your ComfyUI console for processing information and error details.

🏗️ Development

Project Structure:

luminance-stack-processor/
├── __init__.py                 # ComfyUI registration
├── luminance_stack_processor.py # Main node implementations
├── requirements.txt            # Dependencies
└── README.md                  # Documentation

Contributing:

1. Fork the repository
2. Create a feature branch
3. Test with various HDR image sets
4. Submit a pull request

📝 Changelog

See CHANGELOG.md for version history and detailed release notes.

🔧 Development

Version Management

This project uses Semantic Versioning. To bump version:

# Install bumpversion
pip install bump2version

# Bump patch version (1.0.0 -> 1.0.1)
bump2version patch

# Bump minor version (1.0.0 -> 1.1.0) 
bump2version minor

# Bump major version (1.0.0 -> 2.0.0)
bump2version major

Project Structure

luminance-stack-processor/
├── __init__.py                 # ComfyUI node registration & version info
├── luminance_stack_processor.py # Main HDR processing nodes
├── version.py                  # Centralized version management
├── pyproject.toml             # Modern Python packaging configuration
├── requirements.txt           # Runtime dependencies
├── README.md                  # Documentation
└── CHANGELOG.md              # Version history

📚 References

• Debevec, P. E., & Malik, J. (1997). Recovering high dynamic range radiance maps from photographs. ACM SIGGRAPH Computer Graphics, 31(Annual Conference Series), 367-378.
• OpenCV HDR Documentation: https://docs.opencv.org/4.x/d3/db7/tutorial_hdr_imaging.html
• ComfyUI Custom Node Guidelines: https://docs.comfy.org/custom-nodes/
• Semantic Versioning: https://semver.org/

📜 License

MIT License - Feel free to use and modify for your projects.

🤝 Support

For issues, questions, or contributions:

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions or share workflows
• Check the troubleshooting section above
• Review ComfyUI console logs for detailed error information
• Check CHANGELOG.md for version-specific issues
• Ensure all dependencies are properly installed

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Happy HDR Processing! 📸✨ | Version 1.0.1