ComfyUI Extension: BoxBox

Authored by mercu-lore

Created

Updated

1 stars

BoxBox is a lightweight ComfyUI extension for drawing, cropping, resizing, and reinserting specific regions of an image.

Custom Nodes (0)

    README

    BoxBox - Complete Image Region Processing Suite

    A comprehensive ComfyUI custom nodes package for selecting, cropping, resizing, and reinserting image regions with full metadata tracking.

    šŸ“‹ Overview

    BoxBox provides a complete workflow for working with specific image regions:

    1. šŸ“¦ BoxSelector - Interactive interface to select rectangular regions on images
    2. āœ‚ļø BoxCrop - Crop selected regions from original images
    3. šŸ“¦ BoxResize - Resize cropped regions with preset aspect ratios for AI generation
    4. šŸŽØ BoxReinsert - Reinsert generated images back into original positions

    šŸŽÆ Available Nodes

    1. BoxSelector (šŸ“¦ BoxSelector)

    Interactive interface to select rectangular regions on images.

    Input

    • image (IMAGE): Source image to select from

    Output

    • image (IMAGE): Original image (passthrough)
    • box_metadata (STRING): JSON with selection coordinates

    Features

    • šŸ–±ļø Interactive Selection: Click and drag to draw rectangles
    • šŸ“ Side Coordinates: Returns x1, x2, y1, y2 (not x, y, width, height)
    • šŸ”„ Clear Button: Reset selection and start over
    • šŸ“Š Live Coordinates: Shows selection position in real-time

    Output JSON Format

    {
    "x1": 100,
    "y1": 150,
    "x2": 600,
    "y2": 450,
    "borderWidth": 3,
    "borderPosition": "inside",
    "displayScaleFactor": 1.0,
    "selected": true
}

    Advanced Features

    • šŸ“ Aspect Ratio Locking: Select from preset ratios or draw freely
      • Presets: 1:1, 3:4, 5:8, 9:16, 9:21, 4:3, 3:2, 16:9, 21:9
      • Custom: Draw freely and get closest standard ratio
    • šŸ”§ Auto-Scale Large Images: Images > 1024px automatically scaled down for smooth selection
      • Scaling factor saved in metadata (displayScaleFactor)
      • BoxCrop and BoxReinsert automatically correct coordinates

    2. BoxCrop (āœ‚ļø BoxCrop)

    Crops images according to coordinates provided by BoxSelector.

    Input

    • image (IMAGE): Image to crop
    • box_metadata (STRING): JSON coordinates from BoxSelector (x1, x2, y1, y2)
      • Connect directly from BoxSelector output

    Optional Input

    • fallback_mode (COMBO): Behavior when no valid coordinates
      • use_full_image: Return entire image (default)
      • return_zero: Return black image
      • error: Raise error

    Output

    • cropped_image (IMAGE): Cropped region

    How It Works

    1. Extracts x1, x2, y1, y2 from metadata
    2. If displayScaleFactor is present (from large image auto-scaling):
      • Divides coordinates by scale factor to convert from preview space to original image space
    3. Normalizes coordinates (ensures x1 < x2, y1 < y2)
    4. Clips to image boundaries
    5. Crops the specified region

    Automatic Scale Correction

    When BoxSelector uses auto-scale for large images (> 1024px), BoxCrop automatically:

    • Detects the displayScaleFactor in metadata
    • Converts preview-space coordinates back to original-image-space
    • Ensures crops match the intended selection on the original image

    3. BoxResize (šŸ“¦ BoxResize)

    Resizes cropped regions with preset aspect ratios or custom dimensions, with full metadata tracking.

    Input

    • image (IMAGE): Image to resize
    • size (COMBO): Preset selection or "Custom"
      • 1:1 Square 1024x1024
      • 3:4 Portrait 896x1152
      • 5:8 Portrait 832x1216
      • 9:16 Portrait 768x1344
      • 9:21 Portrait 640x1536
      • 4:3 Landscape 1152x896
      • 3:2 Landscape 1216x832
      • 16:9 Landscape 1344x768
      • 21:9 Landscape 1536x640
      • Custom (use width/height parameters)

    Optional Input

    • keep_aspect_ratio (BOOLEAN): Maintain original aspect ratio (default: True)
    • interpolation_mode (COMBO): Resize algorithm
      • bilinear (default, faster)
      • bicubic (higher quality)
      • nearest (pixel-perfect)
    • width (INT): Custom width [64-8192, step 8] (when size = "Custom")
    • height (INT): Custom height [64-8192, step 8] (when size = "Custom")

    Output

    • image (IMAGE): Resized image
    • resize_metadata (STRING): JSON with resize information

    Output JSON Format

    {
    "original_width": 500,
    "original_height": 300,
    "resized_width": 1024,
    "resized_height": 1024,
    "scale_x": 2.048,
    "scale_y": 3.413,
    "size_preset": "1:1 Square 1024x1024",
    "keep_aspect_ratio": true,
    "interpolation_mode": "bilinear"
}

    4. BoxReinsert (šŸŽØ BoxReinsert)

    Reinserts generated images back into original positions using metadata.

    Input

    • original_image (IMAGE): Original full-size image
    • generated_image (IMAGE): Generated/processed image
    • box_metadata (STRING): Selection coordinates from BoxSelector
    • resize_metadata (STRING): Resize information from BoxResize

    Output

    • image (IMAGE): Final image with generated content reinserted

    How It Works

    1. Reads box_metadata for original selection position (x1, x2, y1, y2)
    2. If displayScaleFactor is present (from large image auto-scaling):
      • Divides coordinates by scale factor to convert from preview space to original image space
    3. If resize_metadata is provided:
      • Resizes generated_image back to crop dimensions
      • Inserts at exact original position
    4. If resize_metadata is empty:
      • Inserts generated_image as-is (bypasses resize reversal)
    5. Returns full image with processed region in place

    Automatic Scale Correction

    When BoxSelector uses auto-scale for large images (> 1024px), BoxReinsert automatically:

    • Detects the displayScaleFactor in metadata
    • Converts preview-space coordinates back to original-image-space
    • Reinserts the generated content at the correct position on the original image

    Flexible Workflow

    • With Resize: Generated ā†’ De-resize ā†’ Reinsert
    • Without Resize: Generated ā†’ Reinsert directly

    šŸ”„ Complete Workflow

    Standard AI Generation Workflow

    LoadImage
    ā†“
