920 lines
35 KiB
Markdown
920 lines
35 KiB
Markdown
# ModelTranslator Bake Quality Optimization 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:** Make decimation and selected-to-active baking automatically repair unsuitable low-poly normals and UVs, and derive projection distance from measured high/low surface separation.
|
||
|
||
**Architecture:** Add a Blender-independent `mt_quality.py` policy module for deterministic thresholds, percentile calculations, and CLI validation. Keep Blender operations in `bl_decimate.py` and `bl_bake.py`: decimation rebuilds normals and adaptively unwraps UVs, while baking validates arbitrary low models, repairs only in memory, samples a high-poly BVH, and reports quality metrics through the existing `MT_SUMMARY` protocol.
|
||
|
||
**Tech Stack:** Python 3 standard library, Blender 5.0 `bpy`/`mathutils`, `unittest`, existing headless Blender runner.
|
||
|
||
## Global Constraints
|
||
|
||
- Do not add external dependencies.
|
||
- Do not overwrite either input FBX; repaired data is exported only in generated low/bake output FBX files.
|
||
- Keep existing output directories, output stems, texture names, and existing CLI invocations compatible.
|
||
- Explicit `--ray-distance` overrides adaptive ray calculation.
|
||
- Defaults are texture size 2048, padding 8px, smooth angle 66 degrees, UV overlap limit 2%, and UV flip limit 0.5%.
|
||
- Preserve unrelated user changes and never stage `Tools/ModelTranslator/src`, bake products, Unity assets, or other dirty-worktree files.
|
||
- Follow TDD for every pure policy behavior and run the real `well1500.fbx + well_uv.fbx` smoke test before completion.
|
||
|
||
---
|
||
|
||
## File Map
|
||
|
||
- Create `Tools/ModelTranslator/mt_quality.py`: pure quality thresholds and decisions; no `bpy` import.
|
||
- Create `Tools/ModelTranslator/tests/test_mt_quality.py`: unit tests for every policy function.
|
||
- Modify `Tools/ModelTranslator/bl_decimate.py`: normal rebuild, adaptive seam attempts, dynamic UV margin, metrics.
|
||
- Modify `Tools/ModelTranslator/model_decimate.py`: new compatible CLI options and metric output.
|
||
- Modify `Tools/ModelTranslator/bl_bake.py`: UV/normal diagnosis, in-memory repair, BVH sampling, adaptive ray, dynamic bake margin.
|
||
- Modify `Tools/ModelTranslator/model_bake.py`: new compatible CLI options and metric output.
|
||
- Modify `Tools/ModelTranslator/README.md`: defaults, overrides, and quality diagnostics.
|
||
|
||
---
|
||
|
||
### Task 1: Pure Quality Policy Module
|
||
|
||
**Files:**
|
||
- Create: `Tools/ModelTranslator/mt_quality.py`
|
||
- Create: `Tools/ModelTranslator/tests/test_mt_quality.py`
|
||
|
||
**Interfaces:**
|
||
- Produces: `percentile(values, q) -> float`
|
||
- Produces: `sample_indices(count, limit=10000) -> list[int]`
|
||
- Produces: `adaptive_ray_distance(distances, bbox_dims) -> dict`
|
||
- Produces: `normal_deviation_is_bad(median_deg, p90_deg) -> bool`
|
||
- Produces: `should_repair_normals(median_deg, p90_deg, keep) -> bool`
|
||
- Produces: `padding_to_margin(padding, texture_size) -> float`
|
||
- Produces: `uv_metrics_acceptable(metrics) -> bool`
|
||
- Produces: `should_repair_uv(metrics, keep) -> bool`
|
||
- Produces: `select_uv_candidate(candidates) -> dict | None`
|
||
|
||
- [ ] **Step 1: Write failing unit tests**
|
||
|
||
Create `Tools/ModelTranslator/tests/test_mt_quality.py` with:
|
||
|
||
```python
|
||
import os
|
||
import sys
|
||
import unittest
|
||
|
||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||
import mt_quality as mq
|
||
|
||
|
||
class TestPercentile(unittest.TestCase):
|
||
def test_interpolates_percentile(self):
|
||
self.assertAlmostEqual(mq.percentile([0.0, 10.0], 0.25), 2.5)
|
||
|
||
def test_rejects_empty_values(self):
|
||
with self.assertRaises(ValueError):
|
||
mq.percentile([], 0.99)
|
||
|
||
def test_rejects_invalid_quantile(self):
|
||
with self.assertRaises(ValueError):
|
||
mq.percentile([1.0], 1.1)
|
||
|
||
|
||
class TestSampleIndices(unittest.TestCase):
|
||
def test_returns_all_when_under_limit(self):
|
||
self.assertEqual(mq.sample_indices(4, 10), [0, 1, 2, 3])
|
||
|
||
def test_evenly_spreads_and_includes_endpoints(self):
|
||
self.assertEqual(mq.sample_indices(100, 4), [0, 33, 66, 99])
|
||
|
||
def test_empty_count(self):
|
||
self.assertEqual(mq.sample_indices(0), [])
|
||
|
||
|
||
class TestAdaptiveRayDistance(unittest.TestCase):
|
||
def test_uses_p99_with_safety_factor(self):
|
||
result = mq.adaptive_ray_distance([0.004] * 20, (1.0, 0.0, 0.0))
|
||
self.assertAlmostEqual(result["distance_p99"], 0.004)
|
||
self.assertAlmostEqual(result["value"], 0.006)
|
||
self.assertFalse(result["capped"])
|
||
|
||
def test_applies_bbox_floor(self):
|
||
result = mq.adaptive_ray_distance([0.0], (1.0, 0.0, 0.0))
|
||
self.assertAlmostEqual(result["value"], 0.0005)
|
||
|
||
def test_applies_bbox_cap(self):
|
||
result = mq.adaptive_ray_distance([0.02], (1.0, 0.0, 0.0))
|
||
self.assertAlmostEqual(result["value"], 0.01)
|
||
self.assertTrue(result["capped"])
|
||
|
||
def test_rejects_zero_bbox(self):
|
||
with self.assertRaises(ValueError):
|
||
mq.adaptive_ray_distance([0.01], (0.0, 0.0, 0.0))
|
||
|
||
|
||
class TestNormalPolicy(unittest.TestCase):
|
||
def test_flags_median_threshold(self):
|
||
self.assertTrue(mq.normal_deviation_is_bad(25.1, 20.0))
|
||
|
||
def test_flags_p90_threshold(self):
|
||
self.assertTrue(mq.normal_deviation_is_bad(10.0, 50.1))
|
||
|
||
def test_accepts_threshold_boundaries(self):
|
||
self.assertFalse(mq.normal_deviation_is_bad(25.0, 50.0))
|
||
|
||
def test_repairs_bad_normals_unless_kept(self):
|
||
self.assertTrue(mq.should_repair_normals(30.0, 55.0, keep=False))
|
||
self.assertFalse(mq.should_repair_normals(30.0, 55.0, keep=True))
|
||
|
||
|
||
class TestUvPolicy(unittest.TestCase):
|
||
def test_padding_to_margin(self):
|
||
self.assertAlmostEqual(mq.padding_to_margin(8, 2048), 8 / 2048.0)
|
||
|
||
def test_padding_rejects_invalid_values(self):
|
||
with self.assertRaises(ValueError):
|
||
mq.padding_to_margin(-1, 2048)
|
||
with self.assertRaises(ValueError):
|
||
mq.padding_to_margin(8, 0)
|
||
|
||
def test_accepts_clean_uv(self):
|
||
self.assertTrue(mq.uv_metrics_acceptable(
|
||
{"overlap": 0.02, "flipped": 0.005, "fill": 0.4}))
|
||
|
||
def test_rejects_unknown_or_dirty_uv(self):
|
||
self.assertFalse(mq.uv_metrics_acceptable(
|
||
{"overlap": None, "flipped": 0.0, "fill": 0.4}))
|
||
self.assertFalse(mq.uv_metrics_acceptable(
|
||
{"overlap": 0.021, "flipped": 0.0, "fill": 0.4}))
|
||
self.assertFalse(mq.uv_metrics_acceptable(
|
||
{"overlap": 0.0, "flipped": 0.006, "fill": 0.4}))
|
||
self.assertFalse(mq.uv_metrics_acceptable(
|
||
{"overlap": 0.0, "flipped": 0.0, "fill": 0.0}))
|
||
|
||
def test_selects_first_acceptable_candidate(self):
|
||
candidates = [
|
||
{"seam_angle": 60, "overlap": 0.3, "flipped": 0.0, "fill": 0.5},
|
||
{"seam_angle": 45, "overlap": 0.012, "flipped": 0.0, "fill": 0.45},
|
||
{"seam_angle": 40, "overlap": 0.01, "flipped": 0.0, "fill": 0.4},
|
||
]
|
||
self.assertIs(mq.select_uv_candidate(candidates), candidates[1])
|
||
|
||
def test_returns_none_when_all_candidates_fail(self):
|
||
self.assertIsNone(mq.select_uv_candidate([
|
||
{"overlap": 0.1, "flipped": 0.0, "fill": 0.5}]))
|
||
|
||
def test_repairs_bad_uv_unless_kept(self):
|
||
dirty = {"overlap": 0.1, "flipped": 0.0, "fill": 0.5}
|
||
self.assertTrue(mq.should_repair_uv(dirty, keep=False))
|
||
self.assertFalse(mq.should_repair_uv(dirty, keep=True))
|
||
|
||
|
||
if __name__ == "__main__":
|
||
unittest.main()
|
||
```
|
||
|
||
- [ ] **Step 2: Run the test and verify RED**
|
||
|
||
Run from `Tools/ModelTranslator`:
|
||
|
||
```powershell
|
||
python -m unittest tests.test_mt_quality -v
|
||
```
|
||
|
||
Expected: `ERROR` with `ModuleNotFoundError: No module named 'mt_quality'`.
|
||
|
||
- [ ] **Step 3: Implement the pure policy module**
|
||
|
||
Create `Tools/ModelTranslator/mt_quality.py` with:
|
||
|
||
```python
|
||
"""Pure quality policies shared by ModelTranslator Blender tools."""
|
||
import math
|
||
|
||
DEFAULT_TEXTURE_SIZE = 2048
|
||
DEFAULT_PADDING = 8
|
||
DEFAULT_SMOOTH_ANGLE = 66.0
|
||
UV_SEAM_ANGLES = (60.0, 55.0, 50.0, 45.0, 40.0, 30.0)
|
||
UV_OVERLAP_LIMIT = 0.02
|
||
UV_FLIP_LIMIT = 0.005
|
||
NORMAL_MEDIAN_LIMIT = 25.0
|
||
NORMAL_P90_LIMIT = 50.0
|
||
RAY_SAFETY = 1.5
|
||
RAY_LOWER_PCT = 0.0005
|
||
RAY_UPPER_PCT = 0.01
|
||
|
||
|
||
def percentile(values, q):
|
||
if not values:
|
||
raise ValueError("percentile requires at least one value")
|
||
if not 0.0 <= q <= 1.0:
|
||
raise ValueError("quantile must be between 0 and 1")
|
||
ordered = sorted(float(v) for v in values)
|
||
pos = (len(ordered) - 1) * q
|
||
lo = int(math.floor(pos))
|
||
hi = int(math.ceil(pos))
|
||
if lo == hi:
|
||
return ordered[lo]
|
||
return ordered[lo] + (ordered[hi] - ordered[lo]) * (pos - lo)
|
||
|
||
|
||
def sample_indices(count, limit=10000):
|
||
if count <= 0:
|
||
return []
|
||
if limit <= 0:
|
||
raise ValueError("sample limit must be positive")
|
||
if count <= limit:
|
||
return list(range(count))
|
||
return [round(i * (count - 1) / float(limit - 1)) for i in range(limit)]
|
||
|
||
|
||
def adaptive_ray_distance(distances, bbox_dims):
|
||
diagonal = math.sqrt(sum(float(d) * float(d) for d in bbox_dims))
|
||
if diagonal <= 0.0:
|
||
raise ValueError("low-poly bounding box diagonal must be positive")
|
||
p99 = percentile(distances, 0.99)
|
||
lower = diagonal * RAY_LOWER_PCT
|
||
upper = diagonal * RAY_UPPER_PCT
|
||
raw = max(p99 * RAY_SAFETY, lower)
|
||
return {"distance_p99": p99, "value": min(raw, upper),
|
||
"capped": raw > upper}
|
||
|
||
|
||
def normal_deviation_is_bad(median_deg, p90_deg):
|
||
return median_deg > NORMAL_MEDIAN_LIMIT or p90_deg > NORMAL_P90_LIMIT
|
||
|
||
|
||
def should_repair_normals(median_deg, p90_deg, keep=False):
|
||
return not keep and normal_deviation_is_bad(median_deg, p90_deg)
|
||
|
||
|
||
def padding_to_margin(padding, texture_size):
|
||
if padding < 0:
|
||
raise ValueError("padding must not be negative")
|
||
if texture_size <= 0:
|
||
raise ValueError("texture size must be positive")
|
||
return padding / float(texture_size)
|
||
|
||
|
||
def uv_metrics_acceptable(metrics):
|
||
overlap = metrics.get("overlap")
|
||
return (overlap is not None and overlap <= UV_OVERLAP_LIMIT
|
||
and metrics.get("flipped", 1.0) <= UV_FLIP_LIMIT
|
||
and metrics.get("fill", 0.0) > 0.0)
|
||
|
||
|
||
def should_repair_uv(metrics, keep=False):
|
||
return not keep and not uv_metrics_acceptable(metrics)
|
||
|
||
|
||
def select_uv_candidate(candidates):
|
||
return next((m for m in candidates if uv_metrics_acceptable(m)), None)
|
||
```
|
||
|
||
- [ ] **Step 4: Run focused and full unit tests and verify GREEN**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
python -m unittest tests.test_mt_quality -v
|
||
python -m unittest discover -s tests -v
|
||
```
|
||
|
||
Expected: all new tests pass; all existing ModelTranslator tests pass with zero failures.
|
||
|
||
- [ ] **Step 5: Commit the policy module**
|
||
|
||
```powershell
|
||
git add -- Tools/ModelTranslator/mt_quality.py Tools/ModelTranslator/tests/test_mt_quality.py
|
||
git commit -m "ModelTranslator: add bake quality policies"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: Decimation Normal and UV Repair
|
||
|
||
**Files:**
|
||
- Modify: `Tools/ModelTranslator/bl_decimate.py`
|
||
- Modify: `Tools/ModelTranslator/model_decimate.py`
|
||
- Test: `Tools/ModelTranslator/tests/test_mt_quality.py`
|
||
|
||
**Interfaces:**
|
||
- Consumes: all UV policy constants/functions from `mt_quality.py`.
|
||
- Produces: `repair_normals(obj, smooth_angle) -> bool` for reuse by `bl_bake.py`.
|
||
- Produces: `_normal_geometry_metrics(obj) -> dict` with `median` and `p90`.
|
||
- Produces: `_do_unwrap(obj, mode, warnings, margin, angles) -> dict` with `mode`, `seam_angle`, and UV metrics.
|
||
- Extends the Blender script argv with `texture_size`, `padding`, and `smooth_angle`, each retaining a default when absent.
|
||
|
||
- [ ] **Step 1: Verify the new CLI behavior is RED before editing production code**
|
||
|
||
Run from `Tools/ModelTranslator`:
|
||
|
||
```powershell
|
||
python model_decimate.py src/well1500.fbx --tris 5000 --texture-size 2048 --padding 8 --smooth-angle 66
|
||
```
|
||
|
||
Expected: exit code 2 and `unrecognized arguments` for the new options.
|
||
|
||
- [ ] **Step 2: Parameterize UV unwrap and add adaptive candidate selection**
|
||
|
||
In `bl_decimate.py`, import the policy values and replace fixed UV constants:
|
||
|
||
```python
|
||
from mt_quality import (DEFAULT_PADDING, DEFAULT_SMOOTH_ANGLE,
|
||
DEFAULT_TEXTURE_SIZE, UV_SEAM_ANGLES,
|
||
padding_to_margin, percentile,
|
||
select_uv_candidate, uv_metrics_acceptable)
|
||
```
|
||
|
||
Replace `_unwrap_smart` with the parameterized version:
|
||
|
||
```python
|
||
def _unwrap_smart(obj, margin):
|
||
import bpy
|
||
import math
|
||
_clear_uv_layers(obj.data)
|
||
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=margin)
|
||
bpy.ops.object.mode_set(mode='OBJECT')
|
||
```
|
||
|
||
Replace `_unwrap_seam` with the parameterized version below. At the beginning of each attempt, clear old seam flags before selecting the current angle:
|
||
|
||
```python
|
||
def _unwrap_seam(obj, warnings, seam_angle, margin):
|
||
import bpy
|
||
import math
|
||
_clear_uv_layers(obj.data)
|
||
obj.data.uv_layers.new()
|
||
bpy.context.view_layer.objects.active = obj
|
||
bpy.ops.object.mode_set(mode='EDIT')
|
||
bpy.ops.mesh.select_mode(type='EDGE')
|
||
bpy.ops.mesh.select_all(action='SELECT')
|
||
bpy.ops.mesh.mark_seam(clear=True)
|
||
bpy.ops.mesh.select_all(action='DESELECT')
|
||
bpy.ops.mesh.edges_select_sharp(sharpness=math.radians(seam_angle))
|
||
bpy.ops.mesh.mark_seam(clear=False)
|
||
bpy.ops.mesh.select_all(action='SELECT')
|
||
try:
|
||
bpy.ops.uv.unwrap(method='MINIMUM_STRETCH', margin=margin)
|
||
except TypeError:
|
||
warnings.append("MINIMUM_STRETCH 不可用，展开改用 ANGLE_BASED")
|
||
bpy.ops.uv.unwrap(method='ANGLE_BASED', margin=margin)
|
||
try:
|
||
bpy.ops.uv.pack_islands(rotate=True, margin=margin)
|
||
except RuntimeError:
|
||
warnings.append("pack_islands 不可用，沿用 unwrap 自带布局")
|
||
bpy.ops.object.mode_set(mode='OBJECT')
|
||
```
|
||
|
||
Replace `_do_unwrap` with an adaptive loop. Only final fallback information is appended to `warnings`; per-angle metrics remain in the summary-ready result:
|
||
|
||
```python
|
||
def _do_unwrap(obj, mode, warnings, margin, angles=UV_SEAM_ANGLES):
|
||
if mode == "seam":
|
||
attempts = []
|
||
for angle in angles:
|
||
_unwrap_seam(obj, warnings, angle, margin)
|
||
metrics = _collect_uv_metrics(obj)
|
||
metrics["seam_angle"] = angle
|
||
attempts.append(metrics)
|
||
chosen = select_uv_candidate(attempts)
|
||
if chosen is not None:
|
||
chosen["mode"] = "seam"
|
||
return chosen
|
||
warnings.append("seam 展开候选均未通过质量门，回退 smart_project")
|
||
mode = "smart_fallback"
|
||
_unwrap_smart(obj, margin)
|
||
metrics = _collect_uv_metrics(obj)
|
||
metrics["mode"] = mode if mode == "smart_fallback" else "smart"
|
||
metrics["seam_angle"] = None
|
||
if not uv_metrics_acceptable(metrics):
|
||
warnings.append("smart_project 结果仍未通过 UV 质量门")
|
||
return metrics
|
||
```
|
||
|
||
- [ ] **Step 3: Add reusable normal metrics and repair**
|
||
|
||
Add these Blender-only helpers after `join_meshes`:
|
||
|
||
```python
|
||
def _normal_geometry_metrics(obj):
|
||
import math
|
||
values = []
|
||
mesh = obj.data
|
||
for poly in mesh.polygons:
|
||
face_normal = poly.normal.normalized()
|
||
for loop_index in poly.loop_indices:
|
||
corner = mesh.corner_normals[loop_index].vector.normalized()
|
||
dot = max(-1.0, min(1.0, corner.dot(face_normal)))
|
||
values.append(math.degrees(math.acos(dot)))
|
||
return {"median": round(percentile(values, 0.5), 3),
|
||
"p90": round(percentile(values, 0.9), 3)}
|
||
|
||
|
||
def repair_normals(obj, smooth_angle):
|
||
import bpy
|
||
import math
|
||
had_custom = bool(getattr(obj.data, "has_custom_normals", False))
|
||
bpy.ops.object.select_all(action='DESELECT')
|
||
obj.select_set(True)
|
||
bpy.context.view_layer.objects.active = obj
|
||
if had_custom:
|
||
bpy.ops.mesh.customdata_custom_splitnormals_clear()
|
||
bpy.ops.object.shade_smooth_by_angle(
|
||
angle=math.radians(smooth_angle), keep_sharp_edges=True)
|
||
obj.data.update()
|
||
return had_custom
|
||
```
|
||
|
||
In `main`, capture geometry-normal metrics before and after repair, then unwrap with the dynamic margin:
|
||
|
||
```python
|
||
normal_before = _normal_geometry_metrics(obj)
|
||
had_custom = repair_normals(obj, smooth_angle)
|
||
normal_after = _normal_geometry_metrics(obj)
|
||
margin = padding_to_margin(padding, texture_size)
|
||
uv_info = _do_unwrap(obj, unwrap_mode, warnings, margin)
|
||
uv_info.update({"repaired": True, "padding": padding,
|
||
"texture_size": texture_size})
|
||
normal_info = {"repaired": True, "had_custom": had_custom,
|
||
"basis": "corner_vs_face",
|
||
"before_median": normal_before["median"],
|
||
"before_p90": normal_before["p90"],
|
||
"after_median": normal_after["median"],
|
||
"after_p90": normal_after["p90"],
|
||
"smooth_angle": smooth_angle}
|
||
```
|
||
|
||
Parse optional Blender argv compatibly:
|
||
|
||
```python
|
||
texture_size = int(argv[4]) if len(argv) > 4 else DEFAULT_TEXTURE_SIZE
|
||
padding = int(argv[5]) if len(argv) > 5 else DEFAULT_PADDING
|
||
smooth_angle = float(argv[6]) if len(argv) > 6 else DEFAULT_SMOOTH_ANGLE
|
||
```
|
||
|
||
Add `normal_info` to `MT_SUMMARY` as `normal`.
|
||
|
||
- [ ] **Step 4: Extend and validate `model_decimate.py` CLI**
|
||
|
||
Add arguments and validation:
|
||
|
||
```python
|
||
from mt_quality import DEFAULT_PADDING, DEFAULT_SMOOTH_ANGLE, DEFAULT_TEXTURE_SIZE
|
||
|
||
ap.add_argument("--texture-size", type=int, default=DEFAULT_TEXTURE_SIZE,
|
||
help="目标烘焙贴图边长，用于换算 UV padding")
|
||
ap.add_argument("--padding", type=int, default=DEFAULT_PADDING,
|
||
help="UV 岛像素间距")
|
||
ap.add_argument("--smooth-angle", type=float, default=DEFAULT_SMOOTH_ANGLE,
|
||
help="低模平滑锐边角度（度）")
|
||
```
|
||
|
||
After parsing:
|
||
|
||
```python
|
||
if args.texture_size <= 0:
|
||
ap.error("--texture-size 必须为正整数")
|
||
if args.padding < 0:
|
||
ap.error("--padding 不能为负数")
|
||
if not 0.0 < args.smooth_angle < 180.0:
|
||
ap.error("--smooth-angle 必须在 0 到 180 度之间")
|
||
```
|
||
|
||
Append `texture_size`, `padding`, and `smooth_angle` to `run_blender_script` arguments. Print one normal line and replace the existing UV line with the expanded form:
|
||
|
||
```python
|
||
n = s["normal"]
|
||
print(" 法线: 修复=%s 中位 %.1f° -> %.1f° P90 %.1f° -> %.1f°" %
|
||
("是" if n["repaired"] else "否", n["before_median"],
|
||
n["after_median"], n["before_p90"], n["after_p90"]))
|
||
angle = "n/a" if u["seam_angle"] is None else "%.0f°" % u["seam_angle"]
|
||
print(" UV: 模式=%s seam=%s 岛数=%d 利用率=%.1f%% 翻转=%.1f%% 重叠=%s padding=%dpx" %
|
||
(u["mode"], angle, u["islands"], u["fill"] * 100,
|
||
u["flipped"] * 100, overlap, u["padding"]))
|
||
```
|
||
|
||
- [ ] **Step 5: Run unit and real decimation verification**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
python -m py_compile mt_quality.py bl_decimate.py model_decimate.py
|
||
python -m unittest discover -s tests -v
|
||
python model_decimate.py src/well1500.fbx --tris 5000 --texture-size 2048 --padding 8 --smooth-angle 66 -o out_quality
|
||
```
|
||
|
||
Expected:
|
||
|
||
- compile and unit tests exit 0;
|
||
- `out_quality/well1500_low.fbx` exists;
|
||
- CLI reports 5000 faces within existing tolerance;
|
||
- normal median and P90 decrease;
|
||
- UV overlap is at most 2%, flipped is at most 0.5%, and the chosen seam angle is reported.
|
||
|
||
- [ ] **Step 6: Commit decimation repair**
|
||
|
||
```powershell
|
||
git add -- Tools/ModelTranslator/bl_decimate.py Tools/ModelTranslator/model_decimate.py
|
||
git commit -m "ModelTranslator: repair decimated normals and UVs"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Bake Diagnosis, In-Memory Repair, and Adaptive Ray
|
||
|
||
**Files:**
|
||
- Modify: `Tools/ModelTranslator/bl_bake.py`
|
||
- Modify: `Tools/ModelTranslator/model_bake.py`
|
||
- Consume: `Tools/ModelTranslator/bl_decimate.py`
|
||
- Consume: `Tools/ModelTranslator/mt_quality.py`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `repair_normals`, `_collect_uv_metrics`, `_do_unwrap`, and `_triangulate` from `bl_decimate.py`.
|
||
- Consumes: adaptive ray, normal policy, sampling, padding, and UV policy from `mt_quality.py`.
|
||
- Produces: `MT_SUMMARY.normal`, `MT_SUMMARY.uv`, and `MT_SUMMARY.ray`.
|
||
- Extends Blender argv with `padding`, `smooth_angle`, `keep_low_normals`, and `keep_low_uv`.
|
||
|
||
- [ ] **Step 1: Verify the new bake CLI behavior is RED**
|
||
|
||
Run from `Tools/ModelTranslator`:
|
||
|
||
```powershell
|
||
python model_bake.py src/well1500.fbx src/well_uv.fbx --padding 8 --smooth-angle 66 --keep-low-normals
|
||
```
|
||
|
||
Expected: exit code 2 and `unrecognized arguments`.
|
||
|
||
- [ ] **Step 2: Add projection sample and normal metric helpers**
|
||
|
||
Import policies and shared Blender operations:
|
||
|
||
```python
|
||
from mt_quality import (DEFAULT_PADDING, DEFAULT_SMOOTH_ANGLE,
|
||
adaptive_ray_distance,
|
||
padding_to_margin, percentile, sample_indices,
|
||
should_repair_normals, should_repair_uv,
|
||
uv_metrics_acceptable)
|
||
```
|
||
|
||
Add helpers before `_setup_bake_target`:
|
||
|
||
```python
|
||
def _build_projection_samples(high, low, limit=10000):
|
||
from mathutils.bvhtree import BVHTree
|
||
high_vertices = [high.matrix_world @ v.co for v in high.data.vertices]
|
||
high_polygons = [tuple(p.vertices) for p in high.data.polygons]
|
||
bvh = BVHTree.FromPolygons(high_vertices, high_polygons,
|
||
all_triangles=False)
|
||
samples = []
|
||
for low_index in sample_indices(len(low.data.polygons), limit):
|
||
poly = low.data.polygons[low_index]
|
||
hit = bvh.find_nearest(low.matrix_world @ poly.center)
|
||
if hit[0] is not None:
|
||
samples.append({"low_index": low_index, "location": hit[0],
|
||
"geometric_normal": hit[1],
|
||
"high_index": hit[2], "distance": hit[3]})
|
||
if not samples:
|
||
raise ValueError("高低模 BVH 采样无命中")
|
||
return samples
|
||
|
||
|
||
def _normal_projection_metrics(high, low, samples):
|
||
import math
|
||
from mathutils.geometry import barycentric_transform
|
||
high_mesh, low_mesh = high.data, low.data
|
||
high_normal_matrix = high.matrix_world.to_3x3().inverted().transposed()
|
||
low_normal_matrix = low.matrix_world.to_3x3().inverted().transposed()
|
||
angles = []
|
||
for sample in samples:
|
||
high_poly = high_mesh.polygons[sample["high_index"]]
|
||
if len(high_poly.vertices) != 3:
|
||
high_normal = sample["geometric_normal"].normalized()
|
||
else:
|
||
vertex_ids = list(high_poly.vertices)
|
||
loop_ids = list(high_poly.loop_indices)
|
||
coords = [high.matrix_world @ high_mesh.vertices[i].co
|
||
for i in vertex_ids]
|
||
normals = [(high_normal_matrix
|
||
@ high_mesh.corner_normals[i].vector).normalized()
|
||
for i in loop_ids]
|
||
high_normal = barycentric_transform(
|
||
sample["location"], coords[0], coords[1], coords[2],
|
||
normals[0], normals[1], normals[2]).normalized()
|
||
low_poly = low_mesh.polygons[sample["low_index"]]
|
||
low_normals = [low_mesh.corner_normals[i].vector
|
||
for i in low_poly.loop_indices]
|
||
low_normal = (low_normal_matrix
|
||
@ sum(low_normals[1:], low_normals[0])).normalized()
|
||
dot = max(-1.0, min(1.0, low_normal.dot(high_normal)))
|
||
angles.append(math.degrees(math.acos(dot)))
|
||
return {"median": round(percentile(angles, 0.5), 3),
|
||
"p90": round(percentile(angles, 0.9), 3)}
|
||
```
|
||
|
||
- [ ] **Step 3: Add UV and normal auto-repair to bake setup**
|
||
|
||
After low UV existence validation and before creating the bake material:
|
||
|
||
```python
|
||
margin = padding_to_margin(padding, size)
|
||
uv_before = _collect_uv_metrics(low)
|
||
uv_info = dict(uv_before)
|
||
uv_info.update({"repaired": False, "seam_angle": None,
|
||
"padding": padding, "texture_size": size})
|
||
if should_repair_uv(uv_before, keep=keep_low_uv):
|
||
uv_info = _do_unwrap(low, "seam", warnings, margin)
|
||
uv_info.update({"repaired": True, "padding": padding,
|
||
"texture_size": size})
|
||
elif not uv_metrics_acceptable(uv_before):
|
||
warnings.append("低模 UV 未通过质量门，按 --keep-low-uv 保留")
|
||
|
||
bpy.ops.object.select_all(action='DESELECT')
|
||
high.select_set(True)
|
||
bpy.context.view_layer.objects.active = high
|
||
_triangulate(high)
|
||
try:
|
||
samples = _build_projection_samples(high, low)
|
||
except ValueError as exc:
|
||
print("MT_SUMMARY " + json.dumps({"error": str(exc)}, ensure_ascii=False))
|
||
return
|
||
normal_before = _normal_projection_metrics(high, low, samples)
|
||
normal_repaired = False
|
||
if should_repair_normals(normal_before["median"], normal_before["p90"],
|
||
keep=keep_low_normals):
|
||
repair_normals(low, smooth_angle)
|
||
normal_repaired = True
|
||
elif normal_deviation_is_bad(normal_before["median"], normal_before["p90"]):
|
||
warnings.append("低模法线偏差超标，按 --keep-low-normals 保留")
|
||
normal_after = _normal_projection_metrics(high, low, samples)
|
||
normal_info = {"repaired": normal_repaired, "basis": "low_vs_high",
|
||
"before_median": normal_before["median"],
|
||
"before_p90": normal_before["p90"],
|
||
"after_median": normal_after["median"],
|
||
"after_p90": normal_after["p90"],
|
||
"smooth_angle": smooth_angle}
|
||
```
|
||
|
||
Import the four shared Blender helpers inside `main` to avoid system-Python `bpy` imports at module import time:
|
||
|
||
```python
|
||
from bl_decimate import (_collect_uv_metrics, _do_unwrap, _triangulate,
|
||
repair_normals)
|
||
```
|
||
|
||
- [ ] **Step 4: Replace auto ray and bake margin behavior**
|
||
|
||
Replace the current auto ray selection:
|
||
|
||
```python
|
||
if ray_arg == "auto":
|
||
try:
|
||
ray_info = adaptive_ray_distance(
|
||
[sample["distance"] for sample in samples], tuple(low.dimensions))
|
||
except ValueError as exc:
|
||
print("MT_SUMMARY " + json.dumps({"error": str(exc)}, ensure_ascii=False))
|
||
return
|
||
ray = ray_info["value"]
|
||
ray_info.update({"source": "adaptive"})
|
||
if ray_info["capped"]:
|
||
warnings.append("自适应射线达到包围盒对角线 1%% 上限，请检查高低模对应关系")
|
||
else:
|
||
ray = float(ray_arg)
|
||
ray_info = {"source": "explicit", "distance_p99": None,
|
||
"value": ray, "capped": False}
|
||
```
|
||
|
||
Replace `_bake_pass` with the same existing body plus an explicit `padding` argument and dynamic margin:
|
||
|
||
```python
|
||
def _bake_pass(low, high, target_node, name, bake_type, size, colorspace,
|
||
ray, samples, padding, outdir, stem):
|
||
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=padding, use_clear=True)
|
||
if bake_type == 'NORMAL':
|
||
kwargs["normal_space"] = 'TANGENT'
|
||
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)
|
||
```
|
||
|
||
Pass `padding` at every `_bake_pass` call. Preserve the existing top-level `ray_distance` field and add the structured summaries:
|
||
|
||
```python
|
||
ray_info = dict(ray_info)
|
||
ray_info["distance_p99"] = (None if ray_info["distance_p99"] is None
|
||
else round(ray_info["distance_p99"], 6))
|
||
ray_info["value"] = round(ray_info["value"], 6)
|
||
print("MT_SUMMARY " + json.dumps(
|
||
{"stem": stem, "fbx": os.path.basename(out_fbx), "outputs": outputs,
|
||
"size": size, "ray_distance": round(ray, 6), "ray": ray_info,
|
||
"normal": normal_info, "uv": uv_info,
|
||
"high_tris": len(high.data.polygons),
|
||
"low_tris": len(low.data.polygons), "warnings": warnings},
|
||
ensure_ascii=False))
|
||
```
|
||
|
||
- [ ] **Step 5: Extend and validate `model_bake.py` CLI**
|
||
|
||
Add:
|
||
|
||
```python
|
||
from mt_quality import DEFAULT_PADDING, DEFAULT_SMOOTH_ANGLE
|
||
|
||
ap.add_argument("--padding", type=int, default=DEFAULT_PADDING,
|
||
help="烘焙贴图 UV 扩边像素")
|
||
ap.add_argument("--smooth-angle", type=float, default=DEFAULT_SMOOTH_ANGLE,
|
||
help="异常低模法线的修复角度（度）")
|
||
ap.add_argument("--keep-low-normals", action="store_true",
|
||
help="即使检测异常也保留输入低模法线")
|
||
ap.add_argument("--keep-low-uv", action="store_true",
|
||
help="即使检测异常也保留输入低模 UV")
|
||
```
|
||
|
||
Validate padding and angle with the same conditions as Task 2. Append these values to Blender argv:
|
||
|
||
```python
|
||
str(args.padding), str(args.smooth_angle),
|
||
"1" if args.keep_low_normals else "0",
|
||
"1" if args.keep_low_uv else "0"
|
||
```
|
||
|
||
Parse them compatibly in `bl_bake.py`:
|
||
|
||
```python
|
||
padding = int(argv[6]) if len(argv) > 6 else DEFAULT_PADDING
|
||
smooth_angle = float(argv[7]) if len(argv) > 7 else DEFAULT_SMOOTH_ANGLE
|
||
keep_low_normals = len(argv) > 8 and argv[8] == "1"
|
||
keep_low_uv = len(argv) > 9 and argv[9] == "1"
|
||
```
|
||
|
||
Print concise `normal`, `uv`, and `ray` lines from the returned summary:
|
||
|
||
```python
|
||
n = s["normal"]
|
||
print(" 法线: 修复=%s 中位 %.1f° -> %.1f° P90 %.1f° -> %.1f°" %
|
||
("是" if n["repaired"] else "否", n["before_median"],
|
||
n["after_median"], n["before_p90"], n["after_p90"]))
|
||
u = s["uv"]
|
||
overlap = "n/a" if u["overlap"] is None else "%.1f%%" % (u["overlap"] * 100)
|
||
angle = "n/a" if u["seam_angle"] is None else "%.0f°" % u["seam_angle"]
|
||
print(" UV: 修复=%s 模式=%s seam=%s 翻转=%.1f%% 重叠=%s padding=%dpx" %
|
||
("是" if u["repaired"] else "否", u.get("mode", "input"), angle,
|
||
u["flipped"] * 100, overlap, u["padding"]))
|
||
r = s["ray"]
|
||
p99 = "n/a" if r["distance_p99"] is None else "%.4f" % r["distance_p99"]
|
||
print(" 射线: 来源=%s P99=%s 距离=%.4f%s" %
|
||
(r["source"], p99, r["value"], "（已截断）" if r["capped"] else ""))
|
||
```
|
||
|
||
- [ ] **Step 6: Run focused verification with the diagnosed model**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
python -m py_compile bl_bake.py model_bake.py
|
||
python -m unittest discover -s tests -v
|
||
python model_bake.py src/well1500.fbx src/well_uv.fbx -o out_bake_optimized --size 2048 --padding 8 --samples 64
|
||
```
|
||
|
||
Expected:
|
||
|
||
- compile and all unit tests exit 0;
|
||
- normal repair is `True`, after median and P90 are lower than before, and after median is at most 20 degrees;
|
||
- UV repair is `True`, overlap is at most 2%, flipped is at most 0.5%;
|
||
- ray source is `adaptive`, with value between 0.004 and 0.010 for this model;
|
||
- `out_bake_optimized/well_uv` contains one FBX and five non-empty 2048x2048 PNG files.
|
||
|
||
- [ ] **Step 7: Verify explicit preservation and explicit ray branches**
|
||
|
||
Run a lower-cost 256px branch check:
|
||
|
||
```powershell
|
||
python model_bake.py src/well1500.fbx src/well_uv.fbx -o out_bake_optimized_keep --size 256 --padding 2 --samples 4 --ray-distance 0.006 --keep-low-normals --keep-low-uv
|
||
```
|
||
|
||
Expected: exit 0; ray source is `explicit`; warnings state that abnormal low normals and UVs were preserved; outputs exist at 256x256.
|
||
|
||
- [ ] **Step 8: Commit bake adaptation**
|
||
|
||
```powershell
|
||
git add -- Tools/ModelTranslator/bl_bake.py Tools/ModelTranslator/model_bake.py
|
||
git commit -m "ModelTranslator: adapt bake projection to model quality"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: Documentation and End-to-End Verification
|
||
|
||
**Files:**
|
||
- Modify: `Tools/ModelTranslator/README.md`
|
||
- Verify: `Tools/ModelTranslator/out_bake_optimized/well_uv/*` (untracked product)
|
||
|
||
**Interfaces:**
|
||
- Documents the CLI and summary fields produced by Tasks 2 and 3.
|
||
- Does not change converter output naming or Unity import behavior.
|
||
|
||
- [ ] **Step 1: Update README with exact defaults and overrides**
|
||
|
||
Replace the decimate/bake bullets in the “减面与高低模烘焙” section with text covering:
|
||
|
||
```markdown
|
||
- **model_decimate.py**：减面后清除旧 custom normals，按 `--smooth-angle`（默认 66°）重建锐边平滑；UV 默认尝试多档 seam 角度并以重叠 ≤2%、翻转 ≤0.5% 为质量门，失败才回退 Smart UV。`--texture-size` 默认 2048，`--padding` 默认 8px。
|
||
- **model_bake.py**：烘焙前检查外部低模法线和 UV；异常时只在内存及输出 FBX 中自动修复，源文件不变，`--keep-low-normals` / `--keep-low-uv` 可保留输入数据。自动射线取高低模 BVH 距离 P99×1.5，并限制在包围盒对角线 0.05%–1%；`--ray-distance` 显式值优先。贴图 `--padding` 默认 8px。
|
||
```
|
||
|
||
Add one short troubleshooting paragraph explaining the printed normal/UV/ray metrics and that extreme `--tris` reduction may still need a higher low-poly face budget or explicit cage.
|
||
|
||
- [ ] **Step 2: Run final automated verification**
|
||
|
||
Run from `Tools/ModelTranslator`:
|
||
|
||
```powershell
|
||
python -m py_compile mt_quality.py bl_decimate.py model_decimate.py bl_bake.py model_bake.py
|
||
python -m unittest discover -s tests -v
|
||
```
|
||
|
||
Expected: compile exits 0 and all tests pass with zero failures/errors.
|
||
|
||
- [ ] **Step 3: Validate optimized artifact dimensions and presence**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
Get-ChildItem out_bake_optimized\well_uv | Select-Object Name,Length
|
||
```
|
||
|
||
Then load each PNG in Blender and print dimensions:
|
||
|
||
```powershell
|
||
$code = @'
|
||
import bpy, glob, json, os, sys
|
||
directory = os.path.abspath(sys.argv[sys.argv.index('--') + 1])
|
||
result = {}
|
||
for path in sorted(glob.glob(os.path.join(directory, '*.png'))):
|
||
image = bpy.data.images.load(path)
|
||
result[os.path.basename(path)] = list(image.size)
|
||
print('IMAGE_JSON ' + json.dumps(result))
|
||
'@
|
||
& 'D:\tools\blender-5.0.0-windows-x64\blender.exe' -b --factory-startup --python-expr $code -- 'out_bake_optimized\well_uv' | Select-String 'IMAGE_JSON'
|
||
```
|
||
|
||
Expected: exactly five PNG entries, each `[2048, 2048]`, plus a non-empty `well_uv.fbx`.
|
||
|
||
- [ ] **Step 4: Visually inspect optimized maps**
|
||
|
||
Open with the local image viewer:
|
||
|
||
- `Tools/ModelTranslator/out_bake_optimized/well_uv/well_uv_normal.png`
|
||
- `Tools/ModelTranslator/out_bake_optimized/well_uv/well_uv_ao.png`
|
||
- `Tools/ModelTranslator/out_bake_optimized/well_uv/well_uv_color.png`
|
||
|
||
Acceptance: no large cross-part projections, no unexpected unbaked holes inside occupied UV regions, and visibly fewer extreme normal colors than the current `out_bake/well_uv` result.
|
||
|
||
- [ ] **Step 5: Inspect the final diff and staged paths**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
git diff --check
|
||
git status --short
|
||
git diff -- Tools/ModelTranslator docs/superpowers
|
||
```
|
||
|
||
Expected: no whitespace errors; only planned code/docs are modified or staged by this work; existing user Unity/source/output changes remain untouched and unstaged.
|
||
|
||
- [ ] **Step 6: Commit README and verification record**
|
||
|
||
```powershell
|
||
git add -- Tools/ModelTranslator/README.md
|
||
git commit -m "ModelTranslator: document adaptive bake quality"
|
||
```
|
||
|
||
- [ ] **Step 7: Fresh completion gate**
|
||
|
||
Re-run immediately before reporting completion:
|
||
|
||
```powershell
|
||
python -m unittest discover -s tests -v
|
||
git status --short
|
||
```
|
||
|
||
Expected: all ModelTranslator tests pass; remaining dirty paths are pre-existing user assets/products, not uncommitted planned source changes.
|