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:
347
references/pipeline.md
Normal file
347
references/pipeline.md
Normal file
@@ -0,0 +1,347 @@
|
||||
# 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. On this machine, the app path has been:
|
||||
|
||||
```text
|
||||
/Applications/Blender.app/Contents/MacOS/Blender
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
Reference in New Issue
Block a user