# Quad Remesher 减面后端 Implementation Plan

> **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:** 给 `model_decimate.py` 加可选减面后端 `--reducer collapse|quad`，`quad` 用 Quad Remesher 出规整四边拓扑，失败自动回退 collapse，默认行为零变化。

**Architecture:** 新增纯模块 `qr_bridge.py`（引擎发现/面数换算/settings 生成/progress 解析，可 TDD）；`bl_decimate.py` 加 `_remesh_quad()` 在 headless 直接跑 `xremesh.exe` 子进程（绕开后台不可用的 modal 操作符），`main()` 按 `reducer` 分流；`model_decimate.py` 加 CLI 开关透传。

**Tech Stack:** Python 3 标准库、Blender 5.0 `bpy`、`unittest`、现有 headless Blender runner（`mt_run.py`）。

设计依据：`docs/superpowers/specs/2026-07-22-quadremesher-decimate-backend-design.md`

## Global Constraints

- 不加外部依赖。
- 不覆盖输入 FBX；重拓扑数据只进生成的 `_low.fbx`。
- `--reducer` 默认 `collapse`，现有 CLI/输出/collapse 路径行为零变化。
- QR 任何失败（引擎缺失/超时/负值/空输出/导回无 mesh）记 warning 并回退 collapse，绝不中断。
- 面数：`target_quads = tris // 2`，接受近似，不做二次 collapse。
- 不 stage `Tools/ModelTranslator/src`、bake 产物、Unity 资源等脏工作区文件；只提交本计划涉及的源码/文档。
- Blender 路径：本机在 `D:\tools\Blender\blender-5.0.0-windows-x64\blender.exe`，真机验证用 `--blender` 显式传或设 `BLENDER_EXE`。

## File Map

- Create `Tools/ModelTranslator/qr_bridge.py`：QR 桥纯逻辑，不 import bpy。
- Create `Tools/ModelTranslator/tests/test_qr_bridge.py`：纯函数单测。
- Modify `Tools/ModelTranslator/bl_decimate.py`：加 `_remesh_quad()` 与 `main()` 分流、`MT_SUMMARY.reducer`。
- Modify `Tools/ModelTranslator/model_decimate.py`：加 `--reducer`，透传并打印后端。
- Modify `Tools/ModelTranslator/README.md`：记录 `--reducer` 与回退语义。

---

### Task 1: QR 桥纯逻辑模块

**Files:**
- Create: `Tools/ModelTranslator/qr_bridge.py`
- Create: `Tools/ModelTranslator/tests/test_qr_bridge.py`

**Interfaces:**
- `find_qr_engine() -> str | None`
- `tris_to_target_quads(tris) -> int`
- `build_settings(in_fbx, out_fbx, prog, target_quads, *, adaptive=50, exact=False, hard_edges=True) -> str`
- `parse_progress(text) -> (state, msg)`，`state ∈ {"running","success","error"}`
- 常量 `QR_TIMEOUT`

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

Create `Tools/ModelTranslator/tests/test_qr_bridge.py`：