šŸ“¦ BoxSelector (select region interactively)
    ā†“ box_metadata
āœ‚ļø BoxCrop (extract region)
    ā†“ cropped_image
šŸ“¦ BoxResize (prepare for AI, e.g., 1024x1024)
    ā†“ resize_metadata
[AI Generation Model - SDXL, SD, etc.]
    ā†“ generated_image
šŸŽØ BoxReinsert (put back in original position)
    ā†“
Output: Final image with AI-generated region

    Direct Editing Workflow (skip resize)

    LoadImage
    ā†“
šŸ“¦ BoxSelector (select region)
    ā†“ box_metadata
āœ‚ļø BoxCrop (extract region)
    ā†“ cropped_image
[Edit/Filter directly]
    ā†“ edited_image
šŸŽØ BoxReinsert (reinsert without resize)
    ā†“
Output: Final image

    šŸ’” Metadata System

    The metadata system ensures complete traceability:

    1. BoxSelector Output: {"x1": ..., "y1": ..., "x2": ..., "y2": ..., "displayScaleFactor": ...}

      • Stores original selection coordinates
      • Includes scale factor if image was auto-scaled (for large images > 1024px)
      • borderWidth and borderPosition also included

    2. BoxResize Output: {"original_width": ..., "resized_width": ..., "scale_x": ..., ...}

      • Tracks resize transformation for reversal

    3. BoxCrop & BoxReinsert: Automatically handle:

      • If displayScaleFactor present: Convert coordinates from preview-space to original-image-space
      • Use converted coordinates for accurate cropping and reinsertion
      • Both nodes work seamlessly with auto-scaled selections

    āš™ļø Settings & Presets

    BoxSelector

    • Border Width: Fixed at 3px (built-in)
    • Border Position: Fixed at "inside" (built-in)

    BoxResize Presets

    All presets optimize for AI generation models:

    • Square: 1:1 ratio at 1024x1024
    • Portrait: Multiple heights (3:4, 5:8, 9:16, 9:21)
    • Landscape: Multiple widths (4:3, 3:2, 16:9, 21:9)

    BoxResize Interpolation

    • bilinear: Fast, good quality (default)
    • bicubic: Slower, higher quality
    • nearest: Pixel-perfect, no smoothing

    šŸ”„ Coordinate System

    All nodes use side coordinates (x1, x2, y1, y2):

    • x1: Left edge
    • x2: Right edge
    • y1: Top edge
    • y2: Bottom edge

    This allows:

    • Easy understanding of selected region
    • Automatic validation (x1 < x2, y1 < y2)
    • Direct use for cropping and reinsertion

    šŸŽØ User Interface

    BoxSelector Dialog

    Left Panel (Controls)

    • Image name
    • Aspect Ratio selector (9 presets + Custom mode)
    • Clear Selection button
    • Selection coordinates display with live aspect ratio info
    • Scale info display (when large image is auto-scaled)

    Right Panel (Canvas)

    • Interactive image canvas
    • Auto-scaled preview (for images > 1024px)
    • Click + drag to draw rectangle
    • Drag handles to resize
    • Drag body to move
    • Resize handles with smooth interaction

    Features

    • šŸ”§ Automatic Large Image Handling: Seamlessly scales down for preview while maintaining accuracy
    • šŸ“ Aspect Ratio Locking: Lock to standard ratios or draw freely
    • šŸ“Š Live Feedback: Real-time coordinate and ratio display

    šŸ“¦ Installation

    1. Clone/copy the BoxBox folder to:

      ComfyUI/custom_nodes/BoxBox/

    2. Restart ComfyUI

    3. Nodes will appear in image/box category

    šŸ“‹ Requirements

    • ComfyUI: Latest version
    • Python: 3.8+
    • PyTorch: >= 2.0.0
    • Pillow (PIL): >= 8.0.0
    • NumPy: >= 1.20.0
    • torch.nn.functional: For interpolation (included with PyTorch)

    requirements.txt

    torch>=2.0.0
