# ModelTranslator 减面与烘焙工具实现计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在 `Tools/ModelTranslator` 新增两个 headless Blender 工具——FBX 减面到指定三角面数（含 Smart UV 重展），以及高低模烘焙分离出 normal/ao/color/metallic/roughness 五张贴图。

**Architecture:** 沿用现有"系统 Python CLI 包装器 + `blender -b --factory-startup --python bl_*.py` + stdout `MT_SUMMARY ` JSON 行协议"模式。纯逻辑函数放模块顶部（不 import bpy，可单测），Blender 专属代码全部延迟导入 bpy。烘焙用 Cycles selected-to-active：NORMAL/AO pass 直接烘，color/metallic/roughness 用 EMIT trick（把 Principled 对应输入改接 Emission）。

**Tech Stack:** Python 3 标准库、Blender 5.0（bpy）、unittest。

**设计文档:** `docs/superpowers/specs/2026-07-16-model-decimate-bake-design.md`

**重要提醒:**
- 仓库路径含 `#`（`D:\UD\AI\AIC#Project`），**bash 里所有路径必须加引号**
- Blender 位于 `D:\tools\blender-5.0.0-windows-x64\blender.exe`（`find_blender` 的默认值）
- 测试素材：`Tools/ModelTranslator/src/well1500.fbx`（高模），目标 5000 面
- `Tools/ModelTranslator/src/` 与产物目录均**不入 git**（现状即未跟踪），只提交代码/文档

## 文件结构

```
Tools/ModelTranslator/
  mt_run.py             # 新增：find_blender + run_blender_script（两个新 CLI 共享）
  model_decimate.py     # 新增：工具1 CLI
  bl_decimate.py        # 新增：工具1 Blender 内脚本（含可单测纯逻辑）
  model_bake.py         # 新增：工具2 CLI
  bl_bake.py            # 新增：工具2 Blender 内脚本（含可单测纯逻辑）
  tests/
    test_bl_decimate.py # 新增
    test_bl_bake.py     # 新增
  README.md             # 修改：补两个新工具的用法与管线说明
```

（`model_translator.py` 不动，避免破坏已验证的工具3。）

---

### Task 1: mt_run.py 共享 Blender 运行器

**Files:**
- Create: `Tools/ModelTranslator/mt_run.py`

纯 subprocess 薄封装，无业务逻辑，不写单测（与现有 `model_translator.py` 的 `find_blender`/`run_blender` 同模式，仅泛化脚本名与参数）。

- [ ] **Step 1: 写 mt_run.py**

```python
"""find_blender / run_blender_script：model_decimate 与 model_bake 共享的
headless Blender 运行器（与 model_translator.py 同模式，脚本名与参数泛化）。"""
import json
import os
import shutil
import subprocess
import sys

DEFAULT_BLENDER = r"D:\tools\blender-5.0.0-windows-x64\blender.exe"
HERE = os.path.dirname(os.path.abspath(__file__))


def find_blender(cli_arg):
    for cand in (cli_arg, os.environ.get("BLENDER_EXE"), DEFAULT_BLENDER,
                 shutil.which("blender")):
        if cand and os.path.isfile(cand):
            return cand
    sys.exit("找不到 blender.exe，请用 --blender 指定或设置环境变量 BLENDER_EXE")


def run_blender_script(blender, script, script_args):
    """跑 HERE 下的 bl_*.py，返回 MT_SUMMARY JSON；失败或 summary 带 error 则退出。"""
    cmd = [blender, "-b", "--factory-startup",
           "--python", os.path.join(HERE, script), "--"] + list(script_args)
    proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8",
                          errors="replace")
    summary = None
    for line in (proc.stdout or "").splitlines():
        if line.startswith("MT_SUMMARY "):
            summary = json.loads(line[len("MT_SUMMARY "):])
    if proc.returncode != 0 or summary is None or "error" in summary:
        sys.stderr.write((proc.stdout or "")[-2000:] + "\n" +
                         (proc.stderr or "")[-2000:] + "\n")
        err = summary["error"] if summary and "error" in summary else script
        sys.exit("Blender 执行失败：%s" % err)
    return summary
```

- [ ] **Step 2: 语法检查**

Run: `python -m py_compile "D:/UD/AI/AIC#Project/Tools/ModelTranslator/mt_run.py"`
Expected: 无输出（编译通过）

