AIC-Project/docs/superpowers/plans/2026-07-21-uv-island-reduction.md

UV 减岛优化实现计划（--max-overlap + 减面前网格清理）

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: 让减面工具能通过 --max-overlap 放宽重叠门限选中更高 seam 角度（更少碎岛），并在减面前清理网格，从而降低 UV 岛数、回升利用率。

Architecture: 全部改动内联进 bl_decimate.py（Blender 脚本）与 model_decimate.py（CLI）。重叠容忍由模块常量升级为 keyword-default 运行时参数，经 uv_gate_ok/pick_best_candidate/_do_unwrap 透传；翻转门限保持严格。纯函数（门限判定）走 TDD 单测；Blender 算子集成（_clean_mesh、_do_unwrap、argv、CLI）由端到端真实 FBX 验证。所有增强单点失败降级、不中断，FBX 必产出。

Tech Stack: Python 3（标准库 + unittest）、Blender 5.0 headless（bpy/bmesh/mathutils）。

---

File Structure

• Tools/ModelTranslator/bl_decimate.py（Modify）：uv_gate_ok/pick_best_candidate/_do_unwrap 加 overlap_tol 参数；新增常量 REL_WELD 与函数 _clean_mesh；main() 接线（argv 第 5 位 + join 后清理）。
• Tools/ModelTranslator/model_decimate.py（Modify）：新增 --max-overlap 参数、校验、透传。
• Tools/ModelTranslator/tests/test_bl_decimate.py（Modify）：uv_gate_ok/pick_best_candidate 的 overlap_tol 单测。
• Tools/ModelTranslator/README.md（Modify）：--max-overlap 与网格清理说明。

---

Task 1: overlap_tol 参数穿透纯函数（TDD）

uv_gate_ok 与 pick_best_candidate 增加 keyword-default overlap_tol；翻转门限不受影响。

Files:

• Modify: Tools/ModelTranslator/bl_decimate.py（uv_gate_ok 约 :31-33、pick_best_candidate 约 :41-48）

• Test: Tools/ModelTranslator/tests/test_bl_decimate.py

• Step 1: 写失败测试

在 tests/test_bl_decimate.py 的 TestUvGateOk 类内追加以下方法：

    def test_custom_overlap_tol_allows_higher_overlap(self):
        self.assertTrue(bd.uv_gate_ok(0.0, 0.12, overlap_tol=0.15))
        self.assertFalse(bd.uv_gate_ok(0.0, 0.16, overlap_tol=0.15))

    def test_custom_overlap_tol_does_not_relax_flip(self):
        # 放宽重叠不影响翻转判定（翻转仍按 UV_FLIP_TOL）
        self.assertFalse(bd.uv_gate_ok(0.03, 0.0, overlap_tol=0.5))

    def test_default_overlap_tol_matches_constant(self):
        self.assertTrue(bd.uv_gate_ok(0.0, bd.UV_OVERLAP_TOL))
        self.assertFalse(bd.uv_gate_ok(0.0, bd.UV_OVERLAP_TOL + 0.01))

在 TestPickBestCandidate 类内追加：

    def test_overlap_tol_lets_more_candidates_pass(self):
        # overlap=0.12 在默认 8% 门限下不过；放宽到 0.15 后过门并被选中
        cands = [self._c(0.0, 0.12, 50, 55)]
        self.assertIsNone(bd.pick_best_candidate(cands))
        best = bd.pick_best_candidate(cands, overlap_tol=0.15)
        self.assertEqual(best["angle"], 55)

• Step 2: 运行测试确认失败

Run:

cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_bl_decimate.TestUvGateOk tests.test_bl_decimate.TestPickBestCandidate -v

Expected: FAIL — uv_gate_ok() got an unexpected keyword argument 'overlap_tol'（及 pick_best_candidate 同理）

• Step 3: 改实现

将 bl_decimate.py 的 uv_gate_ok 替换为：

def uv_gate_ok(flipped, overlap, overlap_tol=UV_OVERLAP_TOL):
    """UV 质量门：翻转按 UV_FLIP_TOL 固定，重叠按 overlap_tol（默认 UV_OVERLAP_TOL）。
    overlap 为 None（op 不可用）按 0 处理。"""
    return flipped <= UV_FLIP_TOL and (overlap or 0.0) <= overlap_tol

将 pick_best_candidate 替换为：

