Maelstrom Tools

A collection of custom nodes for ComfyUI focused on luminosity masks, image processing, upscaling, and dynamic code hot-reloading.

Installation

1. Clone this repository into your ComfyUI/custom_nodes/ directory:

   cd ComfyUI/custom_nodes
   git clone https://github.com/Maelstrom2014/Comfyui-Luminocity-masks.git

2. Install the required Python dependencies:

   pip install opencv-python scipy matplotlib scikit-image

3. Restart ComfyUI.

Features

Luminosity Masks (LumMasks)

Create and manipulate luminosity-based masks for precise image editing. Based on the Luminocity workflow with LAB color space processing.

Use cases:

• Basic lightness balancing (darken lights, brighten shadows)
• Create mood with dark midtones
• Improved vignetting with midtone masks
• Fix overexposed highlights and inpaint with SD models
• Separate detail extraction from darks, mids, and highlights
• Portraits: adjust contrast per channel (more contrast = more skin/wrinkles, less = younger skin)
• Classic color balancing: cool tones in shadows, warm tones in highlights

Nodes:

• LuminocityMaskCreate (LumMasks) - Create luminosity masks from images
• LumMaskColorCorrect (LumColorCorrect) - Apply color correction using luminosity masks
• LumBlendImages (BlendMasked) - Blend images using luminosity masks as alpha
• LumImageColorMatch (LumImageColorMatch) - Match colors between images using LAB color space

Image Upscaling with Torch Compile

Nodes:

• Upscale Image (Torch Compile) (UpscaleWithTorchCompile) - Memory-efficient upscaling using PyTorch's compile feature with tiled processing

Features:

• Torch compile support (reduce-overhead or max-autotune modes)
• Tiled upscaling (512px tiles, 32px overlap) for memory efficiency
• Compiled model caching for repeated use

Smart Saturation

Nodes:

• Smart Saturation (SmartSaturation) - Intelligent saturation adjustment using LAB color space

Dynamic Tools with Hot Reload

Nodes:

• Maelstrom Dynamic Tool #1 (MaelstromDynamicTool1) - Dynamic processing with code hot-reload capability. Edit behavior code without restarting ComfyUI
• Delete Empty Image From Batch (DeleteEmptyImageFromBatch) - Remove all-zero tensors from image batches
• Delete Empty Mask From Batch (DeleteEmptyMaskFromBatch) - Remove all-zero tensors from mask batches

Image Utilities

Nodes:

• Resize to Square with fill - Resize images to square format with configurable fill

Project Structure

maelstrom_tools/
├── __init__.py                  # Main entry point - dynamically loads all node modules
├── maelstrom_nodes.py           # Dynamic tools, batch cleaners (hot-reload system)
├── lum_masks_node.py            # Luminosity mask creation, color correction, blending
├── smart_saturation.py          # Smart saturation adjustment
├── tc_upscale.py                # Torch compile upscaler
├── gaus_func.py                 # Gaussian function utilities
├── labtools.py                  # LAB color space conversion and manipulation
├── Animals.py                   # Bobr class - function pointer pattern for dynamic code
├── behaviors/
│   ├── BobrBehaviors.py         # Dynamic behavior implementations (hot-reloadable)
│   └── test_pytorch.py          # PyTorch test utilities
├── Smetana/                     # Alternative/legacy implementations
│   ├── Animals.py
│   ├── BobrBehaviors.py
│   ├── CustomNode.py
│   └── FunctionPointerDemo.py
├── examples/                    # Example workflows and images
│   ├── lum_masks_example1.json
│   └── lum_masks_example1.png
├── workflow (7).png             # Workflow screenshots
└── workflow (8).png

Dependencies

• PyTorch (comes with ComfyUI)
• OpenCV (opencv-python)
• SciPy
• NumPy
• Pillow (PIL)
• scikit-image
• Matplotlib

Node Categories

All nodes appear under the "MaelstromTools" or "image/upscaling" categories in the ComfyUI node menu.

How It Works

Hot-Reload System

The dynamic tools use a function pointer pattern (Animals.py / behaviors/BobrBehaviors.py) that allows code to be reloaded at runtime:

1. The Bobr class holds a function pointer (the_actual_code_of_the_kurva_function)
2. Behavior functions in BobrBehaviors.py can be reloaded via imp.reload()
3. Changes to behavior code take effect immediately without restarting ComfyUI

Luminosity Masks

Luminosity masks work by:

1. Converting images to LAB color space (labtools.py)
2. Extracting the Lightness (L) channel
3. Creating smooth masks using Gaussian/spline interpolation
4. Applying targeted adjustments to shadows, midtones, or highlights independently

Examples

See the examples/ folder for sample workflows:

• lum_masks_example1.json - Luminosity mask workflow with all presets
• lum_masks_example1.png - Example output

Contributing

Pull requests welcome! Please ensure all nodes follow ComfyUI's node format conventions.