- [ ] **Step 3: Commit**

```bash
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/mt_run.py && git commit -m "ModelTranslator: 共享 Blender 运行器 mt_run.py"
```

---

### Task 2: bl_decimate.py 纯逻辑（TDD）

**Files:**
- Create: `Tools/ModelTranslator/tests/test_bl_decimate.py`
- Create: `Tools/ModelTranslator/bl_decimate.py`（本任务只写纯逻辑部分）

- [ ] **Step 1: 写失败测试**

```python
import os
import sys
import unittest

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
import bl_decimate as bd


class TestDecimateRatio(unittest.TestCase):
    def test_normal_reduction(self):
        self.assertAlmostEqual(bd.decimate_ratio(5000, 1500000), 5000 / 1500000.0)

    def test_current_below_target_returns_one(self):
        self.assertEqual(bd.decimate_ratio(5000, 3000), 1.0)

    def test_current_equal_target_returns_one(self):
        self.assertEqual(bd.decimate_ratio(5000, 5000), 1.0)

    def test_zero_current_returns_one(self):
        self.assertEqual(bd.decimate_ratio(5000, 0), 1.0)


class TestWithinTolerance(unittest.TestCase):
    def test_exact_hit(self):
        self.assertTrue(bd.within_tolerance(5000, 5000))

    def test_within_3_percent(self):
        self.assertTrue(bd.within_tolerance(5000, 5150))   # +3%
        self.assertTrue(bd.within_tolerance(5000, 4850))   # -3%

    def test_outside_3_percent(self):
        self.assertFalse(bd.within_tolerance(5000, 5200))
        self.assertFalse(bd.within_tolerance(5000, 4700))

    def test_zero_target_is_false(self):
        self.assertFalse(bd.within_tolerance(0, 0))


if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: 运行确认失败**

Run: `cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_bl_decimate -v`
Expected: FAIL/ERROR（`No module named 'bl_decimate'`）

- [ ] **Step 3: 写 bl_decimate.py 纯逻辑部分**

```python
"""Blender 内运行：FBX 减面到指定三角面数 + Smart UV 重展。
调用：blender -b --factory-startup --python bl_decimate.py -- <src.fbx> <out.fbx> <target_tris>
"""
import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

TOLERANCE = 0.03    # 面数相对误差容忍
MAX_RETRY = 2       # ratio 修正轮数上限


def decimate_ratio(target, cur):
    """Decimate collapse ratio；cur <= target 或非法时返回 1.0（不减面）。"""
    if cur <= 0 or cur <= target:
        return 1.0
    return target / float(cur)


def within_tolerance(target, actual, tol=TOLERANCE):
    """减面结果是否落在目标 ±tol 内。"""
    if target <= 0:
        return False
    return abs(actual - target) <= target * tol
```

- [ ] **Step 4: 运行确认通过**

Run: `cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_bl_decimate -v`
Expected: 全部 PASS（8 个测试）

- [ ] **Step 5: Commit**

```bash
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_decimate.py Tools/ModelTranslator/tests/test_bl_decimate.py && git commit -m "ModelTranslator: 减面 ratio/容差纯逻辑（TDD）"
```

---

### Task 3: bl_decimate.py Blender 主流程 + model_decimate.py CLI

**Files:**
- Modify: `Tools/ModelTranslator/bl_decimate.py`（追加 Blender 专属部分）
- Create: `Tools/ModelTranslator/model_decimate.py`

Blender ops 无法脱离 Blender 单测，正确性由 Task 4 冒烟测试验证。

- [ ] **Step 1: bl_decimate.py 追加 Blender 主流程**

在纯逻辑之后追加（`join_meshes` 为公开函数，Task 6 的 bl_bake 会复用）：

```python
# ---------------- 以下仅在 Blender 内执行 ----------------


def join_meshes(objs):
    """多 mesh join 成单对象，返回结果对象（bl_bake 复用）。"""
    import bpy
    bpy.ops.object.select_all(action='DESELECT')
    for o in objs:
        o.select_set(True)
    bpy.context.view_layer.objects.active = objs[0]
    if len(objs) > 1:
        bpy.ops.object.join()
    return bpy.context.view_layer.objects.active


