CGW-Quote-Builder/DYNAMIC_IMAGE_QUICKSTART.md

# Dynamic Image Generation - Quick Start

## What Was Created

I've built a complete server-side image generation system that can dynamically create product images with different colors and configurations. Here's what's included:

### Files Created:
1. **`app/image_generator.py`** - Core image processing logic using PIL/Pillow
2. **`app/data/image_configs.json`** - Configuration for COBRAI product with colorable regions
3. **`app/templates/image_test.html`** - Test page to demonstrate the API
4. **`information/DYNAMIC_IMAGE_API.md`** - Complete documentation

### Files Modified:
1. **`app/app.py`** - Added 4 new API endpoints
2. **`app/requirements.txt`** - Added Pillow dependency

## ⚠️ Important: Image File

You need to manually save the storm door image as:
```
app/images/cobrai.jpg
```

I created a placeholder file, but you need to replace it with the actual image from your screenshot (the white storm door with two screen panels).

## Setup & Testing

### 1. Install Dependencies
```bash
cd app
pip install Pillow
```

### 2. Add the Image
Save the storm door image as `app/images/cobrai.jpg`

### 3. Start the Server
```bash
python app.py
```

### 4. Test the API

#### Option A: Visit Test Page
Open browser to:
```
http://localhost:8080/image-test
```

This interactive page lets you:
- Select colors (White, Black, Bronze, Sandstone)
- Choose hinge side (Left/Right)
- See both image rendering methods
- View the product configuration
- Clear the cache

#### Option B: Direct URL Test
Visit these URLs in your browser:
```
http://localhost:8080/api/product-image/cobrai?color=black&hinge=right
http://localhost:8080/api/product-image/cobrai?color=bronze&hinge=left
http://localhost:8080/api/product-config/cobrai
```

#### Option C: Using cURL
```bash
# Get black door image
curl http://localhost:8080/api/product-image/cobrai?color=black > test_black.png

# Get bronze left-hinge door
curl http://localhost:8080/api/product-image/cobrai?color=bronze&hinge=left > test_bronze_left.png

# Get configuration
curl http://localhost:8080/api/product-config/cobrai

# Get as JSON with base64
curl http://localhost:8080/api/product-image/cobrai?color=white&format=json
```

## How It Works

### The Configuration
The `image_configs.json` file defines:

1. **Colorable Regions** - Rectangular areas to recolor:
   - Left frame: [0, 0] to [100, 1450]
   - Right frame: [620, 0] to [720, 1450]
   - Top rail: [0, 0] to [720, 80]
   - Middle rail: [0, 590] to [720, 680]
   - Bottom panel: [100, 1090] to [620, 1450]

2. **Available Colors**:
   - White: RGB [255, 255, 255]
   - Black: RGB [30, 30, 30]
   - Bronze: RGB [110, 80, 50]
   - Sandstone: RGB [210, 190, 165]

3. **Hardware Positions** - Where handles go (placeholder for future):
   - Right hinge: position [580, 730]
   - Left hinge: position [140, 730] (flipped)

### The Process
1. Load white storm door image
2. For each colorable region:
   - Calculate pixel brightness
   - Apply target color while preserving brightness
   - This maintains shadows/highlights
3. Optionally flip for left hinge
4. Cache the result for fast subsequent requests

## API Endpoints

### 1. Generate Image
```
GET /api/product-image/<product_code>?color=<color>&hinge=<hinge>
```

**Parameters:**
- `color`: white, black, bronze, sandstone
- `hinge`: left, right
- `format`: image (default) or json
- `cache`: true (default) or false

**Returns:** PNG image or JSON with base64

### 2. Get Configuration
```
GET /api/product-config/<product_code>
```

**Returns:** JSON with all product config (colors, regions, etc.)

### 3. Clear Cache
```
POST /api/clear-image-cache
```

**Body (optional):**
```json
{"productCode": "cobrai"}
```

## Adjusting the Configuration

### If you need to change color regions:

1. Open the image in an image editor (Paint, Photoshop, etc.)
2. Note the pixel coordinates of the area you want to color
3. Edit `app/data/image_configs.json`:
   ```json
   {
     "name": "frame",
     "topLeft": [x1, y1],
     "bottomRight": [x2, y2]
   }
   ```

### If you need to adjust colors:

Edit the RGB values in `availableColors`:
```json
"bronze": {
  "rgb": [110, 80, 50],  // Adjust these numbers
  "name": "Bronze"
}
```

### If hardware images exist:

Place hardware PNGs in `app/images/hardware/` and update config:
```json
"hardwarePositions": {
  "handle_right": {
    "x": 580,
    "y": 730,
    "image": "images/hardware/handle-lever.png"
  }
}
```

## Next Steps

### To integrate into your product finder:

Replace the layered image system with dynamic generation:

```javascript
// Instead of static layers
imageDisplayHtml = `<img src="/api/product-image/${prodCode}?color=${color}&hinge=${hinge}">`;

// Or update existing image on change
function updateProductPreview(productCode) {
    const color = document.getElementById('config-color').value;
    const hinge = document.querySelector('[name="hinge-location"]:checked').value;
    
    document.getElementById('product-image').src = 
        `/api/product-image/${productCode}?color=${color}&hinge=${hinge}`;
}
```

### To add more products:

1. Take photo of product in white/neutral color
2. Save as `app/images/productcode.jpg`
3. Add configuration to `image_configs.json`
4. Define colorable regions using image editor coordinates
5. Test at `/image-test`

## Troubleshooting

**"PIL/Pillow not installed"**
```bash
pip install Pillow
```

**"Product cobrai not found"**
- Check that image exists at `app/images/cobrai.jpg`
- Check that config exists in `image_configs.json`

**Colors look weird**
- Adjust RGB values in config
- Ensure source image is white or neutral
- Check that region coordinates are correct

**Image not changing**
- Try clearing cache
- Set `cache=false` in URL parameter
- Check browser console for errors

## Performance

- **First request**: ~100-300ms (generates and caches)
- **Cached requests**: ~10-50ms (serves from cache)
- **Cache location**: `app/cache/product_images/`

## Full Documentation

See `information/DYNAMIC_IMAGE_API.md` for complete documentation including:
- Advanced configuration options
- Production deployment tips
- Frontend integration examples
- Adding glass tinting, textures, etc.
- Batch generation scripts