Files
cad-building-showcase/references/pipeline.md
zhengwr b871a2f8bd Portability: Blender/ODA discovery via env > PATH > macOS default
The two hardcoded macOS paths in code become last-resort defaults:
- build_showcase_variants: env BLENDER > shutil.which("blender") > app bundle
- cad_dxf_report: env ODA_CONVERTER > shutil.which("ODAFileConverter") > app
  bundle (env override existed already; PATH lookup is new)
Docs annotate the macOS example paths with the discovery order.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-04 15:05:32 +08:00

352 lines
13 KiB
Markdown

# CAD to Web Building Showcase Pipeline
## 1. Inventory and Conversion
Start by listing source files and preserving names. CAD drawing names often encode floor numbers, building zones, and drawing type.
Recommended workspace layout:
```text
work/
cad_showcase/
dxf_raw/
dxf_sanitized/
reports/
building_spec.json
outputs/
<project>/
<project>.blend
<project>.glb
<project>.png
web/
```
For DWG conversion:
```bash
dwg2dxf -y -o work/cad_showcase/dxf_raw/A208.dxf "work/XREF/A208 - 主楼首层、二层平面图.dwg"
```
LibreDWG DXF files may contain `999` comment records. Sanitize before using brittle importers. `ezdxf.recover` usually tolerates them, but sanitizing keeps the files friendlier to FreeCAD and other tools.
## 2. CAD Read Report
Run:
```bash
python3 <skill>/scripts/cad_dxf_report.py --input work/XREF --work work/cad_showcase --output outputs/cad_read_report
```
If `ezdxf` is missing:
```bash
python3 -m pip install --target work/vendor ezdxf
```
Read the report and identify:
- Which drawings are plans versus elevations/details.
- Whether the unit scale is probably millimeters or meters.
- Main modelspace bounding boxes.
- Layer counts and top layers.
- Entity types that matter: `LINE`, `LWPOLYLINE`, `POLYLINE`, `INSERT`, `HATCH`, `TEXT`, `MTEXT`, `DIMENSION`.
## 3. Layer Mapping
Default layer heuristics:
| Category | Common layer names |
| --- | --- |
| walls | `I-WALL`, `A-WALL`, `L-SITE-WALL`, names containing `WALL`, `墙` |
| glazing | `A-GLAZ*`, names containing `GLAZ`, `CURT`, `WINDOW`, `幕墙`, `玻璃`, `窗` |
| roof | `A-ROOF`, `A-FLOR-ROOF`, `A-FLOR-OVHD`, names containing `ROOF`, `屋面`, `屋顶`, `雨棚` |
| columns | `S-COLS`, names containing `COL`, `COLUMN`, `柱` |
| beams | `S-STRS`, `S-STRS-MBND`, names containing `BEAM`, `梁`, `结构` |
| railings | names containing `RAIL`, `HANDRAIL`, `栏杆`, `扶手` |
| doors | names containing `DOOR`, `DR`, `门`, `开启` |
| detail_lines | `A-GENM`, `A-DETL*`, parking/area/detail layers that should stay as low plan context |
| floor_lines | `A-FLOR`, `A-FLOR-OVHD`, names containing `FLOOR`, `FLOR`, `楼面`, `地面` |
| grid | `S-GRID`, names containing `GRID`, `轴网`, `轴线` |
Do not include annotation/dimension/text layers in geometry categories unless the user wants a drawing-like overlay.
## 4. Floor Detection and Alignment
Many architectural sheets place multiple floor plans side by side. Do not assume one DWG equals one floor.
Use this order of evidence:
1. File name and drawing title.
2. Text labels in modelspace/paperspace.
3. Large separated plan clusters in the drawing bounding box.
4. `S-GRID` or equivalent structural axis layers.
5. Repeated column/grid patterns across floors.
For side-by-side plans, create a config with one `floors[]` entry per floor, each with a source `clip` rectangle and optional `offset`.
Example:
```json
{
"project_name": "Main Building",
"scale": 0.001,
"origin_strategy": "center",
"floor_height": 4.2,
"curve_chord_source_length": 750,
"expand_blocks": false,
"expand_blocks_max_depth": 2,
"block_insert_layer_fallback": true,
"generate_footprints": true,
"use_footprint_slabs": true,
"use_footprint_roofs": true,
"footprint_categories": ["walls", "glazing", "floor_lines", "railings", "columns"],
"footprint_concave_ratio": 0.85,
"footprint_simplify_tolerance": 0.12,
"slab_thickness": 0.38,
"default_disabled_categories": [],
"shorten_unsupported_columns": true,
"shorten_unsupported_columns_floor_keys": ["1F"],
"unsupported_column_height": 1.2,
"column_support_distance": 0.55,
"column_support_requires_upper_plate": true,
"column_support_allow_plate_only": false,
"block_name_categories": {
"walls": ["*WALL*", "*墙*"],
"glazing": ["*GLAZ*", "*CURT*", "*幕墙*", "*玻璃*"],
"columns": ["*COL*", "*柱*"],
"beams": ["*BEAM*", "*梁*"]
},
"min_length_meters_by_category": {
"walls": 0.25,
"columns": 0.18,
"beams": 0.35,
"floor_lines": 0.40,
"grid": 1.0
},
"drawings": [
{
"file": "A208.dxf",
"split_x": 0,
"floors": [
{"key": "1F", "name": "首层", "side": "left"},
{"key": "2F", "name": "二层", "side": "right", "offset": [-158029.255, 0]}
]
}
],
"layers": {
"walls": ["I-WALL", "A-WALL", "L-SITE-WALL"],
"glazing": ["A-GLAZ*"],
"roof": ["A-ROOF", "A-FLOR-ROOF"],
"columns": ["S-COLS"],
"beams": ["S-STRS", "S-STRS-MBND"],
"railings": ["*RAIL*"],
"doors": ["*DOOR*", "*DR*"],
"detail_lines": ["A-GENM", "A-DETL*", "*PRKG*", "A-AREA"],
"floor_lines": ["A-FLOR", "A-FLOR-OVHD"],
"grid": ["S-GRID"]
},
"roof_specs": [
{
"floor_key": "RF",
"bounds_from": ["RF"],
"footprint_from": ["RF"],
"thickness": 0.35,
"margin": 0.4
}
]
}
```
In the A208 test project, 1F and 2F were on the same sheet and the second floor required an X shift of about `-158029.255 mm` to align the grids. Treat this as an example, not a constant.
Use `origin_strategy: "center"` for large CAD coordinates. It mirrors the A208 proven workflow and keeps Blender/Web coordinates numerically stable.
Use `clip` rectangles for irregular sheet layouts. Use `split_x` plus `side` when a sheet cleanly places plans left/right; this is less likely to accidentally cut off geometry than a tight clip rectangle.
Keep `expand_blocks` false for the first pass. If the audit shows important geometry in `INSERT`, set `expand_blocks` to `true` or to a list of block-name patterns, then rerun extraction/audit/overlays. When virtual block entities live on layer `0`, `block_insert_layer_fallback: true` lets the parent INSERT layer participate in category matching.
## 5. Spec Extraction
Run:
```bash
python3 <skill>/scripts/derive_showcase_spec.py --dxf-dir work/cad_showcase/dxf_sanitized --config work/cad_showcase/config.json --out work/cad_showcase/building_spec.json
```
Review `building_spec.json` before rendering:
- Floors are ordered correctly.
- Bounds are plausible in meters.
- Each major floor has nonzero `walls`, `columns`, and `grid` or `floor_lines`.
- Segment counts are not dominated by dimensions/hatches/annotations.
- Footprint polygons exist when slabs/roofs are meant to follow CAD floor plates.
- `default_disabled_categories` does not hide `slab` for presentation/digital-twin views.
## 6. Agent Audit and Overlay Review
Do not proceed to Blender until the Agent has reviewed extraction evidence.
Run the audit:
```bash
python3 <skill>/scripts/audit_showcase_extraction.py \
--dxf-dir work/cad_showcase/dxf_sanitized \
--config work/cad_showcase/config.json \
--spec work/cad_showcase/building_spec.json \
--out work/cad_showcase/extraction_audit \
--vendor-dir work/vendor
```
Generate 2D overlays:
```bash
python3 <skill>/scripts/draw_coverage_overlay.py \
--dxf-dir work/cad_showcase/dxf_sanitized \
--config work/cad_showcase/config.json \
--spec work/cad_showcase/building_spec.json \
--out-dir work/cad_showcase/overlays \
--vendor-dir work/vendor
```
Agent review rules:
- Treat `INSERT`, `HATCH`, `ACAD_PROXY_ENTITY`, `SOLID`, `3DFACE`, and large unclassified layers as potential missing-model risks.
- Open overlay SVGs. Gray means source vectors already classified, red dashed means source vectors not classified, color means extracted model geometry.
- If red dashed geometry forms walls, columns, beams, stairs, grids, or floor outlines, update layer mapping or parser strategy and rerun extraction.
- If frequent blocks appear in the audit, inspect block names and decide whether to recursively explode block geometry.
- If hatches carry wall/slab/column information, do not rely only on line extraction.
- Continue only when missing geometry is acceptable for the requested output level.
## 7. Blender Generation
Run:
```bash
/Applications/Blender.app/Contents/MacOS/Blender -b \
--python <skill>/scripts/build_blender_showcase.py -- \
--spec work/cad_showcase/building_spec.json \
--out-dir outputs/<project> \
--name <project>
```
Expected outputs:
- `<project>.blend`
- `<project>.glb`
- `<project>.png`
- `model_metadata.json`
If Blender CLI fails, verify the path. The macOS app-bundle path is:
```text
/Applications/Blender.app/Contents/MacOS/Blender
```
On Linux/other platforms use `blender` from PATH; scripts discover the
executable via env `BLENDER` > PATH > the macOS default, and ODA File
Converter via env `ODA_CONVERTER` > PATH > its macOS default.
## 8. Web Showcase
For a quick single-model preview, run:
```bash
python3 <skill>/scripts/write_web_showcase.py \
--template <skill>/assets/web-showcase-template \
--glb outputs/<project>/<project>.glb \
--metadata outputs/<project>/model_metadata.json \
--out-dir outputs/<project>/web \
--title "<project> Web 展示模型"
```
For Web or digital-twin presentation, generate three reusable variants and let the Web writer consume the manifest:
```bash
python3 <skill>/scripts/build_showcase_variants.py \
--spec work/cad_showcase/building_spec.json \
--out-dir outputs/<project>/variants \
--name <project> \
--build \
--blender /Applications/Blender.app/Contents/MacOS/Blender
python3 <skill>/scripts/write_web_showcase.py \
--template <skill>/assets/web-showcase-template \
--variants-manifest outputs/<project>/variants/variants_manifest.json \
--out-dir outputs/<project>/web \
--title "<project> Web 展示模型"
npm install --prefix outputs/<project>/web three@0.181.2 lucide@0.468.0
python3 -m http.server 8188 --directory outputs/<project>/web
```
The manifest path makes `standard` the default `model.glb`, copies `overview.glb`, `standard.glb`, and `detail.glb`, and writes `model_variants` for the download controls.
Use another port if 8188 is occupied.
Notes:
- GLBs are Draco-compressed (Blender built-in, or post-process with `node tools/compress.mjs in.glb out.glb`). `npm install three` ships the matching decoder under `node_modules/three/examples/jsm/libs/draco/`; the template already registers a `DRACOLoader` pointing there, so no CDN is needed.
- The template is glTF-standard **Y-up**. If you swap in a Z-up GLB the building will render lying down — keep GLB and viewer on the same up-axis.
- `write_web_showcase.py` stamps a `?v=<build>` token on `app.js` / `model.glb` / `model_metadata.json` to defeat browser caching; if a user reports "no change after rebuild", confirm the served folder and hard-refresh.
## 9. Verification
Run the Blender-free QA pass first, then eyeball the previews before opening the Web viewer:
```bash
python3 <skill>/scripts/verify_showcase.py \
--spec work/cad_showcase/building_spec.json \
--glb outputs/<project>/variants/overview.glb outputs/<project>/variants/standard.glb outputs/<project>/variants/detail.glb \
--out outputs/<project>/verify_previews.png --budget-mb 0.6
```
It prints per-floor segment/cap/glazing-continuity counts and a GLB size-budget pass/fail, and writes front/side/plan orthographic previews. Use these to catch missing floors, a lying-down (wrong up-axis) model, uncapped columns, or discontinuous glazing **before** declaring the model done — early visual verification avoids most rework.
Minimum verification:
- Preview PNG is nonblank, building is framed, and floors are visible.
- GLB file exists and has reasonable size.
- Browser loads the Web viewer with zero console errors.
- Floor toggles, component toggles, explode slider, section slider, presets, screenshot, and GLB download work.
- Variant download links exist for overview, standard, and detail when the task is Web/digital-twin presentation.
- Slabs are visible from side views; transparent glazing should not make floor plates look missing.
- Roof caps do not visibly overrun unrelated lower floor footprints.
- Ground-level columns that have no upper support are not left full-height without explanation.
- Mobile viewport around 390 px wide has no incoherent overlap.
- Extraction audit is attached or summarized, including high-risk entity counts and unclassified layers.
- Overlay review result is stated: accepted, accepted with known gaps, or rejected and iterated.
For BIM branch:
- Validate IFC schema with IfcOpenShell.
- Count `IfcBuildingStorey`, `IfcSlab`, `IfcWall`, `IfcColumn`, `IfcBeam`, and property sets.
- Run geometry extraction on all products.
- Do not claim BIM replacement unless semantic and geometric validation has passed.
Generate IFC:
```bash
python3 <skill>/scripts/build_ifc_poc.py \
--spec work/cad_showcase/building_spec.json \
--out-ifc outputs/<project>/<project>_bim_poc.ifc \
--out-report outputs/<project>/<project>_bim_poc_report.json \
--out-notes outputs/<project>/<project>_bim_poc_notes.md \
--vendor-dir work/vendor \
--validate-geometry
```
Render IFC geometry when Blender cannot import IFC directly:
```bash
python3 <skill>/scripts/extract_ifc_meshes.py \
--ifc outputs/<project>/<project>_bim_poc.ifc \
--out work/cad_showcase/<project>_ifc_meshes.json \
--vendor-dir work/vendor
/Applications/Blender.app/Contents/MacOS/Blender -b \
--python <skill>/scripts/render_ifc_meshes_blender.py -- \
--meshes work/cad_showcase/<project>_ifc_meshes.json \
--out-dir outputs/<project> \
--name <project>_ifc_render
```