# 技术设计：Cesium 材质导出契约化

> 对应 `prd.md`。本文件定义边界、数据流、兼容策略和风险控制。

---

## 1. 当前边界

`catalog.py` 是纯 Python 层，只声明材质事实，不能 import `bpy`。`materials.py`
属于 bpy 层，负责把 catalog spec 变成真实 `bpy.types.Material`。`export_cesium.py`
打开 `.blend` 后只应消费场景里已有的材质信息。

因此正确边界是：

```
catalog.MATERIALS[*]["cesium"]      # 纯数据
        │
        ▼
materials.from_spec()               # bpy 层写 material["cesium_export"]
        │
        ▼
<area>.blend                         # 契约随场景文件保存
        │
        ▼
export_cesium.py                     # 优先读 material custom property
```

不采用：

```
export_cesium.py -> import catalog -> 按 material.name 反查
```

原因：这仍然依赖材质名字符串，而且旧 `.blend` 应该能在没有新 catalog contract 的情况下导出。

## 2. Contract Shape

材质自定义属性名固定为：

```python
CESIUM_EXPORT_PROPERTY = "cesium_export"
```

JSON payload 建议 shape：

```json
{
  "tint": [[0.92, 0.94, 0.92], 0.38],
  "metallic": 0.0,
  "base_color": [0.93, 0.94, 0.91],
  "emission": [[0.93, 0.94, 0.91], 0.18]
}
```

字段语义：

| 字段 | 类型 | 语义 | 旧来源 |
|---|---|---|---|
| `tint` | `[[r,g,b], factor]` | diffuse 贴图导出前往目标颜色混合 | `EXPORT_TINTS` |
| `metallic` | number | 覆盖导出 PBR metallic | `EXPORT_METALLIC_OVERRIDES` |
| `base_color` | `[r,g,b]` | 直接覆盖导出材质 base color，并禁用 diffuse/normal 图 | `EXPORT_BASE_COLOR_OVERRIDES` |
| `emission` | `[[r,g,b], strength]` | 设置导出材质自发光 | `EXPORT_EMISSION_OVERRIDES` |

缺失字段表示沿用源材质当前值或当前特殊路径。

## 3. Catalog Migration

把四张旧表中的有效条目迁入 `catalog.MATERIALS` 对应项：

- `Grass` -> `MATERIALS["grass"]["cesium"]`
- `Scrub Ground Cover` -> `MATERIALS["scrub"]["cesium"]`
- `Tree Crown*` -> 现有 `tree_crown*["cesium"]` 扩展到完整字段
- `Office White Plaster Facade` -> `building_default`
- `Office Light Flat Roof` -> `building_office_roof`
- `Industrial White Ribbed Facade` -> `building_industrial`
- `Factory Blue Metal Roof` -> `building_industrial_roof`

`Office White Metal Facade` 当前没有 catalog 材质，不迁入新契约。旧表可保留该 key 作为旧
`.blend` 回退兼容。

`catalog.CESIUM_EXPORT` 应消失或变成真实消费路径。优先方案：删除全局 `CESIUM_EXPORT`，
把其中仍有效的内容迁入各自 `MATERIALS[*]["cesium"]`。

## 4. Material Construction

在 `materials.py`：

1. import `json`
2. 定义同名常量 `CESIUM_EXPORT_PROPERTY = "cesium_export"`，或一个私有 helper
3. `from_spec(spec)` 构造材质后调用：

```python
def apply_cesium_contract(material, spec):
    contract = spec.get("cesium")
    if contract is None:
        material.pop(CESIUM_EXPORT_PROPERTY, None)
        return
    material[CESIUM_EXPORT_PROPERTY] = json.dumps(contract, sort_keys=True)
```

注意：

- `sort_keys=True` 让 `.blend` 摘要更稳定。
- 没有 `cesium` 的材质应清掉旧属性，避免同名材质复用时残留。
- `catalog.py` 仍不 import `bpy`。

## 5. Export Consumption

在 `export_cesium.py`：

1. 增加 `cesium_contract(material)`，读取并 `json.loads(material.get("cesium_export", "{}"))`
2. JSON 解析失败时返回 `{}` 并继续旧回退，避免坏旧文件直接崩溃
3. `make_export_material(material)` 开头读取一次 contract：

```python
contract = cesium_contract(material)
```

4. 每个覆盖点改成 “contract 优先，旧表回退”：

```python
base_color = contract.get("base_color", EXPORT_BASE_COLOR_OVERRIDES.get(material.name, source_color(material)))
metallic = contract.get("metallic", EXPORT_METALLIC_OVERRIDES.get(...))
emission = contract.get("emission", EXPORT_EMISSION_OVERRIDES.get(material.name))
tint = contract.get("tint", EXPORT_TINTS.get(material.name))
```

5. `cesium_tinted_image()` 可以改为接收 `tint` 参数，避免函数内部再查旧表。

## 6. Foliage Special Case

Alpha cut-out foliage 不在本次 contract 化范围内，原因是它不只是普通材质覆盖，还包含：

- `source_alpha_clipped(material)`
- `alpha_dilated_image(..., gain=FOLIAGE_ALBEDO_GAIN, saturation=FOLIAGE_SATURATION)`
- diffuse texture 连接到 emission color
- `FOLIAGE_EMISSION`

这些逻辑保持原样。普通 contract 的 `emission` 只处理非 alpha-clipped 或程序化材质的平铺
emission override；alpha-clipped 分支仍使用 diffuse-as-emissive texture。

## 7. Validation Strategy

快速检查：

```bash
python3 -m unittest discover blender/tests
```

结构验证：

```bash
node scripts/parity.js capture material-contract-before
node scripts/parity.js capture material-contract-after
node scripts/parity.js compare material-contract-before material-contract-after
```

如果 before capture 已存在于实现前，after 在实现后跑。若 compare 报差异：

- `.blend` 摘要多出材质自定义属性 `cesium_export` 是预期差异，但需要确认没有对象、网格、
  材质槽顺序、GLB material PBR 参数等非预期变化。
- GLB 摘要应尽量全绿；若发生 PBR 参数变化，优先修实现而不是接受差异。

## 8. Rollback

回滚点明确：

- `catalog.py` 还原 `MATERIALS["cesium"]` 迁移和 `CESIUM_EXPORT` 处理。
- `materials.py` 删除 custom property 写入。
- `export_cesium.py` 恢复旧四张表直接读取。
- spec 更新随代码回滚。