```python
import os
import sys
import tempfile
import unittest

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
import qr_bridge as qb


class TestTrisToTargetQuads(unittest.TestCase):
    def test_half(self):
        self.assertEqual(qb.tris_to_target_quads(10000), 5000)

    def test_odd_floors(self):
        self.assertEqual(qb.tris_to_target_quads(3), 1)

    def test_at_least_one(self):
        self.assertEqual(qb.tris_to_target_quads(1), 1)
        self.assertEqual(qb.tris_to_target_quads(0), 1)


class TestBuildSettings(unittest.TestCase):
    def _s(self, **kw):
        return qb.build_settings("/i.fbx", "/o.fbx", "/p.txt", 500, **kw)

    def test_core_lines_present(self):
        s = self._s()
        self.assertIn('FileIn="/i.fbx"', s)
        self.assertIn('FileOut="/o.fbx"', s)
        self.assertIn('ProgressFile="/p.txt"', s)
        self.assertIn("TargetQuadCount=500", s)
        self.assertIn("HostApp=Blender", s)
        self.assertTrue(s.endswith("\n"))

    def test_hard_edges_toggle(self):
        self.assertIn("AutoDetectHardEdges=1", self._s(hard_edges=True))
        self.assertIn("AutoDetectHardEdges=0", self._s(hard_edges=False))

    def test_exact_toggle(self):
        self.assertIn("ExactQuadCount=0", self._s(exact=False))
        self.assertIn("ExactQuadCount=1", self._s(exact=True))


class TestParseProgress(unittest.TestCase):
    def test_success(self):
        self.assertEqual(qb.parse_progress("2\n"), ("success", ""))

    def test_error_with_text(self):
        self.assertEqual(qb.parse_progress("-3\n重拓扑失败"), ("error", "重拓扑失败"))

    def test_error_no_text(self):
        self.assertEqual(qb.parse_progress("-3"), ("error", ""))

    def test_running_fraction(self):
        self.assertEqual(qb.parse_progress("0.5"), ("running", ""))

    def test_running_empty(self):
        self.assertEqual(qb.parse_progress(""), ("running", ""))

    def test_running_garbage(self):
        self.assertEqual(qb.parse_progress("abc"), ("running", ""))


class TestFindQrEngine(unittest.TestCase):
    def setUp(self):
        self._env = dict(os.environ)

    def tearDown(self):
        os.environ.clear()
        os.environ.update(self._env)

    def test_env_var_priority(self):
        with tempfile.NamedTemporaryFile(suffix=".exe", delete=False) as f:
            path = f.name
        try:
            os.environ["QR_ENGINE"] = path
            self.assertEqual(qb.find_qr_engine(), path)
        finally:
            os.remove(path)

    def test_missing_returns_none(self):
        os.environ["QR_ENGINE"] = os.path.join(tempfile.gettempdir(), "nope_xremesh.exe")
        os.environ["APPDATA"] = tempfile.mkdtemp()
        self.assertIsNone(qb.find_qr_engine())


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

- [ ] **Step 2: 跑测试确认 RED**

Run（在 `Tools/ModelTranslator`）：

```bash
python -m unittest tests.test_qr_bridge -v
```

Expected: `ModuleNotFoundError: No module named 'qr_bridge'`。

- [ ] **Step 3: 实现 `qr_bridge.py`**

Create `Tools/ModelTranslator/qr_bridge.py`：

```python
"""QR 桥纯逻辑：引擎发现、面数换算、settings 生成、progress 解析。不 import bpy。
减面可选后端 Quad Remesher 用——headless 直接调 Engine/xremesh.exe，绕开 modal 操作符。"""
import glob
import os

QR_TIMEOUT = 120.0   # 引擎轮询超时（秒）


def find_qr_engine():
    """定位 QuadRemesher 的 xremesh.exe；找不到返回 None。
    顺序：QR_ENGINE 环境变量 -> 标准 addon 路径（取最高 Blender 版本目录）。"""
    env = os.environ.get("QR_ENGINE")
    if env and os.path.isfile(env):
        return env
    appdata = os.environ.get("APPDATA")
    if not appdata:
        return None
    pattern = os.path.join(
        appdata, "Blender Foundation", "Blender", "*",
        "scripts", "addons", "QuadRemesher", "Engine", "xremesh.exe")
    hits = sorted(glob.glob(pattern))
    return hits[-1] if hits else None


