15 KiB
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
- Inventory and conversion
- CAD read report
- Layer mapping
- Floor detection and alignment
- Spec extraction
- Audit and overlays
- Blender generation
- Web showcase
- 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:
work/
cad_showcase/
dxf_raw/
dxf_sanitized/
reports/
building_spec.json
outputs/
<project>/
<project>.blend
<project>.glb
<project>.png
web/
For DWG conversion:
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:
python3 <skill>/scripts/cad_dxf_report.py --input work/XREF --work work/cad_showcase --output outputs/cad_read_report
If ezdxf is missing:
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:
- File name and drawing title.
- Text labels in modelspace/paperspace.
- Large separated plan clusters in the drawing bounding box.
S-GRIDor equivalent structural axis layers.- 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:
{
"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:
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.
Arm cross-evidence checks whenever the drawings contain the evidence:
- Copy per-floor areas from the 经济技术指标表/area labels into
declared_areas_m2; usedeclared_area_toleranceonly for a justified source convention. A model area off by roughly 100% usually means two plans or two wings were swallowed into one clip, not balcony noise. - Copy the above-ground count from 总图 labels or elevation/section ladders into
expected_storeys_above_ground. When one typical plan represents a range, instantiate those floors and record that they are source-supported repetitions. - Pass every frame-detector config through
--frames; list deliberately unused frames indiscarded_frameswith reasons.
These checks report NOT_APPLICABLE when no independent evidence exists. That is not proof of correctness; document what was searched before leaving them unarmed.
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:
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, andgridorfloor_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_categoriesdoes not hideslabfor presentation/digital-twin views.- Generated cap edges do not protrude as slab fins.
cap_bufferdefaults to0.1mfor ordinary facade-aligned floors. Set it explicitly around1.3monly for evidenced colonnade/overhang cases such as A208, then confirm front/side views.
6. Agent Audit and Overlay Review
Do not proceed to Blender until the Agent has reviewed extraction evidence.
Run the audit:
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:
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.
- A floor can be internally self-consistent yet occupy the wrong repeated slot. If wall-profile correlation finds a strong non-zero shift, treat it as the 13号 F3 “错槽” pattern and correct the frame offset rather than trusting envelope centers.
7. Blender Generation
Run:
/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>.pngmodel_metadata.json
If Blender CLI fails, verify the path. The macOS app-bundle path is:
/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:
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:
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 threeships the matching decoder undernode_modules/three/examples/jsm/libs/draco/; the template already registers aDRACOLoaderpointing 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.pystamps a?v=<build>token onapp.js/model.glb/model_metadata.jsonto 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:
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:
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:
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