376 lines
14 KiB
Markdown
376 lines
14 KiB
Markdown
# CAD to Web Building Showcase Pipeline
|
|
|
|
Prefer `scripts/cad_showcase.py` for source inspection and the resumable post-config pipeline. Use the individual commands below when diagnosing or iterating a specific stage.
|
|
|
|
## Contents
|
|
|
|
1. Inventory and conversion
|
|
2. CAD read report
|
|
3. Layer mapping
|
|
4. Floor detection and alignment
|
|
5. Spec extraction
|
|
6. Audit and overlays
|
|
7. Blender generation
|
|
8. Web showcase
|
|
9. Verification and IFC proof
|
|
|
|
## 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
|
|
{
|
|
"config_version": 1,
|
|
"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
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Validate before extraction:
|
|
|
|
```bash
|
|
python3 <skill>/scripts/showcase_schema.py config work/cad_showcase/config.json \
|
|
--dxf-dir work/cad_showcase/dxf_sanitized
|
|
```
|
|
|
|
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 25 --strict
|
|
```
|
|
|
|
It prints per-floor segment/cap/glazing-continuity counts and a GLB size-budget pass/fail, and writes front/side/plan previews from the spec. Use those previews for stacking and footprint gaps. Use an actual GLB render/browser screenshot to verify Y-up orientation, caps, materials, and slab fins; a spec preview cannot prove exported geometry orientation.
|
|
|
|
Finish with `verify_delivery.py` and retain its `evidence_manifest.json`; for formal Web delivery include the passing report from `web_smoke_test.mjs`.
|
|
|
|
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
|
|
```
|