Initial
This commit is contained in:
Jason
@@ -0,0 +1,195 @@
|
||||
# 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)
|
||||
```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"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user