ModelTranslator: document QR quad remesh backend
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
ud18010
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
b8eb40f3e4
commit
ac99d104c0
@@ -47,6 +47,7 @@ python model_translator.py out_bake/well1500/well1500.fbx # -> out/well1500/
|
||||
```
|
||||
|
||||
- **model_decimate.py**：多 mesh 自动 join；**减面前清理网格**（按局部包围盒对角线相对焊接重合点 + 去退化面，给 collapse 更干净的流形、减少被迫加的 seam）；三角化后 Decimate(collapse) 减到 `--tris`（±3%，最多 2 轮修正）；旧 UV 全删后重展——默认锐边 seam 整岛展开（SLIM 展开后 `minimize_stretch` 松弛 + `average_islands_scale` 纹素均衡），质量门不达标（翻转 >2% 或重叠 >8%）先按更低 seam 角度扫描（55/45/35°）取过门且岛数最少者抢救，全失败才回退 Smart UV Project，`--unwrap smart` 可直接选投影式展开；**`--max-overlap 0.15` 放宽重叠门限**，让更高 seam 角度（岛更少）能过门被选中——岛数优先、可接受略高重叠时用（翻转门限始终严格）；排布默认用 UVPackmaster 4 重排（只在最终选定 UV 上跑一次，旋转步进调细到 15° 以利薄斜条对齐提升利用率；UVPM 启发式搜索在 headless 下会随机崩溃引擎故未启用），UVPM4 不可用自动沿用内置 pack_islands 布局；输出 `<名>_low.fbx`（`-o` 改目录）与 `<名>_low_uv.png`（UV 线框观察图，便于人工查阅切分/排布/碎岛——Blender 抽 UV 几何，系统 Python 用 Pillow 绘制，因 headless 无 GPU 无法用 Blender 直接出 PNG），日志报 UV 岛数/利用率与实际生效的 seam 角度
|
||||
- **`--reducer collapse|quad`**（默认 `collapse`，不改变既有行为）：减面后端。`quad` 用 **Quad Remesher** 出规整四边拓扑（针对 collapse 的碎三角/UV 展开难痛点），headless 下**直接调 `Engine/xremesh.exe` 引擎子进程**（导出选中 mesh → 写 RetopoSettings.txt → 阻塞轮询 progress.txt → 导回 retopo.fbx），**绕开插件的 modal 操作符**（modal 在 `blender -b` 后台不执行，直接调操作符必然失败）。面数按 `--tris ÷ 2` 换算为目标四边形数，用 `ExactQuadCount=1` 尊重目标数（自适应模式在高细节硬表面模型上会把面数炸开数倍并连带 UV 重叠爆炸，故禁用）；输出为近似面数（约 ±20%）。**任何失败——引擎缺失/超时/引擎报错/无有效输出/导回失败——都记警告并自动回退 collapse**，摘要 `reducer` 字段标 `quad->collapse`，绝不中断。`QR_ENGINE` 环境变量可覆盖引擎路径（**权威**：显式设了就以它为准，无效即视同缺失走回退）。实测 well1500：quad 得 5940 面/591 UV 岛（优于 collapse 的 745 岛、重叠 0.4% vs 2.4%）；QR 网格 seam 展开在部分资产上可能退回 smart_project，但结果仍具竞争力
|
||||
- **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% 打警告；导入后自动应用物体变换——未应用缩放的 FBX（如 cm 单位导出的 scale=0.01）会把射线距离缩到近零导致大面积烘空（脏色）；固定 `-t 1` 单线程跑 Blender——5.0 的 selected-to-active 射线求交多线程有竞争，会随机 EXCEPTION_ACCESS_VIOLATION 崩溃
|
||||
- 输出命名 `<名>_color/normal/metallic/roughness/ao.png`，正好命中转换器的纯网格贴图命名约定
|
||||
|
||||
|
||||
@@ -0,0 +1,630 @@
|
||||
# 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 消费一致。
|
||||
@@ -0,0 +1,137 @@
|
||||
# ModelTranslator 减面可选后端 Quad Remesher 设计
|
||||
|
||||
日期：2026-07-22
|
||||
|
||||
## 背景与动机
|
||||
|
||||
现有减面管线 `model_decimate.py` → `bl_decimate.py` 用 Blender 原生
|
||||
**DECIMATE(COLLAPSE)** modifier 按 `--tris` 目标三角面数减面。用户不满的核心痛点：
|
||||
|
||||
1. **拓扑乱 / 碎三角**：COLLAPSE 产出狭长不规则三角，影响着色、变形、法线。
|
||||
2. **UV 展开难**：碎三角导致 seam/UV 岛碎、利用率低。
|
||||
|
||||
用户已安装 **Quad Remesher(Exoside，重打包版)** Blender 插件，可产出规整四边拓扑，
|
||||
从根子上改善以上两点。本设计将其作为**可选减面后端**接入，默认不改变现有行为。
|
||||
|
||||
## 关键技术结论（已 spike 验证）
|
||||
|
||||
`bpy.ops.qremesher.remesh()` 是 **modal 操作符**（`modal_handler_add` + timer，返回
|
||||
`RUNNING_MODAL`）。`blender -b` 后台无事件循环，modal 永不触发，结果 FBX 永不导回——
|
||||
**直接调操作符在 headless 必然失败**（与 UVPM headless 崩的教训同类）。
|
||||
|
||||
真正的重活是**解耦的外部引擎进程**：插件只是"桥"，做导出 FBX → 写 settings →
|
||||
跑 `Engine/xremesh.exe -s settings.txt` 子进程 → 轮询 `progress.txt` → 导回 retopo。
|
||||
本设计**自己重实现这 ~40 行桥胶水**，完全确定、后台安全、不依赖 modal、不受
|
||||
`--factory-startup` 影响、不需 enable 插件。
|
||||
|
||||
**Spike 实测**：icosphere 5120 tris → `TargetQuadCount=500` → 0.7s 出 441 面全 quad，
|
||||
exit 0、progress=2；重打包版无许可问题能直接跑。
|
||||
|
||||
## 约束
|
||||
|
||||
- 不加外部依赖（纯标准库 + bpy）。
|
||||
- 不覆盖输入 FBX；只在生成的 `_low.fbx` 输出重拓扑数据。
|
||||
- 现有 CLI/输出目录/命名/`collapse` 路径行为**零变化**（`--reducer` 默认 `collapse`）。
|
||||
- QR 失败（引擎缺失/超时/负值/导回空）一律记 warning 并**回退 collapse，绝不中断**——
|
||||
与现有 UVPM"失败即回退"同哲学。
|
||||
- 面数口径：`target_quads = tris // 2`，接受 QR 近似输出（约 ±20%），不做二次 collapse
|
||||
（二次 collapse 会重新引入碎三角，抵消 QR 好处）。**用 `ExactQuadCount=1` 尊重目标数**
|
||||
——真机验证发现自适应模式（`ExactQuadCount=0`）在高细节硬表面模型上面数暴涨数倍
|
||||
（well1500 目标 2500→11500 quads）并连带 seam 展开重叠爆炸，故禁用自适应。
|
||||
- `QR_ENGINE` 覆盖为**权威**语义：显式设了就以它为准，无效路径即视同缺失走 collapse 回退
|
||||
（不再静默自动发现，保证回退契约可测）。
|
||||
|
||||
## 架构
|
||||
|
||||
分三层，纯逻辑与 Blender 操作分离，便于 TDD：
|
||||
|
||||
### 1. 新增纯模块 `qr_bridge.py`（不 import bpy）
|
||||
|
||||
| 函数 | 职责 |
|
||||
|---|---|
|
||||
| `find_qr_engine() -> str \| None` | 按标准 addon 路径查 `xremesh.exe`，找不到返回 None |
|
||||
| `tris_to_target_quads(tris) -> int` | `max(1, tris // 2)`；1 quad ≈ 2 tris |
|
||||
| `build_settings(in_fbx, out_fbx, prog, target_quads, *, adaptive=50, exact=False, hard_edges=True) -> str` | 生成 `RetopoSettings.txt` 文本（HostApp/FileIn/FileOut/ProgressFile/TargetQuadCount/CurvatureAdaptivness/ExactQuadCount/AutoDetectHardEdges 等） |
|
||||
| `parse_progress(text) -> (state, msg)` | `state ∈ {"running","success","error"}`；首行 `2`=success，`<0`=error（次行为文本），空/其它=running |
|
||||
|
||||
`find_qr_engine` 搜索顺序：`QR_ENGINE` 环境变量 → `%APPDATA%/Blender Foundation/Blender/*/scripts/addons/QuadRemesher/Engine/xremesh.exe`。
|
||||
|
||||
### 2. `bl_decimate.py` 新增 `_remesh_quad(obj, target_tris, warnings) -> bool`
|
||||
|
||||
Blender 内执行，步骤：
|
||||
|
||||
1. `find_qr_engine()`；None → warning，return False。
|
||||
2. 建工作目录（`tempfile.gettempdir()/mt_qr/`），清旧 `retopo.fbx`/`progress.txt`。
|
||||
3. 选中 `obj`，`bpy.ops.export_scene.fbx(use_selection=True)` 导出 `inputMesh.fbx`。
|
||||
4. `build_settings(...)` 写 `RetopoSettings.txt`（`hard_edges=True`，`exact=False`）。
|
||||
5. `subprocess.Popen([engine, "-s", settings])`，阻塞轮询 `progress.txt`（间隔 0.3s，
|
||||
超时默认 **120s**）：
|
||||
- `parse_progress` → `success` 且 `retopo.fbx` 非空 → 进入 6；
|
||||
- `error` / 超时 / 进程退出但无输出 → warning，return False。
|
||||
6. 记录旧对象集合 → `bpy.ops.import_scene.fbx(retopo.fbx)` → 删除原 `obj`，把导回的
|
||||
mesh 设为新 active object（供后续展 UV/导出复用）。return True。
|
||||
|
||||
**任何异常都被捕获 → warning → return False**，不抛出。
|
||||
|
||||
### 3. `main()` 分流
|
||||
|
||||
- 解析第 5 个 argv `reducer`（`"collapse"`（默认）/`"quad"`）。
|
||||
- 流程：
|
||||
- `_clean_mesh(obj)`（现有）
|
||||
- `reducer == "quad"` 且 `_remesh_quad()` 成功 → **跳过 DECIMATE**，记 `reducer="quad"`；
|
||||
否则（或 QR 失败回退）走现有 `_triangulate` + collapse 循环，记 `reducer="collapse"`
|
||||
或 `"quad->collapse"`。
|
||||
- 之后照旧：`_do_unwrap`（在更干净的拓扑上展 UV）→ 三角化保证导出为三角 → 导出。
|
||||
- `MT_SUMMARY` 加 `reducer` 字段。
|
||||
|
||||
> 注：QR 输出为 quad，展 UV 在 quad 上进行（seam 更干净）；导出前需确保三角化
|
||||
> （复用现有 `_triangulate`），使 `_low.fbx` 仍为三角网格，兼容下游烘焙。
|
||||
|
||||
### 4. `model_decimate.py` CLI
|
||||
|
||||
- 加 `--reducer {collapse,quad}`，`default="collapse"`，透传给 Blender argv 第 5 位。
|
||||
- 打印实际后端与面数：`后端=quad 面数 20000 -> 882`（或 `quad->collapse` 回退提示）。
|
||||
|
||||
## 数据流
|
||||
|
||||
```
|
||||
FBX --import--> join --clean--> [reducer 分流]
|
||||
quad: export inputMesh.fbx --xremesh.exe--> retopo.fbx --import--> 全 quad obj
|
||||
collapse: DECIMATE(ratio) 循环
|
||||
--> _do_unwrap(seam+UVPM) --triangulate--> export _low.fbx + MT_SUMMARY{reducer,...}
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
| 情况 | 处理 |
|
||||
|---|---|
|
||||
| 找不到 xremesh.exe | warning，回退 collapse |
|
||||
| 引擎超时（>120s） | kill 进程，warning，回退 collapse |
|
||||
| progress 负值（含无许可/EULA 的 -2） | warning（带引擎文本），回退 collapse |
|
||||
| 进程退出但 retopo.fbx 空/缺 | warning，回退 collapse |
|
||||
| 导回 FBX 无 mesh | warning，回退 collapse |
|
||||
|
||||
回退后 `reducer` 字段标 `quad->collapse`，用户可从摘要看出实际走了哪条路。
|
||||
|
||||
## 测试
|
||||
|
||||
- **`tests/test_qr_bridge.py`**（纯函数，TDD）：
|
||||
- `tris_to_target_quads`：偶/奇/极小值（`1→1`, `10000→5000`, `1→1`）。
|
||||
- `build_settings`：含关键行、路径转义、`exact`/`hard_edges` 开关映射正确。
|
||||
- `parse_progress`：`"2"`→success、`"-3\n失败"`→error 带文本、`""`/`"0.5"`→running。
|
||||
- `find_qr_engine`：环境变量优先、缺失返回 None（用临时目录构造）。
|
||||
- **回归**：`python -m unittest discover -s tests` 全绿（现有测试不受影响）。
|
||||
- **真机 smoke**：
|
||||
- `python model_decimate.py src/well1500.fbx --tris 5000 --reducer quad -o out_qr`
|
||||
→ 输出存在、`reducer=quad`、面数近似 5000（±20%）、UV 岛数/翻转/重叠 打印。
|
||||
- 与 `--reducer collapse`（默认）对比 UV 指标，确认岛数下降/更规整。
|
||||
- 强制回退验证：临时改 `QR_ENGINE` 指向不存在路径 → `reducer=quad->collapse`、
|
||||
仍正常出 `_low.fbx`。
|
||||
|
||||
## 明确不做（YAGNI）
|
||||
|
||||
- 不改烘焙 `bl_bake.py`（QR 只作用于减面产出的低模）。
|
||||
- 不做二次 collapse 卡精确面数。
|
||||
- 不暴露 QR 全部参数（对称/顶点色/材质引导）；只用 target/adaptive/hard_edges 合理默认。
|
||||
- 不动进行中的 `2026-07-16-model-bake-quality-optimization` 计划；本功能与其正交，
|
||||
可后续叠加（quad 拓扑 + 法线修复不冲突）。
|
||||
Reference in New Issue
Block a user