def tris_to_target_quads(tris):
    """三角面数换算 QR 目标四边形数：1 quad ≈ 2 tris，至少 1。"""
    return max(1, int(tris) // 2)


def build_settings(in_fbx, out_fbx, prog, target_quads,
                   adaptive=50, exact=False, hard_edges=True):
    """生成 RetopoSettings.txt 文本（xremesh.exe -s 读取）。"""
    lines = [
        "HostApp=Blender",
        'FileIn="%s"' % in_fbx,
        'FileOut="%s"' % out_fbx,
        'ProgressFile="%s"' % prog,
        "TargetQuadCount=%d" % target_quads,
        "CurvatureAdaptivness=%d" % adaptive,
        "ExactQuadCount=%d" % (1 if exact else 0),
        "UseVertexColorMap=False",
        "UseMaterialIds=0",
        "UseIndexedNormals=0",
        "AutoDetectHardEdges=%d" % (1 if hard_edges else 0),
    ]
    return "\n".join(lines) + "\n"


def parse_progress(text):
    """解析 progress.txt -> (state, msg)。
    首行 '2'=success；<0=error（次行为文本）；空/分数/非法=running。"""
    lines = text.splitlines()
    if not lines:
        return ("running", "")
    try:
        v = float(lines[0])
    except ValueError:
        return ("running", "")
    if v == 2:
        return ("success", "")
    if v < 0:
        return ("error", lines[1] if len(lines) > 1 else "")
    return ("running", "")
```

- [ ] **Step 4: 跑测试确认 GREEN**

Run：

```bash
python -m unittest tests.test_qr_bridge -v
python -m unittest discover -s tests -v
```

Expected: 新测试全过；现有 ModelTranslator 测试全过、零失败。

- [ ] **Step 5: 提交**

```bash
git add -- Tools/ModelTranslator/qr_bridge.py Tools/ModelTranslator/tests/test_qr_bridge.py
git commit -m "ModelTranslator: add QR bridge pure logic"
```

---

### Task 2: `bl_decimate.py` 加 QR 重拓扑与分流

**Files:**
- Modify: `Tools/ModelTranslator/bl_decimate.py`

**Interfaces:**
- Consumes: `qr_bridge.find_qr_engine/tris_to_target_quads/build_settings/parse_progress/QR_TIMEOUT`。
- Produces: `_remesh_quad(obj, target_tris, warnings) -> bool`。
- `main()` 读 argv[5] `reducer`，`MT_SUMMARY` 新增 `reducer` 字段。

> 说明：`_remesh_quad` 依赖 bpy，无法纯单测，由 Task 4 真机 smoke 覆盖；本任务以 `py_compile` 把关语法。

- [ ] **Step 1: 顶部导入 qr_bridge 与轮询常量**

在 `bl_decimate.py` 顶部 `sys.path.insert(...)` 之后加：

```python
import qr_bridge

QR_POLL_INTERVAL = 0.3   # progress.txt 轮询间隔（秒）
```

- [ ] **Step 2: 加 `_remesh_quad`（放在 `_decimate` 之后、`_clean_mesh` 之前的 Blender-only 区）**

在 `bl_decimate.py` 的 `_decimate` 函数之后插入：

```python
def _remesh_quad(obj, target_tris, warnings):
    """Quad Remesher 重拓扑 obj（headless 直调 xremesh.exe，绕开 modal 操作符）。
    成功返回 True，并把导回的 quad 网格设为新 active object（原 obj 已删）；
    任何失败记 warning 返回 False，交上层回退 collapse。"""
    import bpy
    import subprocess
    import tempfile
    import time
    engine = qr_bridge.find_qr_engine()
    if not engine:
        warnings.append("未找到 QuadRemesher 引擎(xremesh.exe)，回退 collapse")
        return False
    work = os.path.join(tempfile.gettempdir(), "mt_qr")
    os.makedirs(work, exist_ok=True)
    in_fbx = os.path.join(work, "inputMesh.fbx").replace("\\", "/")
    out_fbx = os.path.join(work, "retopo.fbx").replace("\\", "/")
    prog = os.path.join(work, "progress.txt").replace("\\", "/")
    settings = os.path.join(work, "RetopoSettings.txt")
    for f in (out_fbx, prog):
        if os.path.isfile(f):
            os.remove(f)
    try:
        bpy.ops.object.select_all(action='DESELECT')
        obj.select_set(True)
        bpy.context.view_layer.objects.active = obj
        bpy.ops.export_scene.fbx(filepath=in_fbx, use_selection=True)
        target_quads = qr_bridge.tris_to_target_quads(target_tris)
        with open(settings, "w") as fp:
            fp.write(qr_bridge.build_settings(in_fbx, out_fbx, prog, target_quads))
        proc = subprocess.Popen([engine, "-s", settings])
    except Exception as e:
        warnings.append("QR 启动失败(%s)，回退 collapse" % e)
        return False

    t0 = time.time()
    state = "running"
    while True:
        try:
            with open(prog) as fp:
                state, msg = qr_bridge.parse_progress(fp.read())
        except IOError:
            state, msg = "running", ""
        if state == "success":
            break
        if state == "error":
            warnings.append("QR 重拓扑失败(%s)，回退 collapse" % msg)
            return False
        if proc.poll() is not None:
            # 进程已退出：给 progress/输出一点落地时间后再判一次
            time.sleep(QR_POLL_INTERVAL)
            try:
                with open(prog) as fp:
                    state, _ = qr_bridge.parse_progress(fp.read())
            except IOError:
                state = "running"
            break
        if time.time() - t0 > qr_bridge.QR_TIMEOUT:
            proc.kill()
            warnings.append("QR 超时(%ds)，回退 collapse" % int(qr_bridge.QR_TIMEOUT))
            return False
        time.sleep(QR_POLL_INTERVAL)

    if state != "success" or not (
            os.path.isfile(out_fbx) and os.path.getsize(out_fbx) > 0):
        warnings.append("QR 无有效输出，回退 collapse")
        return False

    try:
        before = set(bpy.data.objects)
        bpy.ops.import_scene.fbx(filepath=out_fbx)
        new = [o for o in bpy.data.objects
               if o not in before and o.type == 'MESH']
        if not new:
            warnings.append("QR 导回无 mesh，回退 collapse")
            return False
        retopo = new[0]
        bpy.data.objects.remove(obj, do_unlink=True)
        bpy.ops.object.select_all(action='DESELECT')
        retopo.select_set(True)
        bpy.context.view_layer.objects.active = retopo
        return True
    except Exception as e:
        warnings.append("QR 导回失败(%s)，回退 collapse" % e)
        return False
```

- [ ] **Step 3: `main()` 解析 reducer 参数**

在 `main()` 中，把：

```python
    overlap_tol = float(argv[4]) if len(argv) > 4 and argv[4] else UV_OVERLAP_TOL
```

改为（其后新增一行）：

```python
    overlap_tol = float(argv[4]) if len(argv) > 4 and argv[4] else UV_OVERLAP_TOL
    reducer_arg = argv[5] if len(argv) > 5 else "collapse"
```

- [ ] **Step 4: `main()` 按 reducer 分流减面**

把 `main()` 中现有的这段：

```python
    _clean_mesh(obj, warnings)
    _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
        # 重试用尽仍超差且偏多：记录警告，交由上层决定是否可接受
        if not within_tolerance(target, cur) and cur > target:
            warnings.append("修正 %d 轮后仍超差：%d 面（目标 %d ±3%%）" % (MAX_RETRY, cur, target))
```

整体替换为：

```python
    _clean_mesh(obj, warnings)
    _triangulate(obj)
    orig = len(obj.data.polygons)   # 高模三角面数（tris_before）
    cur = orig
    used_reducer = "collapse"
    did_quad = False
    if reducer_arg == "quad":
        if _remesh_quad(obj, target, warnings):
            obj = bpy.context.view_layer.objects.active   # QR 导回的 quad 对象
            _triangulate(obj)                             # 三角化供导出/计数
            cur = len(obj.data.polygons)
            used_reducer = "quad"
            did_quad = True
        else:
            used_reducer = "quad->collapse"
    if not did_quad:
        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
            # 重试用尽仍超差且偏多：记录警告，交由上层决定是否可接受
            if not within_tolerance(target, cur) and cur > target:
                warnings.append("修正 %d 轮后仍超差：%d 面（目标 %d ±3%%）" % (MAX_RETRY, cur, target))
```

- [ ] **Step 5: `MT_SUMMARY` 加 reducer 字段**

把 `main()` 末尾 `print("MT_SUMMARY " + json.dumps(` 里的 dict：

```python
        {"src": os.path.basename(src), "fbx": os.path.basename(out_fbx),
         "tris_before": orig, "tris_after": cur, "target": target,
         "uv": uv_info,
```

改为（加一行 `reducer`）：

```python
        {"src": os.path.basename(src), "fbx": os.path.basename(out_fbx),
         "tris_before": orig, "tris_after": cur, "target": target,
         "reducer": used_reducer,
         "uv": uv_info,
```

- [ ] **Step 6: 编译并跑现有测试**

Run：

```bash
python -m py_compile qr_bridge.py bl_decimate.py
python -m unittest discover -s tests -v
```

Expected: 编译 exit 0；全部测试通过（本任务未改纯函数，回归应全绿）。

- [ ] **Step 7: 提交**

```bash
git add -- Tools/ModelTranslator/bl_decimate.py
git commit -m "ModelTranslator: add QR quad remesh decimate backend with collapse fallback"
```

---

### Task 3: `model_decimate.py` CLI 加 `--reducer`

**Files:**
- Modify: `Tools/ModelTranslator/model_decimate.py`

**Interfaces:**
- 加 `--reducer {collapse,quad}`（默认 `collapse`），透传为 Blender argv 第 6 位（index 5）。
- 打印实际后端。

- [ ] **Step 1: 加 argparse 选项**

在 `model_decimate.py` 的 `main()` 中，`--unwrap` 参数定义之后加：

```python
    ap.add_argument("--reducer", choices=("collapse", "quad"), default="collapse",
                    help="减面后端：collapse=Decimate 塌陷（默认），quad=Quad Remesher 四边重拓扑（失败自动回退 collapse）")
```

- [ ] **Step 2: 透传 reducer 到 Blender argv**

把现有：

```python
    s = run_blender_script(blender, "bl_decimate.py",
                           [args.input, out_fbx, str(args.tris), args.unwrap,
                            "" if args.max_overlap is None else str(args.max_overlap)])
```

改为：

```python
    s = run_blender_script(blender, "bl_decimate.py",
                           [args.input, out_fbx, str(args.tris), args.unwrap,
                            "" if args.max_overlap is None else str(args.max_overlap),
                            args.reducer])
```

- [ ] **Step 3: 打印实际后端**

把现有的这行：

```python
    print("== %s: %d -> %d 面（目标 %d）-> %s" %
          (s["src"], s["tris_before"], s["tris_after"], s["target"], out_fbx))
```

其后新增一行：

```python
    print("== %s: %d -> %d 面（目标 %d）-> %s" %
          (s["src"], s["tris_before"], s["tris_after"], s["target"], out_fbx))
    print("  后端: %s" % s.get("reducer", "collapse"))
```

- [ ] **Step 4: 编译与 CLI 冒烟（不进 Blender 也能验证 argparse）**

Run：

```bash
python -m py_compile model_decimate.py
python model_decimate.py --help
```

Expected: 编译 exit 0；`--help` 输出含 `--reducer {collapse,quad}`。

- [ ] **Step 5: 提交**

```bash
git add -- Tools/ModelTranslator/model_decimate.py
git commit -m "ModelTranslator: expose --reducer CLI option"
```

---

### Task 4: 真机验证与文档

**Files:**
- Modify: `Tools/ModelTranslator/README.md`
- Verify: `Tools/ModelTranslator/out_qr/*`（未跟踪产物）

- [ ] **Step 1: quad 后端真机 smoke**

Run（`--blender` 用本机实际路径）：

```bash
python model_decimate.py src/well1500.fbx --tris 5000 --reducer quad -o out_qr \
  --blender "D:/tools/Blender/blender-5.0.0-windows-x64/blender.exe"
```

Expected:
- `out_qr/well1500_low.fbx` 存在；
- 打印 `后端: quad`；
- 面数近似 5000（±20%，QR 近似输出）；
- 打印 UV 岛数/翻转/重叠。

- [ ] **Step 2: collapse 默认路径回归（确认零变化）**

Run：

```bash
python model_decimate.py src/well1500.fbx --tris 5000 -o out_collapse \
  --blender "D:/tools/Blender/blender-5.0.0-windows-x64/blender.exe"
```

Expected: 打印 `后端: collapse`；`out_collapse/well1500_low.fbx` 存在；面数落在 ±3% 容差内（与本功能前一致）。对比两次输出的 UV 岛数，quad 应更少/更规整（记录数值即可，非硬性门槛）。

- [ ] **Step 3: 强制回退验证**

Run（把 `QR_ENGINE` 指向不存在的路径，逼出回退）：

```bash
QR_ENGINE="/nonexistent/xremesh.exe" python model_decimate.py src/well1500.fbx --tris 5000 --reducer quad -o out_qr_fallback \
  --blender "D:/tools/Blender/blender-5.0.0-windows-x64/blender.exe"
```

Expected: 打印 `后端: quad->collapse`；输出仍正常生成；warnings 含"未找到 QuadRemesher 引擎"。

- [ ] **Step 4: 更新 README**

在 `Tools/ModelTranslator/README.md` 的减面章节，`model_decimate.py` 说明处加一段：

```markdown
- **`--reducer collapse|quad`**（默认 `collapse`）：减面后端。`quad` 用 Quad Remesher
  出规整四边拓扑（改善碎三角与 UV 展开），headless 下直接调 `Engine/xremesh.exe`
  引擎子进程（不走插件 modal 操作符）。面数按 `tris/2` 换算为目标四边形数，输出为
  近似面数（±10~20%）。引擎缺失/超时/失败/无有效输出时**自动回退 collapse**，摘要
  `reducer` 字段标 `quad->collapse`。可用 `QR_ENGINE` 环境变量覆盖引擎路径。
```

- [ ] **Step 5: 最终自动化验证**

Run：

```bash
python -m py_compile qr_bridge.py bl_decimate.py model_decimate.py
python -m unittest discover -s tests -v
```

Expected: 编译 exit 0；全部测试通过、零失败。

- [ ] **Step 6: 检查 diff 与暂存范围**

Run：

```bash
git status --short
git diff --check
```

Expected: 无空白错误；只有本计划涉及的源码/README/文档被改或暂存；用户既有的 Unity/src/产物脏文件保持未暂存未改。

- [ ] **Step 7: 提交文档**

```bash
git add -- Tools/ModelTranslator/README.md docs/superpowers/specs/2026-07-22-quadremesher-decimate-backend-design.md docs/superpowers/plans/2026-07-22-quadremesher-decimate-backend.md
git commit -m "ModelTranslator: document QR quad remesh backend"
```

---

## Self-Review 记录

- **Spec 覆盖**：可选后端(Task 2/3)、纯桥模块(Task 1)、headless 直调引擎(Task 2 `_remesh_quad`)、回退 collapse(Task 2 分流 + Task 4 Step 3)、面数 tris/2(Task 1 `tris_to_target_quads`)、硬边默认(Task 1 `build_settings` hard_edges=True)、`reducer` 摘要字段(Task 2 Step 5)、README(Task 4)、测试(Task 1 单测 + Task 4 真机)——全覆盖。
- **占位符**：无 TBD/TODO，所有代码步骤含完整代码。
- **类型一致**：`reducer` 取值 `collapse`/`quad`/`quad->collapse` 全程一致；`parse_progress` 返回 `(state, msg)` 与 `_remesh_quad` 消费一致；argv[5] 索引与 `model_decimate.py` 透传第 6 位一致；`find_qr_engine`/`tris_to_target_quads`/`build_settings` 签名在 Task 1 定义、Task 2 消费一致。