Files
cad-building-showcase/references/optimization_notes.md

8.0 KiB
Raw Blame History

Skill 优化建议(来自主辅楼建筑群 11 张图实战复盘)

Contents

  1. Lightweighting
  2. Up-axis contract
  3. Geometry completeness
  4. Robustness
  5. QA
  6. Portability
  7. Reusable artifacts

本文记录在一次完整实战(A202/A205/A208–A213 共 11 张 CAD 平面图 → 轻量化 Web 展示模型)中暴露的问题与已验证的修复,作为对 skill 脚本与模板的具体改进建议。修复均已在该项目落地验证。


0. 一句话结论

  • 轻量化的关键 = Draco 压缩 + 查看器挂 DRACOLoader(成对),实测体积 ~3–4MB → ~0.4–0.6MB(−92%)。
  • 最该修的潜在 bug = glTF 上方向约定不统一(模板按 Z-up 写,Blender 默认导出 Y-up),会让建筑“躺倒”。
  • 几何完整性(块内幕墙、玻璃连续、柱头封顶、地下室顶板)需要新增专门步骤,CAD 平面图本身不会自动给出这些。

1. 轻量化(最高优先级)

1.1 GLB 压缩(build_blender_showcase.py)

现状是裸导出:

bpy.ops.export_scene.gltf(filepath=str(glb_path), export_format="GLB")

建议二选一:

  • Blender 自带 Draco:export_draco_mesh_compression_enable=True, export_draco_mesh_compression_level=6。
  • 更彻底(推荐):导出后跑 gltf-transform,顺序 weld → dedup → prune → draco(quantizePosition=14, quantizeNormal=10, quantizeGeneric=12)。本项目用的 node 脚本见 tools/compress.mjs(可随 skill 附带)。

1.2 查看器必须挂解码器(assets/web-showcase-template/app.js)

模板只有 new GLTFLoader(),压了 Draco 会直接加载失败。补:

import { DRACOLoader } from "three/addons/loaders/DRACOLoader.js";
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath("./node_modules/three/examples/jsm/libs/draco/"); // three 自带,离线可用
loader.setDRACOLoader(dracoLoader);

npm install three 已含解码器 wasm,无需 CDN。

1.3 变体即 LOD

overview/standard/detail 按构件类别过滤(现有机制即可),默认 standard。若要再轻,可对 overview 做几何减面(当前仅图层过滤,不是真减面)。


2. 上方向约定(潜在严重 bug,强烈建议修)

模板 app.js 通篇按 Z 为上写:group.position.z(楼层展开)、new THREE.Plane(new THREE.Vector3(0,0,-1))(剖切)、相机 center.z + maxSize。但 bpy.ops.export_scene.gltf 默认 export_yup=True,导出的是 Y-up。两者不一致 → 建筑在 three / Blender / 任何标准查看器里躺倒。

建议锁死标准 Y-up:

  • GLB 保持 Y-up(Blender 默认即可;纯 Python 后端需显式把 Z-up 旋到 Y-up:(x,y,z)->(x,z,-y))。
  • 查看器:
    • camera.up.set(0,1,0)(否则 OrbitControls 的 maxPolarAngle 会把相机钳在近水平轨道,俯视/鸟瞰放不开——这是另一个隐藏坑)。
    • 剖切面法线 (0,-1,0);楼层展开走 .y;相机预设 top/side/overview 按 Y-up 重写。

3. 几何完整性(CAD 平面图 → 体量模型新增步骤)

3.1 块内几何要定向展开(已升级为按图层探测)

幕墙/门窗常封装在 INSERT 块里。本项目玻璃在 系统嵌板 - SZ_玻璃…、幕墙平拼… 块内,展开后落在图层 A-GLAZ-CURT。按块名定向展开(["*幕墙*","*玻璃*","*嵌板*","*GLAZ*","*CURT*"])是第一道防线,但实战证明块名匹配不可靠:

  • DWG→DXF 转换会损坏中文块名(系统嵌板→系统嵌、偏移→偏),模式匹配不上;
  • 幕墙嵌板常套在排版/包裹块里,父块名不命中就永远扫不到内层。

derive_showcase_spec.py 现已内置按块内实体图层分类(classify_block_contents,默认开):展开所有 INSERT 到 expand_blocks_max_depth,只保留自身图层能归类到 block_content_categories(默认 glazing/railings/doors)的子实体。配套的 audit_showcase_extraction.py 增加了:

  • 块内锁定几何统计(与配置无关的全量展开核算),96% 覆盖率再也藏不住整面幕墙缺失;
  • glazing 硬门禁:图中存在幕墙证据(块内玻璃图层长度 / 幕墙命名块)而 spec glazing=0 时审计直接 FAIL(exit 3)。

