Translucent_Relief/README.md

# DreamLife-Translucent_Relief

一款纯浏览器端的图片转 3D 打印透光浮雕折扇模型工具。用户上传图片后，可在线编辑扇面、调整透光浮雕参数，最终导出 STL 或 3MF 文件用于 3D 打印。全部计算在本地完成，图片不上传任何服务器。

<div align="center">
<br>

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

<br>
</div>

## 功能概览

- **图片转透光浮雕**：将照片亮度映射为扇叶厚度，打印后背光可呈现原图
- **三套扇形骨架**：大型甲（圆弧扇头）、大型乙（折线圆头，默认）、大型丙（花瓣尖头）
- **扇叶配图模式**：整扇共用一张图，或 11 片扇叶逐片独立配图
- **2D 扇面编辑器**：画笔、橡皮、文字（14 款中文字体、弧形排布）、9 种矢量图形工具
- **实时 3D 预览**：自研 WebGL 渲染管线，按厚度映射颜色，支持拖动旋转和滚轮缩放
- **多格式导出**：STL（二进制）和 3MF（含 ZIP 压缩），5 档网格精度，3 种 3MF 拆分方式

## 项目结构

```
Translucent_Relief/
├── index.html                  HTML 主文件（三栏布局 + 外部引用）
├── README.md                   本文档
├── CSS/
│   ├── variables.css           设计令牌（颜色、圆角、阴影）
│   ├── base.css                全局重置、body、滚动条、输入元素
│   ├── layout.css              顶栏、三栏网格布局、品牌头部（含 Pacifico @font-face）
│   ├── components.css          扇形选择、扇叶面板、拖拽区、文件标签
│   ├── editor.css              2D 画布、画笔光标、浮动工具栏
│   ├── controls.css            滑块、开关、字体选择器、颜色选择器
│   ├── export.css              导出按钮、转轴下载、状态栏
│   ├── stage.css               3D 预览舞台、加载动画
│   └── responsive.css          媒体查询（1200px / 900px / 640px）
├── JavaScript/
│   ├── config.js               状态对象、常量、扇形定义、Base64 STL 骨架数据
│   ├── geometry.js             STL 解析、网格焊接、三角化、点在多边形测试
│   ├── image.js                图片加载、亮度采样、示例图生成
│   ├── canvas_editor.js        2D 画布编辑器全部逻辑（画笔/文字/图形/选择/撤销）
│   ├── export.js               STL/3MF 导出、ZIP 压缩、CRC32、网格构建
│   ├── webgl.js                WebGL 初始化、着色器、渲染循环
│   ├── ui.js                   事件绑定、UI 更新、交互控制
│   └── initialize.js           初始化函数及启动调用
└── pacifico/
    └── Pacifico.ttf            品牌标题字体
```

### JS 加载顺序

文件之间存在全局作用域依赖，必须按以下顺序加载：

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

`config.js` 定义全局的 `state`、`ui`、`FAN`、`DETAIL` 等变量，后续文件引用这些变量。`initialize.js` 末尾调用 `initialize()` 启动应用。

## 三栏布局

| 区域 | 宽度 | 内容 |
|------|------|------|
| 左栏 - 工具与编辑 | 300px | 扇形选择、图片上传、2D 扇面编辑器、构图控制 |
| 中栏 - 3D 预览 | 自适应 | WebGL 实时预览画布、视图控制、模型信息 |
| 右栏 - 参数与导出 | 300px | 透光浮雕参数、打印输出设置、STL/3MF 导出 |

顶栏（44px）左侧显示 Pacifico 字体的 DreamLife 品牌名，右侧显示"浏览器本地处理"状态标识。

## 扇形骨架

三种扇形各有独立的轮廓几何和 STL 骨架模板（以 Base64 内嵌在 `config.js` 中）：

| 名称 | 标识 | 扇头形状 | 包围尺寸（mm） |
|------|------|----------|---------------|
| 大型甲 | 甲 | 圆弧扇头 | 242 × 410 |
| 大型乙 | 乙 | 折线圆头 | 232 × 387 |
| 大型丙 | 丙 | 花瓣尖头 | 235 × 383 |

默认使用大型乙，11 片扇叶，展开角度 140 度。扇叶间距固定 14 度。

## 编辑器工具

### 基础工具

| 工具 | 说明 |
|------|------|
| 移动 | 拖动图片位置，滚轮缩放（默认激活） |
| 选择 | 选中并移动文字或几何图形对象 |
| 画笔 | 自由手绘，笔粗 2-60px |
| 橡皮 | 擦除手绘笔迹和文字 |
| 文字 | 放置文字，支持弧形排布 |

### 矢量图形

