CGW-Quote-Builder/information/LAYER_TRANSFORMS.md

# Layer Transform System

## Overview

The Canvas API layer system supports CSS transforms for individual layers, allowing you to flip or rotate specific layers without modifying the image files. This is particularly useful for:

- **Door Hinge Direction**: Flip the door layer horizontally to show left-hinge vs right-hinge
- **Mirror Effects**: Create symmetric variations of products
- **Multi-Configuration Support**: Use the same image assets for multiple product variations

## Configuration

Add transform configuration to your product's `imageConfig` object:

```json
{
  "productCode": "404",
  "imageConfig": {
    "useCanvasAPI": true,
    "layerTransforms": {
      "door": "flip-horizontal",
      "hardware": "flip-horizontal"
    }
  }
}
```

## Available Transforms

### `flip-horizontal`
Flips the layer horizontally (left-right mirror).

**CSS Applied**: `transform: scaleX(-1)`

**Use Case**: Door hinge direction (left-hinge vs right-hinge)

```json
"layerTransforms": {
  "door": "flip-horizontal"
}
```

### `flip-vertical`
Flips the layer vertically (top-bottom mirror).

**CSS Applied**: `transform: scaleY(-1)`

**Use Case**: Ceiling-mounted vs floor-mounted products

```json
"layerTransforms": {
  "base": "flip-vertical"
}
```

### `flip-both`
Flips the layer both horizontally and vertically (180° rotation).

**CSS Applied**: `transform: scale(-1, -1)`

**Use Case**: Complete inversion of a layer

```json
"layerTransforms": {
  "overlay": "flip-both"
}
```

## Layer Names

Available layers you can transform:
- `base` - Background/house layer
- `door` - Door/window layer (with color variations)
- `hardware` - Hardware layer (handles, locks, etc.)
- `overlay` - Additional overlay layer
- `foreground` - Foreground layer (plants, decorations)

## Complete Example

### Left-Hinge Door (Default)

```json
{
  "id": "404",
  "productCode": "404",
  "imageConfig": {
    "useCanvasAPI": true
  }
}
```

### Right-Hinge Door (Flipped)

Create a separate product entry with a different code:

```json
{
  "id": "404R",
  "productCode": "404R",
  "description": "#404 FALCON STORM WINDOWS (RIGHT-HINGE)",
  "imageConfig": {
    "useCanvasAPI": true,
    "layerTransforms": {
      "door": "flip-horizontal",
      "hardware": "flip-horizontal"
    }
  }
}
```

**Important**: Both products can share the same image files! The transform is applied in CSS at render time.

## Image Preparation Tips

When creating images that will be flipped:

1. **Design for the default orientation first** (e.g., left-hinge door)
2. **Keep text/logos off flippable layers** - they will be reversed
3. **Test the flipped version** to ensure it looks natural
4. **Consider asymmetric details** - handles, hinges, decorative elements

## Implementation Details

### CSS Classes

The system applies these CSS classes automatically:

- `.layer-flip-horizontal` - Horizontal flip
- `.layer-flip-vertical` - Vertical flip  
- `.layer-flip-both` - Both axes flip

### JavaScript

Transforms are applied in `updateCanvasAPIPreview()` function:

```javascript
const layerTransforms = product.imageConfig?.layerTransforms || {};

function applyTransform(element, layerName) {
  element.classList.remove('layer-flip-horizontal', 'layer-flip-vertical', 'layer-flip-both');
  const transform = layerTransforms[layerName];
  if (transform) {
    element.classList.add(`layer-${transform}`);
  }
}
```

## Advanced: Multiple Products, Same Images

You can create an entire product family from a single set of images:

```
/static/images/window/storm-window/404/
  ├── door-white.png      (left-hinge design)
  ├── door-black.png      (left-hinge design)
  └── ...

Products using these images:
- 404   - Left-hinge (no transform)
- 404R  - Right-hinge (door flipped)
- 404T  - Top-mount variant (base flipped)
- 404RT - Right-hinge top-mount (both flipped)
```

## Browser Compatibility

CSS transforms are supported in all modern browsers:
- Chrome/Edge: ✅
- Firefox: ✅
- Safari: ✅
- Opera: ✅

## Performance

Layer transforms are GPU-accelerated CSS operations with no performance impact. Flipping layers is instant and doesn't require:
- Additional HTTP requests
- Image processing
- Additional storage
- Server-side rendering

## Troubleshooting

### Transform not applying

1. Check that `useCanvasAPI: true` is set
2. Verify layer name matches exactly (case-sensitive)
3. Check browser console for JavaScript errors
4. Ensure CSS is loaded properly

### Image looks distorted

Transforms maintain aspect ratio. If the image looks wrong:
1. Verify the original image has correct proportions
2. Check that all layers use the same canvas dimensions
3. Test without transforms first to isolate the issue

### Text is backwards

This is expected! Don't place text or logos on layers that will be flipped. Instead:
1. Keep text on non-flipped layers (usually `base` or `overlay`)
2. Create separate images for left/right variants if text is essential
3. Use the overlay layer for directional text

## Future Enhancements

Possible additions:
- Rotation angles (90°, 180°, 270°)
- Scale adjustments (zoom in/out specific layers)
- Position offsets (shift layers left/right/up/down)
- Animation/transition effects