另外 *-IDEN 标识图层(A-DOOR-IDEN 等)默认排除出分类(exclude_layers),门标号不再被当成门几何;cad_dxf_report.py 会在建模前对 XREF 空壳图(如本项目 A212/A214/A215/A216)输出 likely_xref_shell 警告。回归测试见 tests/test_extraction_pipeline.py。

3.2 立面玻璃连续化

CAD 把幕墙画成稀疏分格板(实测 8F:1.42m 板 / 每 4.5m 一块 / 中间 3.08m 空)。逐段挤出 = 隔空竖条。需做共线合并 + 桥接窗间缝:按 (角度, 垂距) 分组,沿线方向合并区间,gap_tol 取得比窗间缝大(本项目 3.6m)即连成整条玻璃带。注意先确认缝里没有墙(本项目实测该立面墙长 0m)再桥接,避免把实墙盖成玻璃。

3.3 柱头封顶(比 shorten_unsupported_columns 更好)

现有的“无支撑柱缩短”会产生突兀的 1.2m 矮柱。更自然的做法是生成盖板:

  • 地上退台层:cap = 本层footprint(外扩cap_buffer) − 上层footprint,在 z+h 处挤薄板(退台屋面/雨棚)。普通立面默认 0.1m;A208 的外圈柱廊有图纸佐证,才显式使用约 1.3m。
  • 地下室顶层:直接把整层 footprint 在 z=0 封成地面/顶板(停车区上方的地坪)。
  • 顶层(8F)/辅楼顶:用现有 roof_specs 屋顶盖。

3.4 ⚠ floor_group 的 bug

build_blender_showcase.py 的 floor_group() 把 B1/B1M 归 BASE、地上归 MAIN、AUX_ 归 AUX,柱支撑/封顶只在同组内找上层。结果:地下室顶层(B1M)永远找不到地上的 1F 作为上层,拿不到顶板——本项目 983 根地下柱有 397 根(40%)露顶。修复:地下室顶层特判为“整层封顶”,或允许跨组找上方 footprint。


4. 健壮性

  • 生成的盖板(shapely 差集)可能产生退化/狭长面 → 法线 NaN → Blender 导入报 Bad glTF: json contained NaN。导出前必须:丢弃零面积面(area>1e-9)+ 钳 NaN/Inf 法线(置默认向上)。
  • 检查顶点 isfinite,跳过非法网格。

5. 验证 / QA(应做成标准动作)

这次定位问题全靠这些,建议固化进 skill 验证步骤:

  • 正交立面 + 顶视渲染:一眼看出整层缺失、躺倒、退台是否合理。
  • 覆盖率叠合图(draw_coverage_overlay.py 已有):红虚线=未提取,客观回答“是否缺料”。本项目支持长度覆盖率 96%。
  • 量化报告:柱头封顶率、玻璃连续段数变化、各变体 GLB 体积预算(如 overview ≤ 0.5MB)。
  • 早验证原则:生成后立即开查看器/渲立面再下结论。本次迭代 8 版的主要原因是“先猜后验”(误判朝向、误判窗间缝是墙),早点眼见为实可省大量来回。

6. 环境 / 可移植性

  • skill 硬依赖 Blender + dwg2dxf;受限沙箱(无 root、无 Blender、PyPI 无 bpy)两者皆无。建议:
    1. 文档明确宿主机前置条件;
    2. 提供纯 Python 后端(trimesh + gltf-transform)作为无 Blender 的可移植替代——本项目即用它跑通全流程(见 spec_to_glb.py),且天然产出轻量化 GLB;
    3. 无转换器时优雅回退到“请用户提供 DXF”。
  • Web 输出加 cache-busting(?v= 或内容哈希)+ 可见构建版本号:浏览器对 ES 模块/GLB 缓存极顽固,否则用户刷新看不到更新(本次踩坑多轮)。

7. 可直接并入 skill 的产物

本项目沉淀、建议提升为 skill 资源:

  • spec_to_glb.py:无 Blender 的 spec→GLB 导出器(含 z 窗口、segment 棱柱、footprint 楼板、玻璃共线合并、退台/地下封顶、Y-up、NaN 清洗、楼层__类别 命名)。
  • tools/compress.mjs:gltf-transform Draco 压缩脚本。
  • app.js 的 DRACOLoader + Y-up 改动。