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

cd app
pip install Pillow

2. Add the Image

Save the storm door image as app/images/cobrai.jpg

3. Start the Server

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

# 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):

{"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:

   {
     "name": "frame",
     "topLeft": [x1, y1],
     "bottomRight": [x2, y2]
   }
   

If you need to adjust colors:

Edit the RGB values in availableColors:

"bronze": {
  "rgb": [110, 80, 50],  // Adjust these numbers
  "name": "Bronze"
}

If hardware images exist:

Place hardware PNGs in app/images/hardware/ and update config:

"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:

// 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"

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