def _apply_modifier(obj, mod):
    import bpy
    bpy.context.view_layer.objects.active = obj
    bpy.ops.object.modifier_apply(modifier=mod.name)


def _triangulate(obj):
    mod = obj.modifiers.new("mt_tri", 'TRIANGULATE')
    _apply_modifier(obj, mod)


def _decimate(obj, ratio):
    mod = obj.modifiers.new("mt_dec", 'DECIMATE')
    mod.decimate_type = 'COLLAPSE'
    mod.ratio = ratio
    mod.use_collapse_triangulate = True
    _apply_modifier(obj, mod)


def _smart_unwrap(obj):
    """删旧 UV 层后 Smart UV Project 重展。island_margin 0.002 ≈ 2048 图 4px。"""
    import bpy
    import math
    mesh = obj.data
    while mesh.uv_layers:
        mesh.uv_layers.remove(mesh.uv_layers[0])
    bpy.context.view_layer.objects.active = obj
    bpy.ops.object.mode_set(mode='EDIT')
    bpy.ops.mesh.select_all(action='SELECT')
    bpy.ops.uv.smart_project(angle_limit=math.radians(66.0), island_margin=0.002)
    bpy.ops.object.mode_set(mode='OBJECT')


def main():
    import bpy
    import json
    argv = sys.argv[sys.argv.index("--") + 1:]
    src, out_fbx, target = argv[0], argv[1], int(argv[2])
    warnings = []

    bpy.ops.wm.read_factory_settings(use_empty=True)
    bpy.ops.import_scene.fbx(filepath=src)

    meshes = [o for o in bpy.data.objects if o.type == 'MESH']
    skipped = [o.name for o in bpy.data.objects if o.type != 'MESH']
    if skipped:
        warnings.append("忽略非 mesh 对象：%s（本工具只处理静态网格）" % ", ".join(skipped))
    if not meshes:
        print("MT_SUMMARY " + json.dumps({"error": "FBX 中没有 mesh"}, ensure_ascii=False))
        return
    obj = join_meshes(meshes)

    _triangulate(obj)
    orig = len(obj.data.polygons)
    cur = orig
    if cur <= target:
        warnings.append("当前 %d 面 <= 目标 %d，跳过减面" % (cur, target))
    else:
        # collapse 结果是近似值；未达容差时按新面数修正 ratio 再来，最多 MAX_RETRY 轮
        for _ in range(1 + MAX_RETRY):
            _decimate(obj, decimate_ratio(target, cur))
            _triangulate(obj)  # collapse triangulate 后仍可能残留非三角面
            cur = len(obj.data.polygons)
            if within_tolerance(target, cur) or cur <= target:
                break

    _smart_unwrap(obj)
    out_dir = os.path.dirname(os.path.abspath(out_fbx))
    os.makedirs(out_dir, exist_ok=True)
    bpy.ops.export_scene.fbx(filepath=out_fbx, path_mode='STRIP', embed_textures=False)

    print("MT_SUMMARY " + json.dumps(
        {"src": os.path.basename(src), "fbx": os.path.basename(out_fbx),
         "tris_before": orig, "tris_after": cur, "target": target,
         "warnings": warnings}, ensure_ascii=False))


if __name__ == "__main__" and "--" in sys.argv:
    main()
```

- [ ] **Step 2: 写 model_decimate.py**

```python
"""FBX 减面 CLI：减到指定三角面数并 Smart UV 重展，输出 <名>_low.fbx。
用法：python model_decimate.py src/well1500.fbx --tris 5000 [-o dir] [--blender exe]"""
import argparse
import os

from mt_run import find_blender, run_blender_script


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("input", help="FBX 文件")
    ap.add_argument("--tris", type=int, required=True, help="目标三角面数")
    ap.add_argument("-o", "--out", default=None, help="输出目录（默认源文件同目录）")
    ap.add_argument("--blender", default=None)
    args = ap.parse_args()

    blender = find_blender(args.blender)
    name = os.path.splitext(os.path.basename(args.input))[0]
    outdir = args.out or os.path.dirname(os.path.abspath(args.input))
    out_fbx = os.path.join(outdir, name + "_low.fbx")
    s = run_blender_script(blender, "bl_decimate.py",
                           [args.input, out_fbx, str(args.tris)])
    print("== %s: %d -> %d 面（目标 %d）-> %s" %
          (s["src"], s["tris_before"], s["tris_after"], s["target"], out_fbx))
    for w in s["warnings"]:
        print("  [警告] %s" % w)