Pillow>=8.0.0
numpy>=1.20.0

    šŸš€ Quick Start

    1. Add LoadImage node
    2. Add šŸ“¦ BoxSelector node, connect image
    3. Click "šŸ“¦ Select Box" button
    4. Draw rectangle on image, click "āœ… Confirm"
    5. Add āœ‚ļø BoxCrop, connect BoxSelector output
    6. Add šŸ“¦ BoxResize, select preset (e.g., "1:1 Square 1024x1024")
    7. Send to AI model or editor
    8. Add šŸŽØ BoxReinsert:
      • Connect original image from step 1
      • Connect generated image from step 7
      • Connect box_metadata from step 4 output
      • Connect resize_metadata from step 6 output
    9. Execute graph ā†’ final image!

    šŸ› Troubleshooting

    Selection Dialog Doesn't Open

    • Make sure image is connected to BoxSelector
    • Check browser console (F12) for errors
    • Try reloading page (Ctrl+Shift+R)

    Drawing Rectangle Doesn't Work

    • Ensure you're clicking inside the image area
    • Check that cursor shows crosshair
    • Try refreshing the page

    Resize Creates Black/Empty Image

    • Check that keep_aspect_ratio is set correctly
    • Verify image dimensions are valid
    • Try different interpolation_mode

    Reinsert Doesn't Work

    • Verify all 4 inputs are connected (original_image, generated_image, box_metadata, resize_metadata)
    • Check that metadata JSON is valid
    • Ensure original_image and box_metadata match (same image used for selection)

    šŸ“ Changelog

    v1.1.0 (Current)

    • āœ… Auto-Scale Large Images: Images > 1024px automatically scaled in preview for smooth selection
    • āœ… displayScaleFactor Metadata: Scale factor saved in metadata for accurate coordinate conversion
    • āœ… Aspect Ratio Locking: 9 preset aspect ratios + custom free drawing mode
    • āœ… Smart Coordinate Correction: BoxCrop and BoxReinsert auto-correct coordinates from scaled previews
    • āœ… Live Aspect Ratio Display: Shows closest standard ratio when drawing freely

    v1.0.0

    • āœ… BoxSelector with interactive region selection
    • āœ… BoxCrop with coordinate-based cropping
    • āœ… BoxResize with preset aspect ratios and custom sizes
    • āœ… BoxReinsert with flexible resize handling
    • āœ… Complete metadata tracking system
    • āœ… Optional resize bypass in BoxReinsert
    • āœ… Multiple interpolation modes

    šŸŽ“ Advanced Usage

    Chaining Multiple Regions

    Select Region 1 ā†’ Crop ā†’ Resize ā†’ AI Generate ā†’ Reinsert
Parallel with:
Select Region 2 ā†’ Crop ā†’ Resize ā†’ AI Generate ā†’ Reinsert

    Batch Processing

    Use Reroute nodes to process same coordinates on multiple images.

    Custom Aspect Ratios

    Use BoxResize with "Custom" mode and specify exact width/height.

    šŸ“„ License

    MIT

    šŸ¤ Support

    For issues, feature requests, or suggestions, please contact the developer.

    Created for ComfyUI - Transform your images with precision! šŸŽÆāœ‚ļøšŸ“¦šŸŽØ