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

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)

{
  "productCode": "450",
  "description": "#450 RAVEN STORM WINDOWS",
  "image": "images/450.jpg",
  "colors": ["White", "Black", "Bronze"],
  "materials": ["Aluminum"]
}

Product with Layered Images

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

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

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
├── 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