Translucent_Relief/README_EN.md

# DreamLife-Translucent_Relief

A fully browser-based image-to-3D-printing lithophane folding fan model tool. Users upload an image, edit the fan surface, adjust lithophane relief parameters, and export STL or 3MF files for 3D printing. All computation runs locally — no image data is ever uploaded to a server.

<div align="center">
<br>

[中文](README.md) ｜ [**English**](README_EN.md)

<br>
</div>

## Feature Overview

- **Image to Lithophane**: Maps photo luminance to blade thickness; the printed fan reveals the original image when backlit
- **Three Fan Skeletons**: Type A (rounded arc head), Type B (folded-line round head, default), Type C (petal pointed head)
- **Blade Image Modes**: One shared image for the whole fan, or 11 individual images per blade
- **2D Fan Surface Editor**: Brush, eraser, text (14 Chinese art fonts, curved layout), 9 vector shape tools
- **Real-time 3D Preview**: Custom WebGL rendering pipeline with thickness-based color mapping, drag-to-rotate and scroll-to-zoom
- **Multi-format Export**: STL (binary) and 3MF (with ZIP compression), 5 mesh precision levels, 3 assembly modes

## Project Structure

```
Translucent_Relief/
├── index.html                  Main HTML file (three-panel layout + external references)
├── README_EN.md                This document
├── CSS/
│   ├── variables.css           Design tokens (colors, radius, shadows)
│   ├── base.css                Global reset, body, scrollbars, input elements
│   ├── layout.css              Top bar, three-column grid, brand header (includes Pacifico @font-face)
│   ├── components.css          Fan variant selector, blade panel, dropzone, file chip
│   ├── editor.css              2D canvas, brush cursor, floating toolbar
│   ├── controls.css            Sliders, toggles, font picker, color picker
│   ├── export.css              Export buttons, pivot download, status bar
│   ├── stage.css               3D preview stage, loading animation
│   └── responsive.css          Media queries (1200px / 900px / 640px)
├── JavaScript/
│   ├── config.js               State object, constants, fan definitions, Base64 STL skeleton data
│   ├── geometry.js             STL parsing, mesh welding, triangulation, point-in-polygon test
│   ├── image.js                Image loading, luminance sampling, demo image generation
│   ├── canvas_editor.js        Full 2D canvas editor logic (brush/text/shapes/select/undo)
│   ├── export.js               STL/3MF export, ZIP compression, CRC32, mesh building
│   ├── webgl.js                WebGL initialization, shaders, render loop
│   ├── ui.js                   Event binding, UI updates, interaction controls
│   └── initialize.js           Initialization function and startup call
└── pacifico/
    └── Pacifico.ttf            Brand title font
```

### JS Load Order

Files share a global scope dependency chain and must be loaded in the following order:

```
config.js → geometry.js → image.js → canvas_editor.js → export.js → webgl.js → ui.js → initialize.js
```

`config.js` defines global variables (`state`, `ui`, `FAN`, `DETAIL`) referenced by subsequent files. `initialize.js` calls `initialize()` at the end to start the application.

## Three-Panel Layout

| Region | Width | Content |
|--------|-------|---------|
| Left panel — Tools & Editor | 300px | Fan selection, image upload, 2D fan surface editor, composition controls |
| Center panel — 3D Preview | Adaptive | WebGL real-time preview canvas, view controls, model info |
| Right panel — Parameters & Export | 300px | Lithophane relief parameters, print output settings, STL/3MF export |

The top bar (44px) displays the DreamLife brand wordmark in Pacifico font on the left, and a "browser-local processing" status indicator on the right.

## Fan Skeletons

Three fan types, each with independent outline geometry and STL skeleton templates (embedded as Base64 in `config.js`):

| Name | Seal | Head Shape | Bounding Size (mm) |
|------|------|------------|-------------------|
| Type A (jia) | 甲 | Rounded arc head | 242 × 410 |
| Type B (yi) | 乙 | Folded-line round head | 232 × 387 |
| Type C (bing) | 丙 | Petal pointed head | 235 × 383 |

Default: Type B, 11 blades, 140-degree spread. Fixed 14-degree spacing between blades.

## Editor Tools

### Basic Tools

| Tool | Description |
|------|-------------|
| Move | Drag image position, scroll to zoom (default active) |
| Select | Select and move text or vector shape objects |
| Brush | Freehand painting, brush size 2-60px |
| Eraser | Erase brush strokes and text |
| Text | Place text on fan surface with curved layout support |