def pick_best_candidate(candidates, overlap_tol=UV_OVERLAP_TOL):
    """从候选 UV 指标 dict 列表选过质量门且岛数最少者；无过门候选返回 None。
    overlap_tol 覆盖重叠容忍。每个 candidate 至少含 flipped/overlap/islands。"""
    passing = [c for c in candidates
               if uv_gate_ok(c["flipped"], c["overlap"], overlap_tol)]
    if not passing:
        return None
    return min(passing, key=lambda c: c["islands"])

• Step 4: 运行测试确认通过

Run:

cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_bl_decimate -v

Expected: 全部 PASS（含新增用例）

• Step 5: 提交

cd "d:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_decimate.py Tools/ModelTranslator/tests/test_bl_decimate.py && git commit -m "ModelTranslator: uv_gate_ok/pick_best_candidate 加 overlap_tol 参数

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

---

Task 2: _do_unwrap 透传 overlap_tol + main() argv 解析

_do_unwrap 接收 overlap_tol 并用于扫描门检与择优；main() 解析 argv 第 5 位。

Files:

• Modify: Tools/ModelTranslator/bl_decimate.py（_do_unwrap 与 main()）

• Step 1: 改 _do_unwrap

将 bl_decimate.py 的整个 _do_unwrap 替换为（仅签名、docstring、两处 gate/择优调用带上 overlap_tol，其余逻辑不变）：

def _do_unwrap(obj, mode, warnings, overlap_tol=UV_OVERLAP_TOL):
    """按模式展开：seam 从 SEAM_ANGLE_DEG 起降序扫 SEAM_ANGLE_SWEEP，首个过门者即选并停扫
    ——岛数随角度降单调增，故首个过门者已是过门候选里岛数最少的（pick_best_candidate 据此在
    候选集取岛数最少者，与早停一致；重跑分支为防御：早停下 best 恒为最后一档，通常不触发）；
    全失败退 smart。overlap_tol 覆盖重叠门限（翻转仍严格）。排布 UVPM4 增强，只在最终 UV
    上跑一次，失败保底内置 pack。返回 uv 指标 dict（含 mode）。"""
    if mode == "seam":
        angles = [SEAM_ANGLE_DEG] + list(SEAM_ANGLE_SWEEP)
        candidates = []
        for ang in angles:
            _unwrap_seam(obj, warnings, seam_angle_deg=ang)
            m = _collect_uv_metrics(obj)
            m["angle"] = ang
            candidates.append(m)
            if uv_gate_ok(m["flipped"], m["overlap"], overlap_tol):
                break   # 该档已过门；更低角度只会更碎，无需再试
        best = pick_best_candidate(candidates, overlap_tol)
        if best is not None:
            if best["angle"] != candidates[-1]["angle"]:
                # 选中档不是最后跑的那档，重跑恢复其 UV（_unwrap_seam 会覆盖）
                _unwrap_seam(obj, warnings, seam_angle_deg=best["angle"])
            uvpm = _uvpm_repack(obj, warnings)
            m = _collect_uv_metrics(obj)
            m["mode"] = uvpm_mode_label("seam@%d" % int(best["angle"]), uvpm)
            return m
        detail = "、".join(
            "%d°(翻转%.1f%% 重叠%s)" % (
                int(c["angle"]), c["flipped"] * 100,
                "%.1f%%" % (c["overlap"] * 100) if c["overlap"] is not None else "未知")
            for c in candidates)
        warnings.append("所有 seam 角度均未过质量门（%s），回退 smart_project" % detail)
        mode = "smart_fallback"
    _unwrap_smart(obj)
    uvpm = _uvpm_repack(obj, warnings)
    m = _collect_uv_metrics(obj)
    m["mode"] = uvpm_mode_label(mode if mode == "smart_fallback" else "smart", uvpm)
    return m

• Step 2: 改 main() argv 解析与调用

在 main() 中，unwrap_mode = argv[3] if len(argv) > 3 else "seam" 之后新增一行解析 overlap_tol：

    unwrap_mode = argv[3] if len(argv) > 3 else "seam"
    overlap_tol = float(argv[4]) if len(argv) > 4 and argv[4] else UV_OVERLAP_TOL

并把 main() 里对 _do_unwrap 的调用（现为 uv_info = _do_unwrap(obj, unwrap_mode, warnings)）改为：

    uv_info = _do_unwrap(obj, unwrap_mode, warnings, overlap_tol)

