--- name: cad-building-showcase description: Agent-led workflow for generating and auditing architectural 3D web showcase models from CAD drawing folders. Use when Codex is given DWG/DXF/PDF CAD plans, XREF folders, floor plans, building drawings, or asks like "用 CAD 图纸生成 3D 建筑演示模型", "把所有 CAD 图纸做成 Web 展示模型", "DWG/DXF 转 Blender/GLB", "建筑平面图生成完整建筑展示模型", or asks whether CAD-derived output can replace BIM. This skill is specifically for cases where an Agent must inspect CAD reports, decide layer/floor/block rules, run scripts, audit coverage, and iterate; not for blind one-shot script conversion. --- # CAD Building Showcase ## Outcome Create a usable architectural demonstration model through Agent judgment plus deterministic scripts. Do not treat this as blind CAD conversion. The target deliverables are: - CAD read report: converted/sanitized DXF inventory, layer counts, entity counts, drawing bounds, likely units. - Agent extraction config: explicit layer mapping, floor split/alignment, unit scale, curve and filtering rules. - `building_spec.json`: normalized floor-by-floor geometry in meters. - Extraction audit: coverage, unclassified layers, high-risk entity types, block/INSERT signals, and Agent questions. - 2D overlay review: SVG overlays comparing source CAD vectors with extracted model geometry. - Blender scene: `.blend`, `.glb`, and preview `.png`. - Web showcase: static Three.js viewer with floor/component toggles, floor explode, section height, camera presets, screenshot, and GLB download. - Lightweight variants: produce at least overview, standard, and detail GLB variants when the user asks for Web/digital-twin presentation. The Web viewer should default to the standard variant and expose download links for all variants. - Notes file: source drawings, assumptions, extraction limits, and verification results. If the user asks to replace BIM, branch explicitly to IFC/BIM validation. Treat Web showcase and BIM replacement as separate products. ## Agent Decision Loop The Agent owns interpretation. Scripts are tools for evidence and repeatable execution. 1. Inspect first, do not model blind. - Run `cad_dxf_report.py`. - Read top layers, entity types, bounding boxes, units, and high-risk entities. - Form hypotheses: which drawings are floor plans, which layers are walls/glazing/roof/columns/beams/railings/doors/detail lines/grid, whether blocks or hatches matter, and how floors align. 2. Write an explicit extraction config. - Decide layer mappings, floor splits, offsets, origin strategy, curve chord length, and category-specific line-length filters. - Use `references/pipeline.md`, `references/building_spec_schema.md`, and `references/a208_case_notes.md` as calibration. 3. Extract, audit, and review overlays before accepting. - Run `derive_showcase_spec.py`. - Run `audit_showcase_extraction.py`. - Run `draw_coverage_overlay.py`. - Inspect unclassified layers, high-risk `INSERT`/`HATCH` counts, and overlay SVGs. If major geometry is red/unclassified or missing, adjust config or parsing strategy and repeat. 4. Generate and verify the 3D/Web model only after the extraction passes review. - Run Blender/GLB generation and Web template assembly. - Verify preview image, Web controls, console logs, and mobile layout. 5. Report confidence and limits. - State whether the output is Web showcase, LOD-like massing, IFC/BIM proof, or not sufficient. - Include what was not modeled and what evidence supports that judgment. ## Command Workflow 1. Prepare the CAD folder. - Work from a folder under the current workspace when possible. On macOS, avoid direct reads from `Downloads` if TCC blocks access; ask the user to move/copy the CAD folder into the workspace. - Preserve the original CAD folder. Put converted/intermediate files in `work/`. - If DWG files are present, prefer `libredwg` `dwg2dxf` for batch conversion. Use ODA/QCAD/FreeCAD only as fallback — EXCEPT for drawings containing `3DSOLID`/ACIS entities: libredwg silently drops ACIS data (R2013+ stores it in the ACDSDATA section), so 3D-solid DWGs must go through ODA File Converter (`/Applications/ODAFileConverter.app/Contents/MacOS/ODAFileConverter ACAD2004 DXF 0 1 "*.dwg"`). ODA reports bad arguments via GUI dialogs, not stderr: both directories must exist as absolute paths, and a silent exit-0 with no output means a dialog is blocking on screen. 3D-solid DWG branch: if the read report shows `3DSOLID`/`MESH` as the main types (typically also flagged `near_empty` for plan purposes), the floor-plan extrusion pipeline does not apply. Convert via ODA, then tessellate with `ezdxf.acis` (`load_dxf` → `mesh_from_body`, which returns a list of meshes). Only polyhedral/flat ACIS faces tessellate; count curved records (`cone-surface`, `spline-surface`, ...) in the SAT text and report them as not extractable. Export captured meshes + `MESH` entities to OBJ/GLB (OBJ is Z-up: import into Blender with `up_axis='Z'`). If curved skin dominates, tell the user to export OBJ/STL/STEP from a full CAD kernel (AutoCAD/BricsCAD) instead of promising a complete model. 2. Generate a CAD read report. - Run `scripts/cad_dxf_report.py` from this skill. - Install missing parser dependencies into the current project work area, not globally: `python3 -m pip install --target work/vendor ezdxf` - Inspect the Markdown/JSON report before modeling. Confirm drawings, units, bounding boxes, and the top layers for walls/glazing/roof/columns/beams/railings/doors/detail lines/floor lines/grid. - Resolve the report's `Warnings` section before modeling. `likely_xref_shell` / `near_empty` means a sheet's real geometry lives in unbound XREFs and will silently become a missing floor: ask the user to bind/insert the XREFs in CAD and re-export that DXF (do not model the shell and report the floor as done). 3. Build the extraction config and `building_spec.json`. - Use `references/pipeline.md` and `references/building_spec_schema.md`. - Map CAD layers to normalized categories: `walls`, `glazing`, `roof`, `columns`, `beams`, `railings`, `doors`, `detail_lines`, `floor_lines`, and `grid`. - Identify one drawing per floor or split sheets that contain multiple floor plans side by side. - Align floors by structural grid or repeated control axes. Use millimeters-to-meters scale (`0.001`) unless the report proves the CAD is already in meters. - When CAD linework has enough exterior/interior boundary signal, enable generated footprints for floor slabs and roof caps. Prefer footprint polygons over rectangular floor bounds for visual/digital-twin presentation. - Run `scripts/derive_showcase_spec.py` to extract line/polyline geometry into `building_spec.json`. 4. Audit extraction before 3D generation. - Run `scripts/audit_showcase_extraction.py`. - Run `scripts/draw_coverage_overlay.py`. - The audit enforces hard gates and exits with code 3 on failure (e.g. glazing evidence exists in blocks but the spec has 0 glazing segments). A failed gate means the extraction is known-incomplete: fix the config or source export and re-run; never bypass with `--no-strict-gates` just to proceed. - The headline coverage ratio counts modelspace linework only. Read the `Block-Locked Geometry By Layer` section too — geometry inside INSERT blocks is reported separately and a 96% coverage can coexist with an entirely missing curtain wall. - Review the Markdown audit and SVG overlays. Iterate config if important geometry remains unclassified or hidden in high-risk entity types. 5. Generate Blender/GLB. - Use Blender CLI: `/Applications/Blender.app/Contents/MacOS/Blender -b --python /scripts/build_blender_showcase.py -- --spec work/building_spec.json --out-dir outputs/ --name ` - Use Blender MCP only after the CLI artifact exists, for inspection, scene tuning, or interactive refinement. 6. Generate the Web showcase. - For digital-twin-style Web delivery, keep generated slabs visible by default and create three filtered specs/models: - `overview`: walls, glazing, roof, columns, beams, and generated slabs. - `standard`: overview plus railings and doors; use this as the default Web model. - `detail`: full extraction, including grid, floor lines, and detail lines for audit/review. - Run `scripts/build_showcase_variants.py --build` to write the filtered specs, call Blender for all three GLBs, and create `variants_manifest.json`. - Run `scripts/write_web_showcase.py --variants-manifest ...` to copy the template, use the standard model as `model.glb`, copy all variant GLBs, and add `model_variants` to `model_metadata.json`. - Use the single-GLB `write_web_showcase.py --glb ... --metadata ...` path only when the user explicitly wants a quick one-model preview. - Install local web deps in that output folder: `npm install --prefix outputs//web three@0.181.2 lucide@0.468.0` - Start a local server from the web output folder and give the user the URL. 7. Verify before final delivery. - Open the preview PNG or render another screenshot; check that geometry is nonblank and framed. - Open the Web viewer in the Browser plugin on desktop and mobile widths. - Check console logs are clean, controls work, mobile panels do not overlap, and the GLB loads. - Report model precision honestly: showcase model, LOD-like massing/structural visualization, or IFC/BIM proof. ## Modeling Rules - Prefer stable, layered massing over overfitted geometry. CAD floor plans often contain annotations, dimensions, hatches, XREF artifacts, and duplicated lines. - Use linework from walls/glazing/columns/beams/railings/doors as visual extrusions. Generate explicit `roof`/roof-cover geometry when roof drawings are sparse or when top-floor columns need an overhead cap. Keep generic detail layers as low plan detail unless the Agent has evidence they are vertical building elements. Do not claim parametric wall joins, rooms, MEP, quantities, or code-compliant BIM unless IFC semantics and validation are generated. - Keep 3D floor labels off by default. The Web UI already names floors; generated in-scene text usually clutters the building view. - Prefer CAD-derived footprint polygon `slab` meshes over rectangular `bounds` slabs. Generate the footprint from mapped wall/glazing/floor-line/railing/column vectors, simplify it, and cap it to a small number of high-area polygons. For digital-twin-style presentation, use a looser concave hull so floor plates read as continuous platforms instead of leaving avoidable visual voids. Treat this as a visual floor/roof plate, not a BIM-grade slab with validated openings and joins. - For presentation models, make slab edges visible in side views: use a display thickness around 0.35-0.40 m, render slabs double-sided in the Web viewer, and avoid very low slab opacity. Otherwise transparent glazing can make floor plates look missing even when the footprint is present. - Keep `slab` available as a toggle. Default it on for presentation/digital-twin models; default it off only for audit views where slabs obscure linework review. - For generated roof caps, do not blindly union lower floor footprints into the roof geometry. Use the roof floor's own `footprint_from` source unless there is clear CAD evidence that a canopy/overhang exists. - For columns that visually stand without anything above, do not rely on broad floor bounds or broad footprint alone to infer support. Require an adjacent upper floor/roof plate and nearby upper structural geometry; shorten unsupported display columns unless the Agent has evidence they are meant to be full-height freestanding elements. - Keep floors separable in object names and metadata. The Web viewer expects objects named `__`. - Use neutral, readable colors and transparent slabs. Avoid a single-hue scene. - Document every assumption that affects geometry: layer mapping, floor heights, sheet splits, coordinate offsets, unit scale, and ignored entity types. - Curtain walls/glazing are frequently inside INSERT blocks (e.g. `系统嵌板/幕墙` blocks resolving to layer `A-GLAZ-CURT`). `derive_showcase_spec.py` handles this two ways: block-name expansion (`GLAZING_BLOCK_PATTERNS`, fragile — DWG→DXF conversion can mangle CJK names like `系统嵌板`→`系统嵌`) and layer-based probing (`classify_block_contents`, default on): every INSERT — including wrapper/sheet blocks — is expanded up to `expand_blocks_max_depth` and sub-entities are kept only when their own layer classifies into `block_content_categories` (default glazing/railings/doors). Check the audit's glazing gate and block-locked section before accepting. - Identification/annotation layers (`*-IDEN`: door tags, axis numbers, area labels) are excluded from classification by default (`exclude_layers`), so `A-DOOR-IDEN` no longer counts as door geometry. If a category only ever matched an `*-IDEN` layer, the drawing has no real geometry for it — say so instead of modeling tags. - CAD draws curtain walls as sparse panel/mullion segments; `derive_showcase_spec.py` merges collinear glazing into continuous bands (`merge_glazing`, `glazing_gap_tol`). Only bridge gaps that contain no opaque wall on the same line. - Prefer capping column tops over shortening them. `derive_showcase_spec.py` stores `floor.caps` (setback overhang rings for above-ground floors, full ground/podium deck for the top basement level) which both backends extrude as slab caps; this avoids stray topless columns and odd short stubs. - Coordinate convention: GLB is glTF-standard **Y-up**; the Web viewer sets `camera.up=(0,1,0)`, sections/explode along Y, and registers a `DRACOLoader`. Keep GLB up-axis and viewer up-axis in sync, otherwise the building renders lying on its side. - Lightweighting: export Draco-compressed GLB (Blender built-in, or `tools/compress.mjs`); the viewer must register `DRACOLoader` (it does). Sanitize degenerate faces / NaN normals before export so strict importers (Blender, online viewers) accept the file. ## Bundled Resources - `scripts/cad_dxf_report.py`: batch DWG/DXF conversion, DXF sanitizing, and read report generation, including XREF-shell / near-empty sheet warnings. - `scripts/derive_showcase_spec.py`: configurable extraction from DXF line/polyline layers into a normalized building spec, with block-content probing for glazing/railings/doors locked inside INSERTs. - `scripts/audit_showcase_extraction.py`: coverage and risk audit with hard gates (exit 3 on failure) and block-locked geometry accounting, for Agent review before 3D generation. - `scripts/draw_coverage_overlay.py`: SVG overlays comparing source CAD vectors to extracted model geometry. - `scripts/verify_showcase.py`: Blender-free QA from `building_spec.json` (+ optional GLBs): per-floor segment/cap/glazing-continuity report, GLB size-budget check, and orthographic front/side/plan previews. - `scripts/build_blender_showcase.py`: Blender CLI renderer/exporter from `building_spec.json` to `.blend`, `.glb`, `.png`, and metadata. GLB is Draco-compressed by default. - `scripts/spec_to_glb.py`: Blender-free `building_spec.json` -> GLB exporter (trimesh). Use when Blender is unavailable; produces the same `__` naming, Y-up, flat normals, glazing merge, and setback/basement caps. - `tools/compress.mjs`: gltf-transform Draco compressor (`node tools/compress.mjs in.glb out.glb`); alternative to Blender's built-in Draco, usually smaller. - `scripts/build_showcase_variants.py`: creates overview/standard/detail filtered specs, optionally builds their GLBs, and writes a manifest for Web delivery. - `scripts/write_web_showcase.py`: copies the static Web viewer template and model assets into an output folder. - `scripts/build_ifc_poc.py`: optional IFC4 semantic proof-of-concept generator from `building_spec.json`. - `scripts/extract_ifc_meshes.py`: extracts IFC geometry to JSON for render verification. - `scripts/render_ifc_meshes_blender.py`: renders IFC geometry in Blender and exports `.blend`, `.glb`, and `.png`. - `references/pipeline.md`: detailed CAD-to-model procedure and quality gates. - `references/building_spec_schema.md`: expected JSON contract between CAD extraction, Blender, and Web viewer. - `references/agent_review.md`: acceptance/iteration/BIM-claim checklist for Agent judgment. - `references/a208_case_notes.md`: proven details from the A208 DWG/DXF/Blender/Web/IFC run. - `references/optimization_notes.md`: lightweighting + completeness lessons (Draco/DRACOLoader, glTF Y-up convention, block-locked glazing, glazing continuity, column-top caps, NaN sanitation, verification). - `assets/web-showcase-template/`: static Three.js viewer template (Y-up, registers DRACOLoader, cache-busting `?v=` build token). - `tests/test_extraction_pipeline.py`: synthetic-DXF regression test for block-locked glazing capture, `*-IDEN` exclusion, audit gates, and XREF-shell warnings. Run it after changing extraction/audit/report scripts. ## BIM Branch When the user asks whether the model can replace BIM: - Say that the Web showcase model cannot replace BIM by itself. - Create IFC only if the task explicitly needs BIM-like semantics. - Use `scripts/build_ifc_poc.py` with IfcOpenShell to generate and validate IFC entity counts, schema validity, geometry generation, storeys, and property sets. - Use `scripts/extract_ifc_meshes.py` and `scripts/render_ifc_meshes_blender.py` when the user asks to see the IFC render effect or when Blender cannot import IFC directly. - State the remaining BIM gaps: wall/slab joins, object classifications, openings, doors/windows, room spaces, quantities, materials, levels, georeferencing, and discipline coordination.