if __name__ == "__main__":
    main()
```

- [ ] **Step 3: 语法检查 + 既有测试不回归**

Run: `cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m py_compile bl_decimate.py model_decimate.py && python -m unittest -v`
Expected: 编译通过，全部单测 PASS

- [ ] **Step 4: Commit**

```bash
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_decimate.py Tools/ModelTranslator/model_decimate.py && git commit -m "ModelTranslator: FBX 减面工具 model_decimate（Decimate collapse + Smart UV 重展）"
```

---

### Task 4: 工具1 冒烟测试（well1500 → 5000 面）

**Files:** 无新文件；产出 `Tools/ModelTranslator/src/well1500_low.fbx`（不入 git）

- [ ] **Step 1: 跑减面**

Run: `cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python model_decimate.py src/well1500.fbx --tris 5000`
Expected: 输出形如 `== well1500.fbx: NNNNNN -> ~5000 面（目标 5000）-> ...well1500_low.fbx`，`tris_after` 在 4850~5150 之间（±3%）或 ≤5000

- [ ] **Step 2: 确认产物存在**

Run: `ls -la "D:/UD/AI/AIC#Project/Tools/ModelTranslator/src/well1500_low.fbx"`
Expected: 文件存在且非 0 字节

- [ ] **Step 3: 若面数超差或报错**

按 superpowers:systematic-debugging 排查（常见点：Blender 5.0 `smart_project` 参数名、`modifier_apply` 上下文），修复后重跑 Step 1。**不达标不得进入 Task 5。**

---

### Task 5: bl_bake.py 纯逻辑（TDD）

**Files:**
- Create: `Tools/ModelTranslator/tests/test_bl_bake.py`
- Create: `Tools/ModelTranslator/bl_bake.py`（本任务只写纯逻辑部分）

- [ ] **Step 1: 写失败测试**

```python
import math
import os
import sys
import unittest

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
import bl_bake as bb


class TestEstimateRayDistance(unittest.TestCase):
    def test_two_percent_of_bbox_diagonal(self):
        # 3-4-12 直角箱对角线 = 13
        self.assertAlmostEqual(bb.estimate_ray_distance((3.0, 4.0, 12.0)), 0.26)

    def test_custom_pct(self):
        self.assertAlmostEqual(
            bb.estimate_ray_distance((1.0, 0.0, 0.0), pct=0.5), 0.5)


class TestOutputStem(unittest.TestCase):
    def test_strips_low_suffix(self):
        self.assertEqual(bb.output_stem("well1500_low"), "well1500")

    def test_keeps_name_without_suffix(self):
        self.assertEqual(bb.output_stem("well1500"), "well1500")

    def test_only_strips_trailing_suffix(self):
        self.assertEqual(bb.output_stem("low_poly_low"), "low_poly")


class TestBboxMismatch(unittest.TestCase):
    def test_identical_ok(self):
        self.assertFalse(bb.bbox_mismatch((1.0, 2.0, 3.0), (1.0, 2.0, 3.0)))

    def test_within_10_percent_ok(self):
        self.assertFalse(bb.bbox_mismatch((1.0, 2.0, 3.0), (1.05, 1.9, 3.2)))

    def test_one_axis_exceeds(self):
        self.assertTrue(bb.bbox_mismatch((1.0, 2.0, 3.0), (1.0, 2.0, 3.5)))

    def test_zero_axis_ignored(self):
        # 平面模型某轴为 0，不应误报
        self.assertFalse(bb.bbox_mismatch((1.0, 0.0, 3.0), (1.0, 0.0, 3.0)))


if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: 运行确认失败**

Run: `cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_bl_bake -v`
Expected: FAIL/ERROR（`No module named 'bl_bake'`）

- [ ] **Step 3: 写 bl_bake.py 纯逻辑部分**

