Skip to content

README.md

Latest commit

 

History

History
135 lines (100 loc) · 5.1 KB

README.md

File metadata and controls

135 lines (100 loc) · 5.1 KB
Raw

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.