# 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/ / .blend .glb .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 /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 /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`; use `declared_area_tolerance` only 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 in `discarded_frames` with 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: ```bash python3 /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. - Generated cap edges do not protrude as slab fins. The historical `cap_buffer=1.3m` value fits colonnade/overhang cases; use about `0.1m` for ordinary facade-aligned floors, 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: ```bash python3 /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 /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: ```bash /Applications/Blender.app/Contents/MacOS/Blender -b \ --python /scripts/build_blender_showcase.py -- \ --spec work/cad_showcase/building_spec.json \ --out-dir outputs/ \ --name ``` Expected outputs: - `.blend` - `.glb` - `.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 /scripts/write_web_showcase.py \ --template /assets/web-showcase-template \ --glb outputs//.glb \ --metadata outputs//model_metadata.json \ --out-dir outputs//web \ --title " Web 展示模型" ``` For Web or digital-twin presentation, generate three reusable variants and let the Web writer consume the manifest: ```bash python3 /scripts/build_showcase_variants.py \ --spec work/cad_showcase/building_spec.json \ --out-dir outputs//variants \ --name \ --build \ --blender /Applications/Blender.app/Contents/MacOS/Blender python3 /scripts/write_web_showcase.py \ --template /assets/web-showcase-template \ --variants-manifest outputs//variants/variants_manifest.json \ --out-dir outputs//web \ --title " Web 展示模型" npm install --prefix outputs//web three@0.181.2 lucide@0.468.0 python3 -m http.server 8188 --directory outputs//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=` 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 /scripts/verify_showcase.py \ --spec work/cad_showcase/building_spec.json \ --glb outputs//variants/overview.glb outputs//variants/standard.glb outputs//variants/detail.glb \ --out outputs//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 /scripts/build_ifc_poc.py \ --spec work/cad_showcase/building_spec.json \ --out-ifc outputs//_bim_poc.ifc \ --out-report outputs//_bim_poc_report.json \ --out-notes outputs//_bim_poc_notes.md \ --vendor-dir work/vendor \ --validate-geometry ``` Render IFC geometry when Blender cannot import IFC directly: ```bash python3 /scripts/extract_ifc_meshes.py \ --ifc outputs//_bim_poc.ifc \ --out work/cad_showcase/_ifc_meshes.json \ --vendor-dir work/vendor /Applications/Blender.app/Contents/MacOS/Blender -b \ --python /scripts/render_ifc_meshes_blender.py -- \ --meshes work/cad_showcase/_ifc_meshes.json \ --out-dir outputs/ \ --name _ifc_render ```