```python
"""Blender 内运行：高低模 Cycles 烘焙，低模 UV 上出 normal/ao/color/metallic/roughness。
调用：blender -b --factory-startup --python bl_bake.py -- \
    <high.fbx> <low.fbx> <outdir> <size> <ray_distance|auto> <samples>
"""
import math
import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

DEFAULT_RAY_PCT = 0.02   # 自动射线距离 = 低模包围盒对角线 * 2%
BBOX_TOL = 0.10          # 高低模包围盒尺寸相对差警告阈值

# (输出名, bake type, EMIT 来源的 Principled 输入, 目标图颜色空间)
BAKE_PASSES = [
    ("normal", 'NORMAL', None, 'Non-Color'),
    ("ao", 'AO', None, 'Non-Color'),
    ("color", 'EMIT', 'Base Color', 'sRGB'),
    ("metallic", 'EMIT', 'Metallic', 'Non-Color'),
    ("roughness", 'EMIT', 'Roughness', 'Non-Color'),
]


def estimate_ray_distance(bbox_dims, pct=DEFAULT_RAY_PCT):
    """低模包围盒尺寸 (dx,dy,dz) -> 射线距离 = 对角线长 * pct。"""
    return math.sqrt(sum(d * d for d in bbox_dims)) * pct


def output_stem(low_name):
    """低模名去掉 _low 后缀作为输出前缀（对齐工具3纯网格贴图命名约定）。"""
    return low_name[:-4] if low_name.endswith("_low") else low_name


def bbox_mismatch(high_dims, low_dims, tol=BBOX_TOL):
    """任一轴尺寸相对差超 tol 返回 True；接近 0 的轴忽略（平面模型）。"""
    for h, l in zip(high_dims, low_dims):
        m = max(abs(h), abs(l))
        if m > 1e-9 and abs(h - l) / m > tol:
            return True
    return False
```

- [ ] **Step 4: 运行确认通过**

Run: `cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_bl_bake -v`
Expected: 全部 PASS（9 个测试）

- [ ] **Step 5: Commit**

```bash
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_bake.py Tools/ModelTranslator/tests/test_bl_bake.py && git commit -m "ModelTranslator: 烘焙射线距离/命名/包围盒校验纯逻辑（TDD）"
```

---

### Task 6: bl_bake.py Blender 主流程

**Files:**
- Modify: `Tools/ModelTranslator/bl_bake.py`（追加 Blender 专属部分）

关键点：① NORMAL/AO 先烘（依赖高模原始材质），EMIT 三张后烘（会改写节点图，headless 一次性会话无需还原）；② 烘焙目标图的颜色空间决定 PNG 编码——Cycles 向字节图写入时按图颜色空间转换，color 图建为 sRGB 得到 sRGB 编码 PNG，其余 Non-Color 保持线性原值（对应 well10k 双重 sRGB 教训，Unity 端 sRGB 开关由工具3 `.meta` 控制）。

- [ ] **Step 1: 追加 Blender 主流程**

在纯逻辑之后追加：

