--- 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. - Treat detector clips as proposals. If two titles share the same clip, split the common sheet by title/wall clusters; the area and cross-floor gates must pass before modeling. - 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. - 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 --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 audit `WARN` and `SKIP` as `BLOCKED`, not success. Continue only with an explicit `--waiver 'audit:='`; retain it in final evidence. - Open the SVG overlays. Iterate if red/unclassified geometry forms walls, glazing, columns, beams, grids, stairs, slabs, roofs, or whole building wings. 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. - 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. 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`; every detected plan frame is used or appears in `discarded_frames` with a reason. 5. Audit exits 0 and every gate is `PASS`; `WARN`/`SKIP` block delivery unless a named, reasoned waiver is recorded in evidence. 6. Derive emits no `WARNING topless_group`; GLB build emits no `WARNING mesh_from_polygons`. 7. Campus output has a `scope_manifest.json` containing every requested building. Every building and the site is `PASS`, with existing artifacts; a `BLOCKED` entry means the campus request is not complete. 8. Campus output has proven transforms, no unexplained overlap, numeric neighbour gaps, boundary containment, and a top-view placement image. 9. `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. 10. 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. 11. 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.