Files

T

Co-authored-by: Copilot <copilot@github.com>

2026-05-05 15:42:30 -05:00

7.5 KiB

Raw Blame History

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

Base Layer - House/frame (JPG) - the static background
Door Layer - The door panel (PNG with transparency) - changes with color selection
Hardware Layer - Handle/lock set (PNG with transparency) - can flip for left/right hinge
Overlay Layer - Glass view/decorative elements (PNG with transparency) - optional
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)

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

Product with Foreground Layer (Plants/Decorative Elements)

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

Start with full product photo
Create separate layers for each component
Remove background from door/hardware layers
Export:
- Base layer → JPG
- Component layers → PNG (with transparency)
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

7.5 KiB Raw Blame History