Jason
198 lines
5.6 KiB
Markdown
198 lines
5.6 KiB
Markdown
# Quick Start: Canvas API Hierarchical Image System
|
|
|
|
## What Is This?
|
|
The Canvas API lets you share images across multiple products with automatic fallback. Instead of duplicating the same plants.png file in every product folder, you can have ONE shared file that all products use.
|
|
|
|
## 5-Minute Setup
|
|
|
|
### Step 1: Organize Your Images
|
|
|
|
**Create this structure:**
|
|
```
|
|
app/static/images/
|
|
└── doors/
|
|
└── storm/
|
|
├── 404/
|
|
│ └── door-white.png # Product-specific
|
|
├── 505/
|
|
│ └── door-black.png # Product-specific
|
|
└── layers/
|
|
├── base.jpg # Shared by all storm doors
|
|
├── hardware.png # Shared by all storm doors
|
|
└── foreground.png # Shared by all storm doors
|
|
```
|
|
|
|
### Step 2: Enable Canvas API
|
|
|
|
**Edit products.json:**
|
|
```json
|
|
{
|
|
"productCode": "404",
|
|
"description": "#404 FALCON STORM WINDOWS",
|
|
"colors": ["White", "Black"],
|
|
"imageConfig": {
|
|
"useCanvasAPI": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### Step 3: Test
|
|
|
|
1. Start your Flask server
|
|
2. Visit: `http://localhost:8080/api/canvas/test`
|
|
3. Should see: `{"status": "ok"}`
|
|
4. Test specific image: `http://localhost:8080/api/canvas/404/base`
|
|
5. Open product page - images should load automatically!
|
|
|
|
## How It Works
|
|
|
|
When you request `/api/canvas/404/door?color=white`, the system searches:
|
|
|
|
1. `/images/doors/storm/404/door-white.png` ← **Checks here first**
|
|
2. `/images/doors/storm/404/door.png`
|
|
3. `/images/doors/storm/layers/door-white.png`
|
|
4. `/images/doors/storm/layers/door.png` ← **Uses this if 404-specific doesn't exist**
|
|
5. `/images/doors/layers/door.png`
|
|
6. `/images/layers/door.png`
|
|
|
|
## Directory Level Guide
|
|
|
|
| Level | Path | Use For | Example |
|
|
|-------|------|---------|---------|
|
|
| **Product** | `/images/doors/storm/404/` | Unique to this product | Custom door colors, unique base |
|
|
| **Subtype** | `/images/doors/storm/layers/` | Shared across storm doors | Common hardware, shared plants |
|
|
| **Type** | `/images/doors/layers/` | Shared across all doors | Generic handles, railings |
|
|
| **Global** | `/images/layers/` | Shared across everything | Default fallback images |
|
|
|
|
## Common Scenarios
|
|
|
|
### Scenario 1: All Products Share Plants
|
|
**Put foreground.png here:**
|
|
```
|
|
/images/doors/storm/layers/foreground.png
|
|
```
|
|
|
|
Both product 404 and 505 will use this same file automatically!
|
|
|
|
### Scenario 2: Product 404 Needs Custom Plants
|
|
**Add product-specific version:**
|
|
```
|
|
/images/doors/storm/404/foreground.png ← Product 404 uses this
|
|
/images/doors/storm/layers/foreground.png ← Product 505 uses this
|
|
```
|
|
|
|
### Scenario 3: Same Hardware for All Doors
|
|
**Put at type level:**
|
|
```
|
|
/images/doors/layers/hardware.png
|
|
```
|
|
|
|
Every door product (storm, entry, patio) uses the same hardware!
|
|
|
|
## Real-World Example
|
|
|
|
### Before (Static Layered System)
|
|
```
|
|
/images/products/404/
|
|
base.jpg (800KB)
|
|
door-white.png (200KB)
|
|
hardware.png (100KB) ← Duplicate
|
|
plants.png (150KB) ← Duplicate
|
|
|
|
/images/products/505/
|
|
base.jpg (800KB)
|
|
door-black.png (200KB)
|
|
hardware.png (100KB) ← Duplicate!
|
|
plants.png (150KB) ← Duplicate!
|
|
|
|
Total: 2.5MB
|
|
```
|
|
|
|
### After (Canvas API)
|
|
```
|
|
/images/doors/storm/404/
|
|
base.jpg (800KB)
|
|
door-white.png (200KB)
|
|
|
|
/images/doors/storm/505/
|
|
base.jpg (800KB)
|
|
door-black.png (200KB)
|
|
|
|
/images/doors/storm/layers/
|
|
hardware.png (100KB) ← Shared!
|
|
plants.png (150KB) ← Shared!
|
|
|
|
Total: 2.25MB (saved 250KB)
|
|
```
|
|
|
|
With 10 products sharing the same hardware/plants, you'd save **~2MB**!
|
|
|
|
## Quick Reference
|
|
|
|
### Enable for a Product
|
|
```json
|
|
{
|
|
"productCode": "404",
|
|
"imageConfig": {
|
|
"useCanvasAPI": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### API Endpoints
|
|
```
|
|
/api/canvas/<product_code>/<layer>?color=<color>
|
|
/api/canvas/<product_code>/info
|
|
/api/canvas/test
|
|
```
|
|
|
|
### Valid Layers
|
|
- `base` - Background/house
|
|
- `door` - Door/window panel
|
|
- `hardware` - Handles/locks
|
|
- `overlay` - Glass views
|
|
- `foreground` - Plants/decorations
|
|
|
|
### Directory Pattern
|
|
```
|
|
/images/<type>/<subtype>/<product_code>/<layer>-<color>.<ext>
|
|
/images/<type>/<subtype>/layers/<layer>.<ext>
|
|
/images/<type>/layers/<layer>.<ext>
|
|
/images/layers/<layer>.<ext>
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
**Images not loading?**
|
|
1. Check Flask logs: `[INFO] Found image: /path/to/file`
|
|
2. Visit: `/api/canvas/YOUR-PRODUCT/info`
|
|
3. Verify `"useCanvasAPI": true` in products.json
|
|
4. Check baseType/subType match directory structure
|
|
|
|
**Wrong image showing?**
|
|
- More specific paths override generic ones
|
|
- Product-specific overrides subtype
|
|
- Subtype overrides type
|
|
- Type overrides global
|
|
|
|
**404 error?**
|
|
- File doesn't exist at any fallback level
|
|
- Check file naming (lowercase for colors)
|
|
- Verify directory structure matches type/subtype
|
|
|
|
## Next Steps
|
|
|
|
1. ✅ Read the [full Canvas API Guide](CANVAS_API_GUIDE.md) for advanced features
|
|
2. ✅ Review [example JSON configurations](products-layered-example.json)
|
|
3. ✅ Check the [fallback system documentation](CANVAS_API_GUIDE.md#fallback-priority)
|
|
|
|
## Benefits
|
|
|
|
✅ **Eliminate duplication** - Share common files across products
|
|
✅ **Easier updates** - Change one file, affects all products
|
|
✅ **Smaller total size** - Less storage and bandwidth
|
|
✅ **Smart fallbacks** - Products automatically inherit shared elements
|
|
✅ **Flexible organization** - Add product-specific overrides anytime
|
|
|
|
That's it! Start organizing your images by type/subtype and watch the magic happen. 🎨
|