# relievo

## 算法流程

### 深度图生成

`depth_map.go` 将输入图片转换为 STL 前的灰度深度图，核心步骤如下：

1. 将图片转为亮度灰度图，低于背景阈值的暗部会被裁成 `0`。
2. 将图片缩放到最大 `320px`，控制后续 STL 网格规模。
3. 使用轻微模糊得到主体灰度，再叠加拉普拉斯细节增强，保留边缘和局部纹理。
4. 按 `2% - 98%` 分位数归一化灰度，减少极端亮暗点对整体高度范围的影响。
5. 应用 gamma 曲线和顶部平齐曲线，让高亮区域更容易形成可打印的连续顶面。
6. 如果启用反转，则最后反转灰度。

圆盘模式不会根据主体自动偏移；它默认以用户传入图片的中心为中心，居中裁成正方形后再生成圆形遮罩。这样用户可以通过原图构图直接控制圆盘中的位置。

圆盘带圆环时，深度图只会为圆环预留区域；圆环本身在 STL 阶段作为几何结构生成，不依赖图片灰度。

### STL 生成

`stl.go` 将深度图转换为二进制 STL，核心步骤如下：

1. 根据模型尺寸、0.4mm 喷嘴和三角面预算计算采样步长。
2. 对较大模型做轻微喷嘴级平滑，小模型保留更密采样。
3. 将灰度深度采样为高度场，并按 `layer_height` 做 Z 向量化。
4. 使用 `relief_contrast_percent` 生成统一的 `reliefProfile`，集中控制有效高度、深度曲线、高区压缩和平顶阈值。
5. 方形模型生成顶面、底面和四周侧壁。
6. 圆盘模型使用极坐标网格生成顶面、底面和圆形侧壁；带圆环时，最外圈高度由几何圆环直接写入。

高度量化会把连续高度吸附到层高网格，例如 `1mm` 浮雕配 `0.2mm` 层高大约只有 5 个可用 Z 层。算法会尽量分配这些层，但不能突破层高带来的物理限制。

## 浮雕参数

### `relief_contrast_percent`

`relief_contrast_percent` 用来控制 STL 生成时的浮雕层次保留程度，取值范围为 `1-100`，默认建议 `85`。

- 值越低，浮雕越浅，中高亮区域会被压缩得更多，整体更接近薄浮雕。
- 值越高，越倾向于保留灰度层次，中高亮区域压缩更少，浮雕起伏更明显。
- 该参数会同时影响有效浮雕高度、深度分布曲线、高区压缩和平顶触发位置。

推荐值：

- `60-75`：更薄、更平，适合希望整体起伏收敛的模型。
- `80-90`：默认推荐区间，适合 0.4mm 喷嘴和常见层高。
- `90-100`：细节优先，适合小尺寸、浅浮雕、人脸或需要尽量展示更多层次的图案。

注意：这个参数不能突破打印层高本身的限制。比如 `1mm` 浮雕高度下：

- `0.2mm` 层高大约只有 5 个可用 Z 层，参数变化会有作用，但不会特别细腻。
- `0.12mm` 层高大约有 8 个可用 Z 层，参数效果会更明显，细节过渡也更平滑。

如果目标是尽可能展示细节，优先组合是：

- `model_thickness >= 1mm`
- `layer_height = 0.12mm`
- `relief_contrast_percent = 85-100`

如果使用 `layer_height = 0.2mm` 且 `model_thickness = 1mm`，建议把 `relief_contrast_percent` 设为 `90-100`，尽量把有限的 5 个高度层用满。