### Vector Shapes

Line, ellipse, rectangle, triangle, polygon (3-10 sides), star, diamond, arrow, spline curve (tension 0-100%).

Shape tools support both "regular (equal ratio)" and "free ratio" modes.

### Text Fonts

14 Chinese art fonts: Modern Hei, Elegant Song, Regular Kai, Running Kai (default), Clerical Li, Round, Shuti, Amber Hupo, Xinwei Stele, Caiyun Decorative, Yaoti Vintage, Zhongsong Classic, Fangsong Refined, Thin Hei. Fonts use the local system; missing fonts fall back automatically.

Supports solid fill and hollow outline styles. Font size 12-360px, arc curvature -100% to 100%.

## Lithophane Relief Parameters

| Parameter | Range | Default | Description |
|-----------|-------|---------|-------------|
| Min Thickness | 0.35-1.20mm | 0.60mm | Thinnest translucent layer |
| Max Thickness | 1.10-3.20mm | 2.20mm | Thickest opaque layer |
| Edge Margin | 0.00-1.80mm | 0.00mm | Distance between relief and skeleton edge |
| Contrast | 60-190% | 135% | Image contrast adjustment |
| Dark Gamma | 0.55-2.20 | 0.95 | Gamma correction for shadow detail |
| Blur | 0-4px | 0.5px | Gaussian blur for noise softening |
| Invert | On/Off | Off | For negatives or line art |

## Export

### Formats

| Format | Description |
|--------|-------------|
| STL | Binary format, 80-byte header, 50 bytes per triangle |
| 3MF | Standard spec with ZIP stored compression, CRC32 checksums, vertex deduplication |

### Mesh Precision

| Precision | Sample Grid | Description |
|-----------|-------------|-------------|
| Draft | 72 × 14 | Quick preview |
| Standard | 144 × 28 | Regular printing |
| Fine | 240 × 48 | High quality |
| Ultra | 320 × 64 | Recommended |
| Reference | 512 × 96 | ~2.19M triangles |

### 3MF Assembly Modes

- **Merged single object**: Welded into one complete mesh, ready for slicing (default)
- **Assembly with parts**: One assembly object containing N component references
- **Independent objects**: Each mesh as a separate build object

The pivot pin is not included in export files. It must be downloaded separately from MakerWorld.

## Design System

### Color Palette

Light scheme inspired by Microsoft Fluent design:

| Usage | Color |
|-------|-------|
| Page background | #f3f4f6 |
| Panel background | #ffffff |
| Primary text | #1a1d23 |
| Secondary text | #5a5f6a |
| Accent blue | #0078d4 |
| Warning red | #d13438 |
| Success green | #107c10 |

### Typography

| Usage | Font |
|-------|------|
| Body text | Segoe UI, Microsoft YaHei UI, system-ui |
| Brand title | Pacifico |
| Monospace (data/labels) | Cascadia Code, Consolas |
| Seal / fan names | STKaiti, KaiTi |

## 3D Rendering

Uses WebGL 1.0 with no external 3D library. Custom vertex and fragment shaders:

- Two-directional lighting (key light 72% + fill light 18%) + rim lighting
- Ambient light baseline 0.42
- Skeleton mesh rendered in dark teal (#234A4F)
- Relief mesh colored by thickness: light green at thin areas, dark green at thick areas
- Perspective projection 36-degree FOV, near plane 1 / far plane 1600
- Depth testing + back-face culling
- High-DPI support (DPR capped at 2)

## Image Privacy

All image processing happens locally in the browser. Image data never leaves the device. The page runs fully offline after initial load (no network connection required).

## Technology Stack

- HTML5 + CSS3 (Grid layout, CSS variables, backdrop-filter)
- Vanilla JavaScript (no frameworks, no build tools, no external dependencies)
- WebGL 1.0 (custom shaders)
- Canvas 2D API (fan surface editor)
- File API / Blob API (file reading and export)
- Responsive design (1200px / 900px / 640px breakpoints)

## Usage

Open `index.html` directly in a browser. Chrome or Edge is recommended for the best WebGL performance.

Workflow:

1. Select a fan type (A / B / C)
2. Choose image mode (whole-fan single image / per-blade individual images)
3. Upload an image or use the built-in demo
4. Adjust image composition (scale, position, rotation)
5. Use the editor to add brush strokes, text, or shapes (optional)
6. Adjust lithophane relief parameters (thickness, contrast, gamma, etc.)
7. Verify the result in the 3D preview
8. Select precision and export STL or 3MF