# 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
```json
{
    "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
```json
{
    "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! 🎯✂️📦🎨