Initial commit: cad-building-showcase skill
Agent-led CAD-drawing → 3D web showcase pipeline. Inspects CAD reports, maps layers/floors, extracts a normalized building spec (with block-probed glazing and audit gates), builds Blender/trimesh GLB variants, and assembles a Three.js web viewer. Includes XREF-shell detection and a regression test. Large inputs/outputs (work/, outputs/, source_cad/, renders) are gitignored. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
112
references/optimization_notes.md
Normal file
112
references/optimization_notes.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# Skill 优化建议(来自主辅楼建筑群 11 张图实战复盘)
|
||||
|
||||
本文记录在一次完整实战(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(外扩~1.3m) − 上层footprint`,在 `z+h` 处挤薄板(退台屋面/雨棚)。外扩是为了盖住凹包络切掉的外圈柱廊柱。
|
||||
- **地下室顶层**:直接把整层 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 改动。
|
||||
Reference in New Issue
Block a user