• Step 3: 语法自检 + 单测不回归

Run:

cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -c "import ast; ast.parse(open('bl_decimate.py', encoding='utf-8').read()); print('OK')" && python -m unittest tests.test_bl_decimate 2>&1 | tail -3

Expected: OK，随后单测全 PASS。（_do_unwrap 行为在 Task 6 端到端验证。）

• Step 4: 提交

cd "d:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_decimate.py && git commit -m "ModelTranslator: _do_unwrap 透传 overlap_tol,main 解析 argv 第5位

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

---

Task 3: 减面前网格清理 _clean_mesh

新增常量 REL_WELD 与 _clean_mesh；main() 在 join 后、三角化前调用。

Files:

• Modify: Tools/ModelTranslator/bl_decimate.py（常量区 + _decimate 后新增函数 + main()）

• Step 1: 新增常量

在 bl_decimate.py 常量区 STRETCH_ITERS = 30 那一行之后追加：

REL_WELD = 1e-4   # 焊接距离占局部包围盒对角线比例（避免 cm/m 单位差异导致绝对阈值失准）

• Step 2: 新增 _clean_mesh 函数

在 bl_decimate.py 的 _decimate 函数之后新增：

def _clean_mesh(obj, warnings):
    """减面前清理：按局部包围盒对角线相对焊接重合点 + 去退化面，给 collapse 更干净的流形，
    减少被迫加的 seam。各步失败降级不中断。"""
    import bpy
    import mathutils
    bb = [mathutils.Vector(c) for c in obj.bound_box]
    diag = (bb[0] - bb[6]).length
    bpy.context.view_layer.objects.active = obj
    bpy.ops.object.mode_set(mode='EDIT')
    bpy.ops.mesh.select_all(action='SELECT')
    if diag > 0.0:
        try:
            bpy.ops.mesh.remove_doubles(threshold=diag * REL_WELD)
        except RuntimeError as e:
            warnings.append("remove_doubles 失败（%s），跳过焊接" % e)
    else:
        warnings.append("包围盒对角线为 0，跳过焊接")
    try:
        bpy.ops.mesh.dissolve_degenerate()
    except RuntimeError as e:
        warnings.append("dissolve_degenerate 失败（%s），跳过去退化" % e)
    bpy.ops.object.mode_set(mode='OBJECT')

• Step 3: main() 接线

在 main() 中 obj = join_meshes(meshes) 之后、_triangulate(obj) 之前插入：

    _clean_mesh(obj, warnings)

• Step 4: 语法自检 + 单测不回归

Run:

cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -c "import ast; ast.parse(open('bl_decimate.py', encoding='utf-8').read()); print('OK')" && python -m unittest tests.test_bl_decimate 2>&1 | tail -3

Expected: OK，随后单测全 PASS。（清理行为在 Task 6 端到端验证。）

• Step 5: 提交

cd "d:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_decimate.py && git commit -m "ModelTranslator: 减面前 _clean_mesh 焊接重合点+去退化面

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

---

Task 4: model_decimate.py 新增 --max-overlap

CLI 参数 + 校验 + 透传给 bl_decimate（argv 第 5 位）。

Files:

• Modify: Tools/ModelTranslator/model_decimate.py

• Step 1: 加参数

在 model_decimate.py 的 ap.add_argument("--unwrap", ...) 之后、ap.add_argument("--blender", ...) 之前新增：

    ap.add_argument("--max-overlap", type=float, default=None,
                    help="UV 重叠容忍上限（0-1，默认内置 0.08）；调高可让更高 seam 角度过门、减少碎岛")

• Step 2: 加校验

在 if args.tris <= 0: ap.error(...) 之后新增：

    if args.max_overlap is not None and not (0.0 < args.max_overlap <= 1.0):
        ap.error("--max-overlap 必须在 (0, 1] 内")

• Step 3: 透传

将 run_blender_script(blender, "bl_decimate.py", [args.input, out_fbx, str(args.tris), args.unwrap]) 改为：

    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)])

• Step 4: 语法自检 + 参数校验（无需 Blender）

Run:

cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -c "import ast; ast.parse(open('model_decimate.py', encoding='utf-8').read()); print('OK')" && python model_decimate.py dummy.fbx --tris 100 --max-overlap 2 2>&1 | tail -2

Expected: OK；随后 argparse 报错退出，信息含 --max-overlap 必须在 (0, 1] 内（在启动 Blender 前就拒绝，无需真实 FBX）。

