perf: batch Cesium export mesh preparation

This commit is contained in:
que01 committed 2026-09-17 17:12:42 +08:00
1 parent a4dfbf884a
commit c6cce44f60
12 files changed
+632 -11

No files matched your search

+28
View File
@@ -307,6 +307,34 @@ npm run build:area -- --config config/areas/<area>.json --stages blender,cesium,
| 直接用 Cesium `Model.getMaterial().setValue()` 改普通 glTF PBR 材质 | 运行时数字仍保持原色,不能实现相位字色 |
| 每个信号灯各自生成 0-19 全套倒计时 mesh | 节点和几何按信号数量线性膨胀;应按两个 phase group 共享 |
## Cesium 导出准备:依赖图更新边界
`export_cesium.py` 的 `prepare_independent_meshes(candidates)` 只优化可证明为对象局部的
准备工作。Blender 的 `bpy.ops` 调用前后会更新 view layer;对约 1,744 个对象逐个调用
选择、修改器及模式切换会重复评估整个场景。实测原导出 173 秒中绝大部分用于更新,
采用以下边界后约 16 秒;不能全局 monkey-patch 或禁用 `_view_layer_update`。
- `select_only(obj)` 用选择数据 API;空修改器栈在改变上下文前直接返回。
- 原有修改器仅允许已证明局部的 `BEVEL` 进入预处理;其他类型保持原顺序回退。
- `batch_triangulate_meshes` 使用真正的 Triangulate 修改器及当前 Blender 默认值,
一次评估后通过 `new_from_object(..., preserve_all_data_layers=True)` 获取结果。
必须先收集所有结果,再替换原网格;替换/删除修改器会使 evaluated 数据失效。
共享、形状键、自定义法线、库链接、fake-user 保留网格不进入这个复制路径。
- `mesh_has_multiple_users` 按 Blender `ID_REAL_USERS` 判断:`users - int(use_fake_user)`。
对多个真实用户的网格,原修改器应用本来就失败,提前跳过保持原拓扑与共享关系。
- 缺 UV 的已准备网格在临时小场景逐对象调用原 `smart_project`,通过 `window.scene`
保持编辑模式上下文一致;有 UV 的模型资产不重展。退出必须恢复窗口场景和 view layer,
删除临时场景。无法满足条件时使用原操作路径。
验证使用 `blender/tools/check_export_preparation.py -- --baseline <original_export_cesium.py>`
在真实 Blender 内比对 control、共享网格、形状键、自定义法线、fake user、Bevel 和
Boolean 依赖回退。真实区域还必须比全部主/分类/动态 GLB 的结构摘要、解码后的索引、
坐标、UV、法线、切线、材质与贴图哈希。不要只用顶点数相同证明视觉一致。
Blender 4.5 的 Triangulate 默认 quad method 是 shortest diagonal,并非 BEAUTY。
直接换成 BMesh BEAUTY 会改变拆面和后续 UV,不能称为等价提速。任何替代算法必须先
核对源码默认值和属性转换路径。详见任务 `09-17-cesium-export-performance/research/`。
## 第三方资产导入的源文件边界
第三方 Blend 只属于一次性入库工具的输入,不能成为 `build:area` 或 Cesium 预览的运行时依赖。
@@ -0,0 +1,4 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
{"file":".trellis/spec/blender/asset-generation.md","reason":"Asset compatibility"}
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"Parity acceptance"}
{"file":".trellis/tasks/09-17-cesium-export-performance/research/triangulation-semantics.md","reason":"Source-backed optimization correctness"}
@@ -0,0 +1,15 @@
# Design
## Evidence and theory
Baseline profiler: 179.6 s total, 166 s in 6,917 automatic view-layer updates; all eight exports 4.4 s. Blender `bpy/ops.py` updates the view layer before and after operators. Object-local mesh preparation should not repeatedly evaluate unrelated scene objects. Modifier evaluation may depend on scene relations, so disabling update globally is unacceptable.
A previous direct-BMesh experiment used BEAUTY for quads, unlike Blender's Triangulate modifier SHORTEDGE default. Both use BM_mesh_triangulate. Match parameters and mesh attribute conversion before accepting a direct path; retain original behavior for shared meshes and unsupported custom data. Research official modifier conversion code to explain residual differences.
## Implementation boundaries
Only exporter mesh preparation plus focused verification tools. Early-return for no-op work before selecting objects. Prefer public data APIs for object-local operations; preserve scene evaluation for actual dependent modifiers. Keep original triangulation modifier semantics via batched evaluation if direct BMesh cannot prove equivalence. No monkeypatching Blender internals in production.
## Compatibility and rollback
Same CLI, completion markers, GLB set, ordering, metadata, materials, and source blend. Validation uses temporary output directories. Reject alternatives that alter geometry/UV/normals without an explained contract. Each optimization separately measurable and removable. Existing user changes outside the exporter remain untouched.
@@ -0,0 +1,4 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
{"file":".trellis/spec/blender/asset-generation.md","reason":"Deterministic assets and shared mesh contract"}
{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"Output parity and control requirements"}
{"file":".trellis/tasks/09-17-cesium-export-performance/research/triangulation-semantics.md","reason":"Official source proof and safe alternatives"}
@@ -0,0 +1,11 @@
# Execution
- [x] Preserve original exporter and repeat unmodified control on Nantaizi without profiler; baseline second real area.
- [x] Record Blender source/API proof for proposed replacement operations, including triangulation defaults and conversion flags.
- [x] Implement exporter optimization through Trellis implement agent; main agent owns measurement and independent artifact comparisons.
- [x] Validate all GLBs against baseline and control; compare decoded geometry/attributes/images when digest is insufficient.
- [x] Run real Blender edge fixtures and existing pure Python tests.
- [x] Run fresh final benchmarks and cross-agent check; fix any findings.
- [x] Record results/spec contracts and report measured gain plus limitations. No automatic commit.
User approval: previous turn proposed preserving assets while eliminating redundant updates/modifier work; current user explicitly approved, with theory required. This records that accepted scope rather than requesting approval again.
@@ -0,0 +1,25 @@
# Cesium 导出性能优化与产物一致性验证
## Goal
将 Cesium 导出阶段从约 150 秒降至接近 15–20 秒,保持全部资产与视觉语义。用户在性能诊断之后明确同意优化,并要求每项操作有理论依据。
## Requirements
- 每项优化对应测量热点、Blender API/源码依据及可证伪的验证。
- 保留主场景、分类资产、三个动态信号资产、材质、贴图、节点与地理锚点。
- 不全局关闭依赖图更新;保留涉及修改器依赖的正确评估。
- 不降低几何精度、不改材质、删资产或修改浏览器流程。
- 不覆盖用户现有工作区修改;性能及 parity 产物写临时目录。
## Acceptance Criteria
- [x] 同一输入、无 profiler 的前后基准,记录实际耗时与提升倍率;接近 10 倍是目标,不能牺牲正确性。
- [x] 全部 GLB 通过既有结构摘要契约;深入检查几何、UV、法线、切线及纹理,不能通过扩大忽略名单隐藏差异。
- [x] 至少两份真实区域输入及针对共享网格、无修改器、既有 UV 的 Blender 验证。
- [x] 未改动代码 control 复测;相关现有测试通过。
- [x] 理论依据、验证结果、限制记录到任务研究与长期规范。
## Results
Nantaizi 173.227 → 15.905 秒(10.89x);Fengshu 36.891–41.396 → 5.638 秒(6.54–7.34x)。全部结构摘要通过。Nantaizi 解码属性零差异;Fengshu 仅树冠切线存在未改代码 control 已复现的一个四位小数舍入步长波动。详见 `research/measurements.md`,未扩展项目忽略名单。
@@ -0,0 +1,74 @@
// Diagnostic: run from repository root with two export directory arguments.
// Strict 1e-6 comparison; known control noise is reported, never suppressed.
const fs = require('fs');
const path = require('path');
const assert = require('assert/strict');
const crypto = require('crypto');
const {digest} = require(path.join(process.cwd(), 'scripts/glb-digest'));
function glb(file) {
const data = fs.readFileSync(file);
let json, bin;
for (let i=12; i<data.length;) {
const len=data.readUInt32LE(i), type=data.readUInt32LE(i+4);
if(type===0x4e4f534a) json=JSON.parse(data.subarray(i+8,i+8+len));
if(type===0x004e4942) bin=data.subarray(i+8,i+8+len);
i+=8+len;
}
function accessor(id) {
const a=json.accessors[id];
assert(!a.sparse, 'sparse accessor unsupported');
const v=json.bufferViews[a.bufferView];
const n={SCALAR:1,VEC2:2,VEC3:3,VEC4:4,MAT4:16}[a.type];
const [bytes,fn]={5120:[1,'readInt8'],5121:[1,'readUInt8'],5122:[2,'readInt16LE'],5123:[2,'readUInt16LE'],5125:[4,'readUInt32LE'],5126:[4,'readFloatLE']}[a.componentType];
const out=[];
for(let i=0;i<a.count;i++) for(let j=0;j<n;j++) {
out.push(bin[fn]((v.byteOffset||0)+(a.byteOffset||0)+i*(v.byteStride||n*bytes)+j*bytes));
}
return out;
}
function imageHash(image) {
const v=json.bufferViews[image.bufferView];
return crypto.createHash('sha256').update(bin.subarray(v.byteOffset||0,(v.byteOffset||0)+v.byteLength)).digest('hex');
}
return {json, accessor, imageHash};
}
const [before,after]=process.argv.slice(2);
let failures=0;
for(const file of fs.readdirSync(before).filter(f=>f.endsWith('.glb')).sort()) {
const issues=[];
try {
const da=digest(path.join(before,file)), db=digest(path.join(after,file));
for(const d of [da,db]) {delete d.fileBytes;delete d.buffers;delete d.counts.accessors;}
try {assert.deepEqual(da,db);} catch {issues.push('structural digest differs');}
const a=glb(path.join(before,file)),b=glb(path.join(after,file));
for(const key of ['nodes','scenes','scene','materials','textures','samplers','animations','skins','extensions','extensionsUsed','extensionsRequired']) {
assert.deepEqual(a.json[key],b.json[key],key);
}
assert.equal(a.json.meshes.length,b.json.meshes.length);
let maxError=0;
for(let m=0;m<a.json.meshes.length;m++) {
const am=a.json.meshes[m],bm=b.json.meshes[m];
assert.equal(am.name,bm.name);
assert.equal(am.primitives.length,bm.primitives.length);
for(let p=0;p<am.primitives.length;p++) {
const ap=am.primitives[p],bp=bm.primitives[p];
assert.equal(ap.material,bp.material);
assert.deepEqual(Object.keys(ap.attributes),Object.keys(bp.attributes));
for(const key of ['indices',...Object.keys(ap.attributes)]) {
const av=a.accessor(key==='indices'?ap.indices:ap.attributes[key]);
const bv=b.accessor(key==='indices'?bp.indices:bp.attributes[key]);
if(av.length!==bv.length) {issues.push(`${am.name}/${p}/${key}: count ${av.length} -> ${bv.length}`);continue;}
let error=0;
for(let i=0;i<av.length;i++) error=Math.max(error,Math.abs(av[i]-bv[i]));
maxError=Math.max(maxError,error);
if(error>(key==='indices'?0:1e-6)) issues.push(`${am.name}/${p}/${key}: max delta ${error}`);
}
}
}
assert.equal(a.json.images?.length||0,b.json.images?.length||0);
for(let i=0;i<(a.json.images||[]).length;i++) assert.equal(a.imageHash(a.json.images[i]),b.imageHash(b.json.images[i]));
console.log(file, issues.length?'FAIL':'PASS', 'max attribute delta',maxError,issues.slice(0,12));
} catch(e) {issues.push(e.message);console.log(file,'ERROR',e.message.slice(0,500));}
if(issues.length) failures++;
}
process.exitCode=failures?1:0;
@@ -0,0 +1,48 @@
# Performance and parity evidence (2026-09-17)
Environment: local Blender 4.5.12, same existing `.blend` per region, serial runs, all outputs in `/private/tmp/cesium-profile.9ODFNa`. Original exporter preserved there as `original_export_cesium.py`. No source scene or existing output overwritten.
## Measurements
| Input / implementation | Export function wall time |
| --- | ---: |
| Nantaizi original cProfile | 179.596 s |
| Nantaizi original control without profiler | 173.227 s |
| Nantaizi initial production candidate | 33.389 s |
| Nantaizi candidate with shared-mesh guards | 15.337 s |
| Nantaizi final fake-user guard correction | 15.905 s |
| Fengshu original | 41.396 s |
| Fengshu original second control | 36.891 s |
| Fengshu optimized | 5.527 s |
| Fengshu final fake-user guard correction | 5.638 s |
Time excludes Blender process startup; `measure.py` uses perf_counter around export() and per-function timing wrappers, no cProfile. Inputs/outputs and eight/seven export calls unchanged. Final Nantaizi speedup 10.89x; Fengshu 6.54–7.34x. Final Nantaizi eight GLBs again pass with zero decoded attribute delta. Both regions' metadata matches after normalizing output directory prefixes.
## Nantaizi parity
Unchanged control compared with original profiler output: all eight GLBs have identical project structural digests (existing unstable fields excluded), decoded indices/positions/UVs/normals/tangents/other attributes, full nodes/scenes/materials/textures/samplers and embedded image hashes. Maximum numeric delta 0. Initial and shared-guard production candidates both pass these exact comparisons.
## Fengshu control noise
All seven project structural digests match. Six GLBs' decoded attributes also match exactly. `vegetation.glb`, mesh `Tree_Natural_Crowns_DarkMesh`, TANGENT values vary by at most 0.00010001659393310547 between two **unmodified** runs. Optimized versus first baseline has the same maximum; versus second baseline 0.00010000169277191162. Positions, UVs, normals, indices, other meshes and embedded images match. This is not a broad tolerance waiver.
Installed `io_scene_gltf2/blender/exp/primitive_extract.py:1507` rounds tangents to `ROUNDING_DIGIT`, defined as 4 in `io/com/constants.py:159`. A 0.0001 difference is one exporter quantization step. Existing project digest ignores accessor/buffer layout noise, but no project ignore list was expanded for this work.
## Edge fixtures
`blender/tools/check_export_preparation.py` passed in real Blender using original exporter as reference and an unchanged control. Includes asymmetric quad/ngon triangle counts, authored UVs, shared meshes, custom normals, shape keys, Bevel, dependent Boolean, and fake retention user. Compares topology/vertex order/UV/normals/material slots/mesh names/custom properties/sharing/remaining modifiers. Uses 1e-6 numerical tolerance.
Independent review moved edit-mode selection into the cleanup try/finally and added an injected UV failure fixture asserting restoration of original scene/view layer/collection links and no scene leak. Expanded fixture passed after review. All 64 existing pure Python tests, Python compilation and `git diff --check` pass. No project Python lint/type-check configuration exists. No UI screenshot claim: visual semantics checked through decoded render attributes and identical image bytes; no browser rendering code changed.
Reproducible strict comparison: from repo root run `node .trellis/tasks/09-17-cesium-export-performance/research/compare-glb.cjs <baseline-directory> <candidate-directory>`. It reports the Fengshu control tangent noise as a failure at 1e-6, deliberately not masking it. Classify that one known result using the unchanged control evidence above; all project structural digest checks pass.
## Source-backed choices
- Public selection data API avoids operator entry/exit graph updates.
- Empty modifier stack returns before any selection/update.
- Same Triangulate modifier is evaluated in a batch; evaluated meshes copied before mutating original data; preserve all data layers. No BMesh approximation.
- Same UV operator runs one object at a time in a small temporary scene, switched through actual window.scene; normal graph updates stay enabled.
- Shared triangulation skipped using `ID_REAL_USERS = users - fake_user`, matching Blender's failure precondition.
- Unknown modifier stacks retain original ordering; no global monkey patch.
Failed temp_override-only UV investigation was stopped because Blender edit-mode poll requires consistent window scene context; production uses a real temporary scene/window switch instead. Diagnostic global update suppression and mismatched direct-BMesh experiment are not in production.
@@ -0,0 +1,82 @@
# Research: Triangulation semantics and output-preserving optimization
- Query: Explain the temporary direct-BMesh experiment's different GLB vertex counts and identify source-backed faster alternatives.
- Scope: mixed (project source, installed exporter, official Blender 4.5.0 source)
- Date: 2026-09-17
## Findings
### Confirmed algorithm mismatch in the experiment
`blender/export_cesium.py:531` creates a Triangulate modifier and only overrides `min_vertices = 4`. The temporary `/private/tmp/cesium-profile.9ODFNa/profile_export.py:42` instead passes `quad_method='BEAUTY', ngon_method='BEAUTY'` to BMesh.
Blender **4.5.0** `source/blender/makesdna/DNA_modifier_defaults.h:643-649` defines the modifier defaults as:
```
flag = 0
quad_method = MOD_TRIANGULATE_QUAD_SHORTEDGE
ngon_method = MOD_TRIANGULATE_NGON_BEAUTY
min_vertices = 4
```
Thus the experiment is not algorithm-equivalent: quads use shortest diagonal in the baseline and beauty in the experiment. This is a concrete reason to correct the experiment, not speculative parameter tuning. Do not rely on older Blender documentation's defaults; read a temporary modifier's RNA properties on the actual running version if supporting multiple Blender versions.
Both routes ultimately call `BM_mesh_triangulate` (official `MOD_triangulate.cc`, `bmo_triangulate.cc:29-44`). The modifier passes `tag_only=false`; the BMesh operator tags its supplied faces and passes `tag_only=true`. Supplying all eligible faces and matching quad/ngon methods aligns the core algorithm.
### Why GLB vertex counts can differ with equal triangles
Installed `/Applications/Blender.app/Contents/Resources/4.5/scripts/addons_core/io_scene_gltf2/blender/exp/primitive_extract.py:336-344` explicitly explains that Blender corner attributes are packed into per-vertex records for glTF. Deduplication at lines 825 and 900-901 uses the attribute record, not position alone. Normals, tangents and UV discontinuities therefore split vertices without changing triangle count. Changing the quad diagonal can change subsequent normals and UV unwrap even when all positions and triangle totals remain unchanged.
Project preparation order (`blender/export_cesium.py:670-676`) is triangulate then unwrap. Hence changing topology before `smart_project` can also change UV islands. Counts alone do not establish visual parity or identify which attribute actually changed in the existing artifacts; inspect decoded attribute arrays per mesh to attribute the observed count difference definitively.
### Remaining BMesh conversion differences
Official `MOD_triangulate.cc` sets `calc_face_normal=true`, `calc_vert_normal=false` and carries original-index custom-data masks through conversion. Python `BMesh.from_mesh` (`bmesh_py_types.cc:1376-1414`) defaults both normal flags to true; pass `face_normals=True, vertex_normals=False` to match the modifier's inputs more closely.
Modifier `flag=0` means **keep_custom_normals is false by default in 4.5.0**. Therefore do not claim custom-normal preservation is the established reason for this scene's discrepancy. If enabled, the modifier explicitly copies evaluated corner normals into a temporary CD_NORMAL layer and restores normalized custom normals after triangulation. Direct BMesh does not reproduce that explicit procedure automatically.
Python `BMesh.to_mesh` (`bmesh_py_types.cc:1201-1240`) uses `BM_mesh_bm_to_me`, updates shape-key indices/object remaps and tags geometry dirty; modifier output uses `BKE_mesh_from_bmesh_for_eval_nomain`. These are distinct conversion paths. Matching triangulation settings does not constitute a proof of byte-identical mesh output, ordering or custom data. Preserve the baseline fallback for multi-user meshes (`modifier_apply` refuses them); do not change shared topology as a performance side effect.
### Strongest semantic route: keep the actual modifier, batch evaluation
For simple single-user meshes without pre-existing modifiers or shape keys, add the same Triangulate modifier through the data API for all eligible objects, evaluate the dependency graph once, then obtain persistent meshes with `bpy.data.meshes.new_from_object(obj.evaluated_get(depsgraph), preserve_all_data_layers=True, depsgraph=depsgraph)`. Stage every result before replacing source data/removing modifiers, because mutation can invalidate evaluated state. This executes the actual modifier implementation instead of duplicating it in Python.
Official `rna_main_api.cc:1103-1123` says an original object produces undeformed geometry while an evaluated object produces final geometry with all modifiers; preserving all data layers requires a dependency graph. Official `rna_ID.cc:2447-2452` says `evaluated_get` only retrieves the **last** evaluation and does **not** ensure the graph is up to date. An explicit graph evaluation barrier after adding modifiers is mandatory; repeated evaluation per object defeats the optimization.
Limit this fast path to proven equivalent cases. Existing modifier stacks, hidden modifiers, failing modifiers, shape keys, shared meshes and inter-object dependencies are not generally equivalent to the current sequential `modifier_apply` loop. Keep the existing operator fallback for those cases until separately justified. New datablocks must preserve material slots, required custom properties and semantic names; parity must detect unintended instance splitting or GLB naming differences.
### Recommended decision
1. Correct the demonstrated quad-method mismatch before drawing conclusions from direct-BMesh measurements.
2. Prefer batched evaluation of the original modifier if exact parity remains the requirement; its geometric semantics have a stronger equivalence basis.
3. Keep graph updates at real dependency boundaries; never ship the temporary global `_view_layer_update` monkey patch.
4. Require decoded triangle attributes and existing project structure parity, including UVs/normals/tangents and dynamic/shared assets. Do not accept matching counts as sufficient evidence.
## Files found
- `blender/export_cesium.py` — preparation order and baseline modifier/UV operations.
- `/private/tmp/cesium-profile.9ODFNa/profile_export.py` — temporary monkey-patch and direct-BMesh experiment.
- `/Applications/Blender.app/Contents/Resources/4.5/scripts/addons_core/io_scene_gltf2/blender/exp/primitive_extract.py` — glTF corner-attribute splitting and deduplication.
## External references
All source references pinned to Blender `v4.5.0`:
- https://github.com/blender/blender/blob/v4.5.0/source/blender/makesdna/DNA_modifier_defaults.h#L643
- https://github.com/blender/blender/blob/v4.5.0/source/blender/modifiers/intern/MOD_triangulate.cc
- https://github.com/blender/blender/blob/v4.5.0/source/blender/bmesh/operators/bmo_triangulate.cc
- https://github.com/blender/blender/blob/v4.5.0/source/blender/python/bmesh/bmesh_py_types.cc#L1376
- https://github.com/blender/blender/blob/v4.5.0/source/blender/makesrna/intern/rna_main_api.cc#L1103
- https://github.com/blender/blender/blob/v4.5.0/source/blender/makesrna/intern/rna_ID.cc#L2447
## Related specs
- `.trellis/spec/blender/index.md` — Blender/standard-Python boundary and parity requirements.
- `.trellis/spec/blender/asset-generation.md` — deterministic geometry, shared meshes and dynamic export assets.
- `.trellis/spec/blender/testing.md` — mathematical expectations and real Blender parity.
## Caveats / Not Found
- Research only: no Blender runs or changes to product code were performed.
- The algorithm mismatch is proven from source; the exact per-attribute cause of every previously observed vertex-count change is not measured here.
- Batch evaluated-mesh conversion is a source-backed candidate, not a claim of verified output parity or measured speedup.
@@ -0,0 +1,26 @@
{
"id": "cesium-export-performance",
"name": "cesium-export-performance",
"title": "Cesium 导出性能优化与产物一致性验证",
"description": "",
"status": "in_progress",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-17",
"completedAt": null,
"branch": null,
"base_branch": "experiment/road-compiler-rethink",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": null,
"relatedFiles": [],
"notes": "",
"meta": {}
}
+138 -11
View File
@@ -496,6 +496,14 @@ def make_export_material(material):
return result
def select_only(obj):
"""Change selection without an operator's scene-evaluation barriers."""
for selected in bpy.context.selected_objects:
selected.select_set(False)
obj.select_set(True)
bpy.context.view_layer.objects.active = obj
def unwrap_mesh(obj):
if obj.type != "MESH" or not obj.data.polygons:
return
@@ -504,23 +512,19 @@ def unwrap_mesh(obj):
# meshes arrive without a UV layer, so that is the reliable discriminator.
if obj.data.uv_layers:
return
bpy.ops.object.select_all(action="DESELECT")
obj.select_set(True)
bpy.context.view_layer.objects.active = obj
select_only(obj)
bpy.ops.object.mode_set(mode="EDIT")
bpy.ops.mesh.select_all(action="SELECT")
try:
bpy.ops.mesh.select_all(action="SELECT")
bpy.ops.uv.smart_project(island_margin=0.025, area_weight=0.0)
finally:
bpy.ops.object.mode_set(mode="OBJECT")
def apply_mesh_modifiers(obj):
if obj.type != "MESH":
if obj.type != "MESH" or not obj.modifiers:
return
bpy.ops.object.select_all(action="DESELECT")
obj.select_set(True)
bpy.context.view_layer.objects.active = obj
select_only(obj)
for modifier in list(obj.modifiers):
try:
bpy.ops.object.modifier_apply(modifier=modifier.name)
@@ -528,6 +532,11 @@ def apply_mesh_modifiers(obj):
pass
def mesh_has_multiple_users(mesh):
# modifier_apply uses ID_REAL_USERS, excluding the fake retention user.
return mesh.users - int(mesh.use_fake_user) > 1
def triangulate_mesh(obj):
"""Split n-gons into triangles ahead of the exporter.
@@ -544,11 +553,14 @@ def triangulate_mesh(obj):
"""
if obj.type != "MESH" or not obj.data.polygons:
return
# modifier_apply rejects multi-user data before evaluating geometry. Avoid
# creating a modifier and evaluating the whole scene only to remove it in
# the failure handler below; keeping this mesh unchanged is intentional.
if mesh_has_multiple_users(obj.data):
return
if all(len(polygon.vertices) <= 3 for polygon in obj.data.polygons):
return
bpy.ops.object.select_all(action="DESELECT")
obj.select_set(True)
bpy.context.view_layer.objects.active = obj
select_only(obj)
modifier = obj.modifiers.new("ExportTriangulate", "TRIANGULATE")
modifier.min_vertices = 4
try:
@@ -559,6 +571,120 @@ def triangulate_mesh(obj):
obj.modifiers.remove(modifier)
def batch_triangulate_meshes(candidates):
"""Evaluate independent Triangulate modifiers in one dependency graph pass.
This uses the actual modifier (including the running Blender version's
defaults), not a BMesh reimplementation. new_from_object on an evaluated
object copies its final geometry; preserve_all_data_layers retains UVs and
other mesh attributes. Stage every result before editing original objects:
assigning data or removing a modifier invalidates evaluated state.
Existing stacks can depend on other objects' unmodified geometry. Leave
their sequential application order untouched, including stacks outside the
export subset. Multi-user meshes, shape keys and custom normals retain the
original operator path, whose restrictions are part of the export behavior.
"""
if any(obj.modifiers for obj in bpy.context.scene.objects):
return
pending = []
for obj in candidates:
mesh = obj.data
if (mesh.users != 1 or mesh.use_fake_user or mesh.shape_keys
or mesh.has_custom_normals or mesh.library or obj.library
or not any(len(p.vertices) > 3 for p in mesh.polygons)):
continue
modifier = obj.modifiers.new("ExportTriangulate", "TRIANGULATE")
modifier.min_vertices = 4
pending.append((obj, mesh, modifier))
if not pending:
return
staged = []
try:
# evaluated_get itself does not update the graph. This explicit barrier
# is required after adding all modifiers, and is intentionally not
# repeated for each object.
depsgraph = bpy.context.evaluated_depsgraph_get()
depsgraph.update()
for obj, source, modifier in pending:
mesh = bpy.data.meshes.new_from_object(
obj.evaluated_get(depsgraph), preserve_all_data_layers=True,
depsgraph=depsgraph)
staged.append((obj, source, modifier, mesh))
for key in source.keys():
mesh[key] = source[key]
except Exception:
for _, _, _, mesh in staged:
bpy.data.meshes.remove(mesh)
for obj, _, modifier in pending:
obj.modifiers.remove(modifier)
raise
for obj, source, modifier, mesh in staged:
name = source.name
obj.data = mesh
obj.modifiers.remove(modifier)
bpy.data.meshes.remove(source)
mesh.name = name
def unwrap_meshes_in_work_scene(candidates):
"""Run the unchanged per-object UV operator against a small scene.
UV projection operates on the original mesh in edit mode, not evaluated
scene geometry. Link the original object into a temporary scene one at a
time so operator barriers do not reevaluate every unrelated scene object.
Switch the window's scene, not just context object overrides: edit-mode
operators require a consistent window/scene/view-layer context.
"""
window = bpy.context.window
if window is None or any(obj.modifiers for obj in bpy.context.scene.objects):
return
# A later fallback triangulation must precede UV projection. Shared meshes
# are also safe here: modifier_apply refuses them, so their topology stays
# unchanged in the original preparation loop.
pending = [obj for obj in candidates if not obj.modifiers
and not obj.data.uv_layers and obj.data.polygons
and (mesh_has_multiple_users(obj.data)
or all(len(p.vertices) <= 3 for p in obj.data.polygons))]
if not pending:
return
original_scene = window.scene
original_layer = window.view_layer
work_scene = bpy.data.scenes.new("Cesium UV work scene")
try:
window.scene = work_scene
for obj in pending:
# Shared mesh UVs are already prepared by their first instance.
if obj.data.uv_layers:
continue
work_scene.collection.objects.link(obj)
try:
unwrap_mesh(obj)
finally:
work_scene.collection.objects.unlink(obj)
finally:
window.scene = original_scene
window.view_layer = original_layer
bpy.data.scenes.remove(work_scene)
def prepare_independent_meshes(candidates):
"""Keep dependency-bearing modifier stacks on the sequential legacy path."""
# Bevel reads this object's geometry and vertex groups. Unlike Boolean,
# Shrinkwrap or Geometry Nodes it cannot read another object's mesh. Apply
# it with the original operator before batching independent triangulation.
# Unknown stack types deliberately keep the original preparation order.
if any(modifier.type != "BEVEL"
for obj in bpy.context.scene.objects for modifier in obj.modifiers):
return
for obj in candidates:
apply_mesh_modifiers(obj)
batch_triangulate_meshes(candidates)
unwrap_meshes_in_work_scene(candidates)
def export_glb(filepath, meshes):
"""Export a prepared object subset without changing authoring visibility."""
bpy.ops.object.select_all(action="DESELECT")
@@ -654,6 +780,7 @@ def export(args):
and not obj.hide_viewport and not obj.hide_render]
total_candidates = max(1, len(candidates))
progress.update("prepare scene", 3, "%d mesh objects" % len(candidates))
prepare_independent_meshes(candidates)
for index, obj in enumerate(candidates, 1):
if any(c.name == "06_TrafficSignalsDynamic" for c in obj.users_collection):
groups = {slot.material.name for slot in obj.material_slots if slot.material}
+177
View File
@@ -0,0 +1,177 @@
"""Compare exporter preparation against a supplied original in real Blender.
blender --background --factory-startup --python this_file.py -- \
--baseline /absolute/path/to/original_export_cesium.py
The fixture combines asymmetric quads, n-gons, authored UVs, shared meshes,
custom normals, shape keys and Bevel. A separate Boolean scenario exercises
the dependency-bearing fallback. Expected triangle totals follow n - 2;
attribute/ordering comparisons use the original exporter as an independent
reference, including an unchanged-code control run.
"""
import argparse
import importlib.util
import math
from pathlib import Path
import sys
import bpy
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
def load_exporter(name, path):
spec = importlib.util.spec_from_file_location(name, path)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
def fixture(dependent):
bpy.ops.wm.read_factory_settings(use_empty=True)
material = bpy.data.materials.new("Fixture material")
objects = []
def mesh_object(name, vertices, faces):
mesh = bpy.data.meshes.new(name + " mesh")
mesh.from_pydata(vertices, [], faces)
mesh.materials.append(material)
mesh["fixture_property"] = "preserved"
obj = bpy.data.objects.new(name, mesh)
bpy.context.scene.collection.objects.link(obj)
objects.append(obj)
return obj
quad = [(0, 0, 0), (3, 0, 0), (2, 1, 0), (0, 2, 0)]
mesh_object("quad", quad, [(0, 1, 2, 3)])
mesh_object("ngon", quad + [(-1, 1, 0)], [(0, 1, 2, 3, 4)])
authored = mesh_object("authored", quad, [(0, 1, 2, 3)])
uv = authored.data.uv_layers.new(name="Authored UV")
for loop, value in zip(uv.data, [(0, 0), (.9, .1), (.6, .8), (.1, 1)]):
loop.uv = value
shared = mesh_object("shared", quad, [(0, 1, 2, 3)])
instance = bpy.data.objects.new("shared instance", shared.data)
bpy.context.scene.collection.objects.link(instance)
objects.append(instance)
mesh_object("triangle", quad[:3], [(0, 1, 2)])
custom = mesh_object("custom normals", quad, [(0, 1, 2, 3)])
custom.data.normals_split_custom_set([(0, .2, 1)] * 4)
keyed = mesh_object("shape keys", quad, [(0, 1, 2, 3)])
keyed.shape_key_add(name="Basis")
keyed.shape_key_add(name="Raised").data[0].co.z = .25
bevel = mesh_object("bevel", quad, [(0, 1, 2, 3)])
modifier = bevel.modifiers.new("Fixture bevel", "BEVEL")
modifier.width = .16
modifier.segments = 2
retained = mesh_object("fake user", quad, [(0, 1, 2, 3)])
retained.data.use_fake_user = True
if dependent:
boolean = objects[0].modifiers.new("Dependent Boolean", "BOOLEAN")
boolean.object = authored
return objects
def digest(objects):
return [{
"name": obj.name,
"mesh": obj.data.name,
"users": obj.data.users,
"properties": dict(obj.data.items()),
"vertices": [tuple(v.co) for v in obj.data.vertices],
"polygons": [tuple(p.vertices) for p in obj.data.polygons],
"smooth": [p.use_smooth for p in obj.data.polygons],
"normals": [tuple(n.vector) for n in obj.data.corner_normals],
"uv": {uv.name: [tuple(v.uv) for v in uv.data]
for uv in obj.data.uv_layers},
"materials": [m.name if m else None for m in obj.data.materials],
"modifiers": [(m.name, m.type) for m in obj.modifiers],
"shape_keys": ([key.name for key in obj.data.shape_keys.key_blocks]
if obj.data.shape_keys else []),
} for obj in objects]
def prepare(module, dependent, optimized):
objects = fixture(dependent)
if optimized:
module.prepare_independent_meshes(objects)
seen = set()
for obj in objects:
module.apply_mesh_modifiers(obj)
if obj.data.name not in seen:
seen.add(obj.data.name)
module.triangulate_mesh(obj)
module.unwrap_mesh(obj)
assert objects[3].data is objects[4].data, "shared mesh was split"
if not dependent:
assert len(objects[0].data.polygons) == 2, "quad must give n - 2 triangles"
assert len(objects[1].data.polygons) == 3, "pentagon must give n - 2 triangles"
return digest(objects)
def compare(expected, actual, path="root"):
if isinstance(expected, dict):
assert expected.keys() == actual.keys(), path
for key in expected:
compare(expected[key], actual[key], path + "." + str(key))
elif isinstance(expected, (list, tuple)):
assert len(expected) == len(actual), (path, len(expected), len(actual))
for index, (left, right) in enumerate(zip(expected, actual)):
compare(left, right, path + "[%d]" % index)
elif isinstance(expected, float):
assert math.isclose(expected, actual, rel_tol=0, abs_tol=1e-6), (
path, expected, actual)
else:
assert expected == actual, (path, expected, actual)
def check_work_scene_cleanup(module):
objects = fixture(False)
triangle = objects[5]
original_scene = bpy.context.window.scene
original_layer = bpy.context.window.view_layer
scene_names = set(bpy.data.scenes.keys())
collections = tuple(triangle.users_collection)
unwrap = module.unwrap_mesh
def fail_unwrap(obj):
assert bpy.context.scene != original_scene
assert obj == triangle
raise RuntimeError("fixture UV failure")
module.unwrap_mesh = fail_unwrap
# Remove the Bevel so this specifically exercises the scratch-scene path.
objects[8].modifiers.clear()
try:
try:
module.unwrap_meshes_in_work_scene([triangle])
except RuntimeError as error:
assert str(error) == "fixture UV failure"
else:
raise AssertionError("fixture failure was swallowed")
finally:
module.unwrap_mesh = unwrap
assert bpy.context.window.scene == original_scene
assert bpy.context.window.view_layer == original_layer
assert set(bpy.data.scenes.keys()) == scene_names
assert tuple(triangle.users_collection) == collections
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--baseline", required=True)
args = parser.parse_args(sys.argv[sys.argv.index("--") + 1:])
original = load_exporter("original_exporter", args.baseline)
optimized = load_exporter("optimized_exporter", ROOT / "export_cesium.py")
for dependent in (False, True):
reference = prepare(original, dependent, False)
compare(reference, prepare(original, dependent, False), "control")
compare(reference, prepare(optimized, dependent, True), "optimized")
check_work_scene_cleanup(optimized)
print("EXPORT_PREPARATION_CHECK_OK: control, independent and dependent fixtures")
if __name__ == "__main__":
main()