直线、圆形、方形、三角形、多边形（3-10 边）、星形、菱形、箭头、样条曲线（平滑度 0-100%）。

几何图形支持"正图形（等比例）"和"自由比例"两种模式。

### 文字字体

14 款中文艺术字体：黑体、雅宋、楷书、行楷（默认）、隶书、圆体、舒体、琥珀、新魏、彩云、姚体、中宋、仿宋、细黑。字体来自本机系统，缺失时自动回退。

支持实心填充和空心描边两种字形样式，字号 12-360px，弧度 -100% 至 100%。

## 透光浮雕参数

| 参数 | 范围 | 默认值 | 说明 |
|------|------|--------|------|
| 最薄处 | 0.35-1.20mm | 0.60mm | 最薄处透光厚度 |
| 最厚处 | 1.10-3.20mm | 2.20mm | 最厚处暗部厚度 |
| 边缘留量 | 0.00-1.80mm | 0.00mm | 浮雕与骨架边缘的距离 |
| 图像对比 | 60-190% | 135% | 图像对比度调整 |
| 暗部层次 | 0.55-2.20 | 0.95 | Gamma 校正，影响暗部细节 |
| 柔化噪点 | 0-4px | 0.5px | 高斯模糊柔化噪点 |
| 反相 | 开/关 | 关 | 适合底片或线稿 |

## 导出

### 格式

| 格式 | 说明 |
|------|------|
| STL | 二进制格式，80 字节文件头，50 字节/三角形 |
| 3MF | 标准规范，含 ZIP stored 压缩、CRC32 校验、顶点去重 |

### 网格精度

| 精度 | 采样网格 | 说明 |
|------|----------|------|
| 快速预览 | 72 × 14 | 草稿级 |
| 标准打印 | 144 × 28 | 常规打印 |
| 高精度打印 | 240 × 48 | 高质量 |
| 极致精度 | 320 × 64 | 推荐 |
| 参考作品级 | 512 × 96 | 约 219 万面 |

### 3MF 拆分方式

- **整扇单一对象**：焊接为 1 个完整网格，适合直接切片（默认）
- **总成内可拆零件**：1 个总成对象包含 N 个组件引用
- **独立对象**：每个网格作为独立的构建对象

转轴不包含在导出文件中，需单独从 MakerWorld 下载配套零件。

## 设计系统

### 配色

浅色系，以微软 Fluent 设计为参考：

| 用途 | 颜色 |
|------|------|
| 页面背景 | #f3f4f6 |
| 面板背景 | #ffffff |
| 主文字 | #1a1d23 |
| 次文字 | #5a5f6a |
| 强调蓝 | #0078d4 |
| 警告红 | #d13438 |
| 成功绿 | #107c10 |

### 字体

| 用途 | 字体 |
|------|------|
| 正文 | Segoe UI, Microsoft YaHei UI, system-ui |
| 品牌标题 | Pacifico |
| 等宽（数据/标签） | Cascadia Code, Consolas |
| 印章/扇形名 | STKaiti, KaiTi |

## 3D 渲染

使用 WebGL 1.0，无外部 3D 库依赖。自研顶点和片段着色器：

- 两方向光照（主光 72% + 补光 18%）+ 边缘光
- 环境光基线 0.42
- 骨架网格渲染为深青色（#234A4F）
- 浮雕网格按厚度映射颜色：薄处浅绿、厚处深绿
- 透视投影 36 度 FOV，近裁 1 / 远裁 1600
- 深度测试 + 背面剔除
- 支持高 DPI 屏幕（DPR 上限 2）

## 图片隐私

所有图片处理在浏览器本地完成，图片数据不离开设备。页面可完全离线运行（首次加载后无需网络）。

## 技术栈

- HTML5 + CSS3（Grid 布局、CSS 变量、backdrop-filter）
- 原生 JavaScript（无框架、无构建工具、无外部依赖）
- WebGL 1.0（自写着色器）
- Canvas 2D API（扇面编辑器）
- File API / Blob API（文件读取和导出）
- 响应式设计（1200px / 900px / 640px 断点）

## 使用方式

直接在浏览器中打开 `index.html` 即可使用。推荐使用 Chrome 或 Edge 浏览器以获得最佳 WebGL 性能。

操作流程：

1. 选择扇形（甲/乙/丙）
2. 选择图片模式（整扇一张图 / 单片独立图）
3. 上传图片或使用内置示例
4. 调整图片构图（缩放、移动、旋转）
5. 使用编辑器添加画笔、文字或图形（可选）
6. 调整透光浮雕参数（厚度、对比度、层次等）
7. 在 3D 预览中确认效果
8. 选择精度并导出 STL 或 3MF