• Step 5: 提交

cd "d:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/model_decimate.py && git commit -m "ModelTranslator: model_decimate 新增 --max-overlap 参数（校验+透传）

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

---

Task 5: README 更新

Files:

• Modify: Tools/ModelTranslator/README.md

• Step 1: 更新 model_decimate.py 说明段

将 README.md 的 - **model_decimate.py**：… 那条整体替换为（在现有基础上补入网格清理与 --max-overlap）：

- **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 上跑一次），UVPM4 不可用自动沿用内置 pack_islands 布局；输出 `<名>_low.fbx`（`-o` 改目录）与 `<名>_low_uv.png`（UV 线框观察图，便于人工查阅切分/排布/碎岛——Blender 抽 UV 几何，系统 Python 用 Pillow 绘制，因 headless 无 GPU 无法用 Blender 直接出 PNG），日志报 UV 岛数/利用率与实际生效的 seam 角度

• Step 2: 提交

cd "d:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/README.md && git commit -m "ModelTranslator: README 补充 --max-overlap 与减面前网格清理

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

---

Task 6: 端到端验证 + 前后对比

Files: 无（仅运行验证）

• Step 1: 全量单测

Run:

cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_bl_decimate tests.test_uv_preview tests.test_unity_assets 2>&1 | tail -3

Expected: 全部 PASS。

• Step 2: 端到端 —— 放宽重叠（减岛目标）

Run:

cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && rm -f src/gargoyle_low_uv.png && PYTHONIOENCODING=utf-8 python model_decimate.py src/gargoyle.fbx --tris 3000 --max-overlap 0.15 2>&1 | tail -6 && ls -la src/gargoyle_low_uv.png

Expected: 成功；模式 为更高角度（如 seam@55+uvpm/seam@45+uvpm）；岛数明显低于基线 686、利用率高于 38.2%；gargoyle_low_uv.png 生成。记录实际 岛数/利用率/翻转/重叠/角度。用 Read 打开 PNG 确认碎岛减少、留白减少。

• Step 3: 端到端 —— 默认路径不回归

Run:

cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && PYTHONIOENCODING=utf-8 python model_decimate.py src/gargoyle.fbx --tris 3000 2>&1 | tail -6

Expected: 成功；默认仍 8% 门限（翻转严格）；流程不崩，FBX + 观察图产出。因网格清理现默认开启，指标可能与历史基线（686/38.2%/seam@35）略有不同——记录并说明是清理带来的差异，非回归。

• Step 4: 记录前后对比表

在最终汇报里给出三列对比：

• 基线（本优化前）：seam@35 / 686 岛 / 38.2% / 翻转 0% / 重叠 6.3%
• 默认路径（清理开启，无 --max-overlap）：实测
• --max-overlap 0.15（清理开启）：实测 列出 模式/岛数/利用率/翻转/重叠。

---

Self-Review 记录

• Spec 覆盖：①--max-overlap 穿透→Task 1(纯函数)+Task 2(_do_unwrap/main)+Task 4(CLI)；②减面前网格清理→Task 3；③测试→Task 1(TDD)+Task 6(端到端)；④README→Task 5；错误处理表（remove_doubles/dissolve_degenerate/对角线为0/越界/空串回落）→Task 2 argv 回落、Task 3 各 try/except、Task 4 校验。全部有对应任务。
• 占位符：无 TBD/TODO；每个代码步给出完整代码与确切命令、预期输出。
• 类型/命名一致：overlap_tol（Task 1 定义于 uv_gate_ok/pick_best_candidate，Task 2 在 _do_unwrap 使用并透传，键名一致）；REL_WELD/_clean_mesh（Task 3 定义与 main 调用一致）；--max-overlap→argv 第 5 位空串回落（Task 4 产生，Task 2 main 解析 float(argv[4]) if ... and argv[4] else UV_OVERLAP_TOL，契约一致）；翻转门限 UV_FLIP_TOL 全程不动。
• 已知风险/取舍：网格清理默认开启会改变默认路径指标（Task 6 Step 3 明确记录说明）；remove_doubles 相对阈值依赖 obj.bound_box 局部坐标（对角线为 0 时跳过，已处理）；_do_unwrap 早停使 pick_best_candidate 择优在单调假设下与早停一致（沿用既有设计，overlap_tol 只是放宽门限、不改这一性质）。