CGW-Quote-Builder/information/LAYERED_IMAGES.md

# Layered Image System Guide

## Overview
The product finder supports a layered image system that allows dynamic product configuration (changing colors, materials, hinge location, etc.) without requiring a separate photo for every combination.

## How It Works

### System Architecture
Images are stacked in layers (like Photoshop layers):
1. **Base Layer** - House/frame (JPG) - the static background
2. **Door Layer** - The door panel (PNG with transparency) - changes with color selection
3. **Hardware Layer** - Handle/lock set (PNG with transparency) - can flip for left/right hinge
4. **Overlay Layer** - Glass view/decorative elements (PNG with transparency) - optional
5. **Foreground Layer** - Plants, decorative items that appear in front (PNG with transparency) - optional

### Fallback Behavior
- **No layered config**: Shows the standard flat `image` field
- **Layered enabled but missing files**: Shows base layer + warning banner
- **User selects unavailable option**: Displays "Preview not available for this configuration"

## JSON Configuration

### Standard Product (Flat Image)
```json
{
  "productCode": "450",
  "description": "#450 RAVEN STORM WINDOWS",
  "image": "images/450.jpg",
  "colors": ["White", "Black", "Bronze"],
  "materials": ["Aluminum"]
}
```

### Product with Layered Images
```json
{
  "productCode": "404",
  "description": "#404 FALCON STORM WINDOWS",
  "image": "images/404.jpg",
  "colors": ["White", "Black", "Bronze", "Sandstone"],
  "materials": ["Aluminum"],
  "imageConfig": {
    "layered": true,
    "basePath": "images/products/404/",
    "layers": {
      "base": "base.jpg",
      "door": {
        "white": "door-white.png",
        "black": "door-black.png",
        "bronze": "door-bronze.png",
        "sandstone": "door-sandstone.png"
      },
      "hardware": "handle.png",
      "overlay": {
        "inside": "view-inside.png",
        "outside": "view-outside.png"
      }
    }
  }
}
```

### Partial Layered Images (Some Colors Available)
```json
{
  "productCode": "505",
  "description": "#505 DOOR",
  "image": "images/505.jpg",
  "colors": ["White", "Black", "Bronze", "Tan"],
  "materials": ["Aluminum", "Vinyl"],
  "imageConfig": {
    "layered": true,
    "basePath": "images/products/505/",
    "layers": {
      "base": "base.jpg",
      "door": {
        "white": "door-white.png",
        "black": "door-black.png"
        // Bronze and Tan not available yet - will show warning
      },
      "hardware": "handle.png"
    }
  }
}
```

### Product with Foreground Layer (Plants/Decorative Elements)
```json
{
  "productCode": "600",
  "description": "#600 PREMIUM ENTRY DOOR",
  "image": "images/600.jpg",
  "colors": ["White", "Black", "Bronze"],
  "materials": ["Aluminum"],
  "imageConfig": {
    "layered": true,
    "basePath": "images/products/600/",
    "layers": {
      "base": "base.jpg",
      "door": {
        "white": "door-white.png",
        "black": "door-black.png",
        "bronze": "door-bronze.png"
      },
      "hardware": "handle.png",
      "foreground": "plants.png"
    }
  }
}
```
**Note:** The foreground layer appears on top of all other layers and is perfect for adding plants, decorative elements, or other items that should appear in front of the product.

## File Structure

### Recommended Directory Layout
```
app/images/products/
├── 404/
│   ├── base.jpg              # Frame/house background
│   ├── door-white.png        # White door panel (transparent BG)
│   ├── door-black.png        # Black door panel (transparent BG)
│   ├── door-bronze.png       # Bronze door panel (transparent BG)
│   ├── door-sandstone.png    # Sandstone door panel (transparent BG)
│   ├── handle.png            # Hardware (transparent BG)
│   ├── view-inside.png       # Optional inside view overlay
│   └── view-outside.png      # Optional outside view overlay
├── 600/
│   ├── base.jpg              # Frame/house background
│   ├── door-white.png        # White door panel (transparent BG)
│   ├── door-black.png        # Black door panel (transparent BG)
│   ├── door-bronze.png       # Bronze door panel (transparent BG)
│   ├── handle.png            # Hardware (transparent BG)
│   └── plants.png            # Foreground layer - plants/decorative (transparent BG)
├── 450/
│   ├── base.jpg
│   └── door-white.png
└── [other products]/
```

## Creating Layered Images

### Requirements
- **Base image**: JPG format, includes frame, glass, background
- **Layer images**: PNG format with transparency
- **Consistent dimensions**: All layers for a product should be the same size
- **Alignment**: Layers must align perfectly when stacked

### Photoshop/GIMP Workflow
1. Start with full product photo
2. Create separate layers for each component
3. Remove background from door/hardware layers
4. Export:
   - Base layer → JPG
   - Component layers → PNG (with transparency)
5. Create color variants by adjusting door layer

### Photography Tips
- Use consistent lighting
- Photograph against neutral background (for easy removal)
- Keep camera/product position identical for all shots
- Consider photographing white version first, then recolor digitally

## Features

### Auto-Selection
- If product has only one color: auto-selected and dropdown disabled
- If no colors available: shows "N/A" and disabled

### Hinge Location
- Right/Left hinge radio buttons flip the hardware layer horizontally
- Works with both flat and layered images

### Dynamic Updates
- Color changes update the door layer instantly
- Missing images show warning instead of breaking

### Sorting
- Materials: Alphabetically sorted
- Colors: Alphabetically sorted with White always at bottom

## Testing Your Setup

### 1. Test Flat Fallback
Set `"layered": false` or remove `imageConfig` entirely - should show standard image

### 2. Test Missing Layer
Remove a color file - should show base + warning banner

### 3. Test All Colors
Select each color - should swap door layer smoothly

### 4. Test Hinge Flip
Toggle left/right hinge - hardware should flip horizontally

## Troubleshooting

### Images not showing
- Check file paths in `basePath` and layer filenames
- Verify files exist in `app/images/products/[code]/`
- Check browser console for 404 errors

### Colors not matching
- Ensure color keys in JSON match available color names
- Keys should be lowercase in the door config (e.g., `"white"` not `"White"`)

### Layers misaligned
- All images must be same dimensions
- Check that transparent PNGs aren't cropped differently

### Warning banner always showing
- Verify the selected color exists in `layers.door` object
- Check that color value from dropdown matches JSON key

## Migration Strategy

### Phase 1: Keep Flat Images
Keep existing flat images as fallback while creating layered versions

### Phase 2: Add Layered for Key Products
Focus on best-selling products first, add `imageConfig` gradually

### Phase 3: Full Migration
Once all images ready, can remove flat images (but recommend keeping as fallback)

## Performance Notes
- PNG layers are cached by browser
- Base image loads once, only door layer changes on color switch
- Much smaller file size than separate photos for each combination
- Example: Instead of 4 full photos (1MB each = 4MB), use 1 base (800KB) + 4 doors (200KB each = 800KB) = 1.6MB total