# 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`) 现状是裸导出: ```python 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 会**直接加载失败**。补: ```js 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 改动。