--- name: cad-building-showcase description: Agent-led workflow for auditing DWG/DXF architectural drawings and generating verified building_spec.json, Blender or lightweight GLB models, offline/served Three.js showcases, multi-building campus assemblies, and optional IFC proofs. Use for CAD floor-plan folders, XREF-heavy Chinese construction drawings, TArch/天正 exports, multi-frame sheets, DWG/DXF-to-3D/Web requests, campus placement, 3DSOLID/MESH extraction, or questions about whether CAD-derived output can replace BIM. Do not use for PDF-only plans unless the user first supplies or authorizes a separate PDF-to-vector/CAD conversion workflow. --- # CAD Building Showcase ## Outcome Produce an evidence-backed architectural showcase, not a blind CAD conversion. Deliver as applicable: - sanitized DXF inventory and source gate report; - versioned extraction config and `building_spec.json`; - extraction audit and per-floor SVG overlays; - overview/standard/detail GLBs plus metadata; - Blender scene/preview when Blender is selected; - served Web viewer and/or offline single-file viewer; - `scope_manifest.json` accounting for every requested building and the site; - `evidence_manifest.json` with machine-readable final checks; - notes stating assumptions, missing geometry, source limitations, and confidence level. Treat Web showcase, massing, 3D-solid extraction, and BIM/IFC as separate products. ## Reference Router Read only the branches needed for the current task: - Standard extraction/config/schema: `references/pipeline.md` and `references/building_spec_schema.md`. - Input conversion, dependencies, PDF boundary, 3DSOLID/MESH: `references/input_formats.md`. - Multi-frame sheets and TArch/天正 mappings: `references/multi_frame_tarch.md`. - Multi-building sites, placement, context, gaps: `references/campus_workflow.md`. - GLB variants, Web/offline delivery, browser and final QA: `references/web_delivery.md`. - IFC/BIM claims and validation: `references/bim_branch.md`. - Acceptance judgment: `references/agent_review.md`. - Calibration only, never constants: `references/a208_case_notes.md` and `references/optimization_notes.md`. ## Agent Decision Loop 1. Inspect before modeling. - Run `python3 scripts/cad_showcase.py inspect --input --work --output `. - Require source gate `all_sources_converted_and_readable=PASS`. - Read warnings, units, bounds, entity types, top layers, XREF/block signals, and plan-title counts. 2. Select the branch. - Use standard line extraction for architectural DWG/DXF plans. - Use `detect_sheet_frames.py` for multi-frame sheets. If the source report finds two or more plan identities in one drawing, `--frames` is mandatory; do not let `frame_ledger` become `NOT_APPLICABLE`. - Treat detector clips as proposals. If Revit views share world coordinates, keep the detector's per-floor `include_block_names` plus top-level `expand_block_names`; clips alone cannot separate overlapping views. For non-Revit overlap, split by title/wall clusters. Area and cross-floor gates must pass before modeling. - Keep `屋面平面图` (`RF`) and `机房小屋面` (`PH`) as distinct source identities. One overlapping RF clip may not satisfy both; resolve their view-suffixed blocks, heights, and roof-cap roles from the drawing evidence. - Model each building separately before campus assembly. - For multi-building/campus requests, write `scope_manifest.json` before modeling. Copy every requested building ID from the user/source inventory; never shrink scope to the easiest drawing set. - Use `--converter oda` plus `extract_3d_solids.py` for known 3DSOLID/ACIS drawings. For ordinary DWG input, `--converter auto` tries native LibreDWG, then the packaged WASM bridge, then ODA; do not manually assemble the WASM commands unless the report records a converter failure. - Stop and request DWG/DXF/vector conversion for PDF-only input. 3. Write and validate an explicit config. - Set layer mappings, scale, floor clips/offsets/order, heights, origin, block rules, footprints, caps, and evidence values. - Run `python3 scripts/showcase_schema.py config --dxf-dir `. - Treat unknown keys, missing drawings, duplicate floor keys, incomplete `floor_order`, and invalid values as hard failures. 4. Extract, audit, and review overlays. - Prefer the resumable entry point after the config is approved: `python3 scripts/cad_showcase.py run --dxf-dir --config --source-report --scope-manifest --out-dir --name --frames --backend trimesh`. - Use `--backend blender` when `.blend` and Blender preview are required. - Never pass `--no-strict-gates` to proceed toward delivery. - Treat applicable audit `WARN`/`SKIP` as `BLOCKED`, not success. `NOT_APPLICABLE` means the optional check was not armed and is non-blocking. Continue past WARN/SKIP only with an explicit `--waiver 'audit:='`; retain it in final evidence. - A waiver must be explicitly approved by the user. The Agent must not invent one, and must never use one when the user says “no waivers/不要豁免”. - Search all source sheets for economic-index tables, storey labels, and elevation ladders before declaring area/storey evidence absent. If a typical plan represents repeated floors, instantiate the source-supported repetitions; a final full-building model may not jump from F2 directly to F16. - Open the SVG overlays. Iterate if red/unclassified geometry forms walls, glazing, columns, beams, grids, stairs, slabs, roofs, or whole building wings. - Resolve every `disconnected_footprints` failure. A small remote polygon is usually a leaked sheet component that becomes a floating fin; only record `allowed_disconnected_footprints` when the source visibly proves a legitimate detached stair/canopy and include the reason. - Treat every geometry-loss warning from derive (`isolated_cluster`, `unsupported_roof`, `floor_order`, `topless_group`) as a stop condition. Tune the config or restore/model the geometry; do not accept a successful exit code with these warnings. 5. Verify actual deliverables. - Require `verify_showcase.py --strict` and `verify_delivery.py` to pass. - Inspect at least one iso/front/side/plan render personally. - For served Web output, use `cad_showcase.py run --web`; it Draco-compresses Trimesh GLBs, starts a temporary local server, runs `web_smoke_test.mjs` at real 1440×900 and 390×844 viewports, and feeds the report to final verification automatically. - For `--offline`, the pipeline embeds the retained uncompressed `standard.raw.glb`, opens `viewer.html` through a real `file://` Chromium page, and records `offline_browser_smoke_report.json`. Never embed a Draco GLB in the r147 offline viewer unless a matching offline decoder is bundled and tested. - Confirm idle `window.__renders` does not grow, GLBs decode, variants exist, controls work, and console errors are zero. 6. Report confidence and limits. - Label the result `Web showcase`, `Massing/LOD100-150`, `3D-solid partial extraction`, or `IFC/BIM proof`. - State what was not modeled and cite report/gate/image evidence. ## Hard Definition of Done Do not hand over a model unless every applicable item has evidence: 1. `cad_read_report.json.gate.status == PASS`; no unresolved conversion/read failure. A reasoned partial `WARN` is usable only with a user-approved `cad_source_report` waiver and must remain visible in evidence. 2. Config and spec pass their versioned JSON Schemas. 3. Every configured source exists, every floor key is unique, every floor is nonempty, and `floor_order` has no gaps/ghosts. 4. Multi-frame projects pass `frame_ledger`; `--frames` is mandatory when the source reports multiple plan identities, and every detected frame key and required block selector is mapped one-to-one or appears in `discarded_frames` with a reason. `RF` and `PH` cannot satisfy each other merely because their clips overlap. 5. A required single-building/campus `scope_manifest.json` matches the requested scope and its artifacts exist. 6. Numbered floors are vertically continuous; representative typical-floor drawings are repeated into source-supported storeys instead of leaving large empty gaps. 7. Audit exits 0 and every gate is `PASS`; `WARN`/`SKIP` block delivery unless a named, user-approved waiver is recorded in evidence. 8. Derive emits no `WARNING topless_group`; GLB build emits no `WARNING mesh_from_polygons`. 9. Campus output contains every requested building and the site as `PASS`, with existing artifacts; a `BLOCKED` entry means the campus request is not complete. 10. Campus output has proven transforms, no unexplained overlap, numeric neighbour gaps, boundary containment, and a top-view placement image. 11. `disconnected_footprints` passes; iso/front/side/plan review shows no floating fins, orphan slabs, duplicated roof volumes, or unexplained detached geometry. 12. `verify_delivery.py` writes `evidence_manifest.json` with overall `PASS`; `BLOCKED`/`FAIL` must never be described as complete, and a human has looked at the render. 13. Served Web delivery includes a passing desktop/mobile browser smoke report whose viewport checks prove 1440×900 and 390×844. If Chromium cannot run, report `BLOCKED`; do not substitute the offline viewer for the requested Web template. 14. Offline delivery includes a passing `file://` browser smoke report proving the readiness marker, canvas, and first render; an embedded payload check alone is insufficient. 15. After any script/schema/template change, run: - `pytest tests/test_contracts.py tests/test_delivery.py` - `python3 tests/test_extraction_pipeline.py` - `ruff format --check scripts tests && ruff check scripts tests` - `npm run check:js` ## Core Commands Check prerequisites: ```bash python3 scripts/cad_showcase.py doctor ``` Inspect/convert sources: ```bash python3 scripts/cad_showcase.py inspect \ --input --work work/ --output outputs//cad_read_report \ --converter auto ``` Run from an Agent-approved extraction config: ```bash python3 scripts/cad_showcase.py run \ --dxf-dir work//dxf_sanitized \ --config work//extract_config.json \ --source-report outputs//cad_read_report/cad_read_report.json \ --frames work//frames_config.json \ --out-dir outputs/ --name \ --backend trimesh --web --offline --scope-manifest work//scope_manifest.json --resume ``` For a known ACIS/3DSOLID source, force ODA during inspection; do not let an apparently nonempty libredwg conversion hide dropped solids: ```bash python3 scripts/cad_showcase.py inspect ... --converter oda python3 scripts/extract_3d_solids.py \ --dxf work//dxf_sanitized/model.dxf \ --out-glb outputs//solids.glb \ --report outputs//solids_report.json ``` ## Modeling and Honesty Rules - Prefer stable layered geometry over overfitted CAD noise. - Preserve floor/category naming as `__` and glTF Y-up. - Keep source originals unchanged; write intermediates under `work/` and deliveries under `outputs/`. - Start each independent attempt in a new project directory. Reusing a prior directory requires an explicit user request and a recorded provenance note. - Use CAD-derived footprint polygons for slabs/roofs when evidence is sufficient; do not present generated caps, hulls, mullions, wall unions, or massings as BIM-verified geometry. - Keep slabs visible for presentation, grids/details toggleable, and in-scene labels off by default. - Never claim rooms, openings, quantities, materials, MEP coordination, code compliance, or production BIM unless the IFC branch explicitly generates and validates them. - A missing building stays missing or becomes an explicitly labeled outline massing; never invent detail to make a scene look complete. ## Bundled Entry Points - `scripts/cad_showcase.py`: doctor, source inspection, resumable deterministic pipeline, state ledger. - `scripts/showcase_schema.py` + `schemas/`: config/spec/manifest validation and shared floor-group contract. - `scripts/cad_dxf_report.py`: DWG/DXF conversion, sanitizing, inventory, source gate. - `scripts/detect_sheet_frames.py`: frame detection, grid/wall correlation, title expansion, elevation evidence. - `scripts/derive_showcase_spec.py`: normalized extraction and canonical caps. - `scripts/audit_showcase_extraction.py` + `scripts/draw_coverage_overlay.py`: gates and visual coverage evidence. - `scripts/spec_to_glb.py` / `scripts/build_blender_showcase.py`: Y-up GLB/Blender backends consuming the same spec contract. - `scripts/build_showcase_variants.py`, `scripts/write_web_showcase.py`, `scripts/write_offline_viewer.py`: delivery assembly. - `scripts/verify_showcase.py`, `scripts/verify_delivery.py`, `scripts/web_smoke_test.mjs`: strict final QA. - `scripts/assemble_campus.py`, `scripts/register_site_outlines.py`, `scripts/site_context_from_dump.py`, `scripts/massing_from_outline.py`: campus branch. - `scripts/extract_3d_solids.py`: flat ACIS/MESH extraction with curved-surface limitation report. - `scripts/build_ifc_poc.py`, `scripts/extract_ifc_meshes.py`, `scripts/render_ifc_meshes_blender.py`: IFC proof branch.