```python
# ---------------- 以下仅在 Blender 内执行 ----------------


def _import_fbx_joined(path, warnings):
    """导入 FBX 并把其中所有 mesh join 成单对象；无 mesh 返回 None。"""
    import bpy
    from bl_decimate import join_meshes
    before = set(bpy.data.objects)
    bpy.ops.import_scene.fbx(filepath=path)
    new = [o for o in bpy.data.objects if o not in before]
    meshes = [o for o in new if o.type == 'MESH']
    skipped = [o.name for o in new if o.type != 'MESH']
    if skipped:
        warnings.append("%s：忽略非 mesh 对象 %s"
                        % (os.path.basename(path), ", ".join(skipped)))
    if not meshes:
        return None
    return join_meshes(meshes)


def _setup_bake_target(low, stem):
    """低模换成单一烘焙材质，返回接收烘焙结果的 image 节点。"""
    import bpy
    mat = bpy.data.materials.new(stem)
    mat.use_nodes = True
    node = mat.node_tree.nodes.new('ShaderNodeTexImage')
    mat.node_tree.nodes.active = node
    low.data.materials.clear()
    low.data.materials.append(mat)
    return mat, node


def _high_materials(high):
    return [s.material for s in high.material_slots if s.material]


def _rewire_emit(mat, input_name, warnings):
    """把 Principled 指定输入（连线或常量）改接 Emission 直连输出，供 EMIT 烘焙。"""
    import bpy
    if not mat.use_nodes:
        mat.use_nodes = True
    nt = mat.node_tree
    bsdf = next((n for n in nt.nodes if n.type == 'BSDF_PRINCIPLED'), None)
    out = next((n for n in nt.nodes if n.type == 'OUTPUT_MATERIAL'), None)
    if out is None:
        out = nt.nodes.new('ShaderNodeOutputMaterial')
    emit = nt.nodes.get("mt_emit")
    if emit is None:
        emit = nt.nodes.new('ShaderNodeEmission')
        emit.name = "mt_emit"
    for l in list(emit.inputs['Color'].links):
        nt.links.remove(l)
    if bsdf is None:
        warnings.append("材质 %s 无 Principled BSDF，%s 用 0.5 灰常量"
                        % (mat.name, input_name))
        emit.inputs['Color'].default_value = (0.5, 0.5, 0.5, 1.0)
    else:
        sock = bsdf.inputs[input_name]
        if sock.is_linked:
            nt.links.new(sock.links[0].from_socket, emit.inputs['Color'])
        else:
            v = sock.default_value
            if isinstance(v, float):
                emit.inputs['Color'].default_value = (v, v, v, 1.0)
            else:  # Base Color 是 4 分量
                emit.inputs['Color'].default_value = (v[0], v[1], v[2], 1.0)
    for l in list(out.inputs['Surface'].links):
        nt.links.remove(l)
    nt.links.new(emit.outputs['Emission'], out.inputs['Surface'])


def _bake_pass(low, high, target_node, name, bake_type, size, colorspace,
               ray, samples, outdir, stem):
    """执行一个烘焙 pass 并保存 PNG，返回文件名。"""
    import bpy
    img = bpy.data.images.new("mt_bake_" + name, size, size, alpha=False)
    img.colorspace_settings.name = colorspace
    target_node.image = img

    bpy.ops.object.select_all(action='DESELECT')
    high.select_set(True)
    low.select_set(True)
    bpy.context.view_layer.objects.active = low
    bpy.context.scene.cycles.samples = samples

    kwargs = dict(type=bake_type, use_selected_to_active=True,
                  cage_extrusion=ray, max_ray_distance=ray * 2.0,
                  margin=16, use_clear=True)
    if bake_type == 'NORMAL':
        kwargs["normal_space"] = 'TANGENT'  # OpenGL +Y
    bpy.ops.object.bake(**kwargs)

    path = os.path.abspath(os.path.join(outdir, "%s_%s.png" % (stem, name)))
    img.filepath_raw = path
    img.file_format = 'PNG'
    img.save()
    bpy.data.images.remove(img)
    return os.path.basename(path)


def main():
    import bpy
    import json
    argv = sys.argv[sys.argv.index("--") + 1:]
    high_fbx, low_fbx, outdir = argv[0], argv[1], argv[2]
    size, ray_arg, ao_samples = int(argv[3]), argv[4], int(argv[5])
    warnings = []

    bpy.ops.wm.read_factory_settings(use_empty=True)
    high = _import_fbx_joined(high_fbx, warnings)
    low = _import_fbx_joined(low_fbx, warnings)
    if high is None or low is None:
        print("MT_SUMMARY " + json.dumps(
            {"error": "高模或低模 FBX 中没有 mesh"}, ensure_ascii=False))
        return
    if not low.data.uv_layers:
        print("MT_SUMMARY " + json.dumps(
            {"error": "低模没有 UV 层，请先用 model_decimate.py 生成"},
            ensure_ascii=False))
        return

    high_dims, low_dims = tuple(high.dimensions), tuple(low.dimensions)
    if bbox_mismatch(high_dims, low_dims):
        warnings.append("高低模包围盒尺寸差异超 %d%%：高 %s 低 %s，确认是同一模型且坐标已对齐"
                        % (BBOX_TOL * 100,
                           [round(d, 3) for d in high_dims],
                           [round(d, 3) for d in low_dims]))
    ray = estimate_ray_distance(low_dims) if ray_arg == "auto" else float(ray_arg)

    stem = output_stem(os.path.splitext(os.path.basename(low_fbx))[0])
    os.makedirs(outdir, exist_ok=True)

    scene = bpy.context.scene
    scene.render.engine = 'CYCLES'
    scene.cycles.device = 'CPU'
    bake_mat, target_node = _setup_bake_target(low, stem)

    mats = _high_materials(high)
    outputs = {}
    for name, bake_type, emit_input, colorspace in BAKE_PASSES:
        if emit_input is not None:  # EMIT trick：先改写全部高模材质
            for m in mats:
                _rewire_emit(m, emit_input, warnings)
        samples = ao_samples if bake_type == 'AO' else 1
        outputs[name] = _bake_pass(low, high, target_node, name, bake_type,
                                   size, colorspace, ray, samples, outdir, stem)

    # 导出低模：剥掉烘焙 image 节点，材质名保留 stem（工具3 兜底识别用）
    bake_mat.node_tree.nodes.remove(target_node)
    out_fbx = os.path.join(outdir, stem + ".fbx")
    bpy.ops.object.select_all(action='DESELECT')
    low.select_set(True)
    bpy.ops.export_scene.fbx(filepath=out_fbx, use_selection=True,
                             path_mode='STRIP', embed_textures=False)

    print("MT_SUMMARY " + json.dumps(
        {"stem": stem, "fbx": os.path.basename(out_fbx), "outputs": outputs,
         "size": size, "ray_distance": round(ray, 6),
         "high_tris": len(high.data.polygons), "low_tris": len(low.data.polygons),
         "warnings": warnings}, ensure_ascii=False))


if __name__ == "__main__" and "--" in sys.argv:
    main()
```

- [ ] **Step 2: 语法检查 + 纯逻辑测试不回归**

Run: `cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m py_compile bl_bake.py && python -m unittest tests.test_bl_bake -v`
Expected: 编译通过，9 个测试 PASS

- [ ] **Step 3: Commit**

```bash
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_bake.py && git commit -m "ModelTranslator: 高低模烘焙 Blender 主流程（NORMAL/AO + EMIT trick）"
```

---

### Task 7: model_bake.py CLI

**Files:**
- Create: `Tools/ModelTranslator/model_bake.py`

- [ ] **Step 1: 写 model_bake.py**

```python
"""高低模烘焙 CLI：在低模 UV 上烘出 normal/ao/color/metallic/roughness 五张贴图。
产物命名对齐 model_translator.py 纯网格约定，可直接作为其输入。
用法：python model_bake.py <高模.fbx> <低模.fbx> [-o out_bake] [--size 2048]
     [--ray-distance N] [--samples 64] [--blender exe]"""
import argparse
import os

from bl_bake import output_stem
from mt_run import HERE, find_blender, run_blender_script


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("high", help="高模 FBX（带材质/贴图）")
    ap.add_argument("low", help="低模 FBX（须有 UV，见 model_decimate.py）")
    ap.add_argument("-o", "--out", default=os.path.join(HERE, "out_bake"))
    ap.add_argument("--size", type=int, default=2048, help="烘焙贴图边长")
    ap.add_argument("--ray-distance", type=float, default=None,
                    help="射线距离（场景单位），默认低模包围盒对角线 2%%")
    ap.add_argument("--samples", type=int, default=64, help="AO 采样数")
    ap.add_argument("--blender", default=None)
    args = ap.parse_args()

    blender = find_blender(args.blender)
    stem = output_stem(os.path.splitext(os.path.basename(args.low))[0])
    outdir = os.path.join(args.out, stem)
    ray = "auto" if args.ray_distance is None else str(args.ray_distance)
    s = run_blender_script(blender, "bl_bake.py",
                           [args.high, args.low, outdir, str(args.size),
                            ray, str(args.samples)])
    print("== %s（高 %d 面 / 低 %d 面，射线距离 %.4f）-> %s" %
          (s["stem"], s["high_tris"], s["low_tris"], s["ray_distance"], outdir))
    for name, fname in s["outputs"].items():
        print("  %-10s %s" % (name, fname))
    for w in s["warnings"]:
        print("  [警告] %s" % w)


if __name__ == "__main__":
    main()
```

- [ ] **Step 2: 语法检查 + 全部单测**

Run: `cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m py_compile model_bake.py && python -m unittest -v`
Expected: 编译通过，全部单测 PASS

- [ ] **Step 3: Commit**

```bash
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/model_bake.py && git commit -m "ModelTranslator: 烘焙工具 CLI model_bake.py"
```

---

### Task 8: 工具2 冒烟测试（well1500 高模 + well1500_low 低模）

**Files:** 无新文件；产出 `Tools/ModelTranslator/out_bake/well1500/`（不入 git）

- [ ] **Step 1: 跑烘焙**

Run: `cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python model_bake.py src/well1500.fbx src/well1500_low.fbx`
Expected: 打印 5 行输出贴图名，无 error 退出（高面数模型 CPU 烘焙可能要几分钟，Bash timeout 给到 600000）

- [ ] **Step 2: 校验产物：fbx + 5 张 2048 PNG**

Run:
```bash
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator/out_bake/well1500" && ls && python -c "
import struct, glob
for p in sorted(glob.glob('*.png')):
    w, h = struct.unpack('>II', open(p, 'rb').read(24)[16:24])
    print(p, w, h)"
```
Expected: `well1500.fbx` 存在；`well1500_color/normal/metallic/roughness/ao.png` 五张均为 `2048 2048`

- [ ] **Step 3: 抽查烘焙内容非空**

Run:
```bash
cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && "D:/tools/blender-5.0.0-windows-x64/blender.exe" -b --factory-startup --python-expr "
import bpy
for n in ('color', 'normal'):
    img = bpy.data.images.load(r'D:\UD\AI\AIC#Project\Tools\ModelTranslator\out_bake\well1500\well1500_%s.png' % n)
    px = list(img.pixels[:4000])
    uniq = len(set(round(v, 2) for v in px))
    print('CHECK', n, 'unique=', uniq)
"
```
Expected: 两张图 `unique=` 都明显 >1（纯黑/纯灰说明烘焙落空——射线距离或 selected-to-active 出了问题，按 systematic-debugging 排查后重跑）

---

### Task 9: 全管线验证 + README 更新

**Files:**
- Modify: `Tools/ModelTranslator/README.md`

- [ ] **Step 1: 工具3 吃工具2 产物**

Run: `cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python model_translator.py out_bake/well1500/well1500.fbx`
Expected: 输出 `out/well1500/`，日志显示 color/normal/metallic/roughness/ao 五个来源均识别到（无"(常量)"），生成 base/mix PNG + .mat + .meta

- [ ] **Step 2: README 补两个新工具**

在 README.md「用法」小节后新增一节（保持现有行文风格）：

```markdown
## 减面与高低模烘焙（可选前置工具）

高面数模型先减面、再把细节烘到低模贴图，产物直接作为上面转换器的输入：

​```bash
cd Tools/ModelTranslator
python model_decimate.py src/well1500.fbx --tris 5000        # -> src/well1500_low.fbx
python model_bake.py src/well1500.fbx src/well1500_low.fbx   # -> out_bake/well1500/
python model_translator.py out_bake/well1500/well1500.fbx    # -> out/well1500/（Unity 资源）
​```

- **model_decimate.py**：多 mesh 自动 join；三角化后 Decimate(collapse) 减到 `--tris`（±3%，最多 2 轮修正）；旧 UV 全删，Smart UV Project 重展；输出 `<名>_low.fbx`（`-o` 改目录）
- **model_bake.py**：Cycles selected-to-active 烘焙。normal（切线空间 OpenGL +Y）/ao 直接烘；color/metallic/roughness 把高模 Principled 对应输入接 Emission 烘 EMIT。`--size` 默认 2048，`--samples` AO 采样默认 64，射线距离默认低模包围盒对角线 2%（`--ray-distance` 覆盖）；低模无 UV 会报错，高低模包围盒差超 10% 打警告
- 输出命名 `<名>_color/normal/metallic/roughness/ao.png`，正好命中转换器的纯网格贴图命名约定
```

（注意：示例中的 ``` 围栏按 README 实际格式写，上面的 ​``` 仅为本计划文档转义。）

- [ ] **Step 3: 全部单测最后过一遍**

Run: `cd "D:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest -v`
Expected: 全部 PASS

- [ ] **Step 4: Commit**

```bash
cd "D:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/README.md && git commit -m "ModelTranslator: README 补减面/烘焙工具用法（well1500 全管线冒烟通过）"
```

- [ ] **Step 5: Unity 手动验证（用户操作）**

把 `out/well1500/` 拷入 `Client/Assets/`，拖进场景确认外观正常（法线/颜色/粗糙度无明显异常、无双重 gamma 变亮）。此步由用户在 Unity 编辑器完成。