10 KiB
10 KiB
name, description
| name | description |
|---|---|
| cad-building-showcase | 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.jsonaccounting for every requested building and the site;evidence_manifest.jsonwith 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.mdandreferences/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.mdandreferences/optimization_notes.md.
Agent Decision Loop
-
Inspect before modeling.
- Run
python3 scripts/cad_showcase.py inspect --input <cad> --work <work> --output <report>. - Require source gate
all_sources_converted_and_readable=PASS. - Read warnings, units, bounds, entity types, top layers, XREF/block signals, and plan-title counts.
- Run
-
Select the branch.
- Use standard line extraction for architectural DWG/DXF plans.
- Use
detect_sheet_frames.pyfor 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.jsonbefore modeling. Copy every requested building ID from the user/source inventory; never shrink scope to the easiest drawing set. - Use
--converter odaplusextract_3d_solids.pyfor known 3DSOLID/ACIS drawings. - Stop and request DWG/DXF/vector conversion for PDF-only input.
-
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 <config.json> --dxf-dir <sanitized-dxf>. - Treat unknown keys, missing drawings, duplicate floor keys, incomplete
floor_order, and invalid values as hard failures.
-
Extract, audit, and review overlays.
- Prefer the resumable entry point after the config is approved:
python3 scripts/cad_showcase.py run --dxf-dir <dxf> --config <config> --source-report <cad_read_report.json> --out-dir <out> --name <name> --frames <frames.json> --backend trimesh. - Use
--backend blenderwhen.blendand Blender preview are required. - Never pass
--no-strict-gatesto proceed toward delivery. - Treat audit
WARNandSKIPasBLOCKED, not success. Continue only with an explicit--waiver 'audit:<gate>=<evidence-based reason>'; 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.
- Prefer the resumable entry point after the config is approved:
-
Verify actual deliverables.
- Require
verify_showcase.py --strictandverify_delivery.pyto 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, runsweb_smoke_test.mjsat real 1440×900 and 390×844 viewports, and feeds the report to final verification automatically. - Confirm idle
window.__rendersdoes not grow, GLBs decode, variants exist, controls work, and console errors are zero.
- Require
-
Report confidence and limits.
- Label the result
Web showcase,Massing/LOD100-150,3D-solid partial extraction, orIFC/BIM proof. - State what was not modeled and cite report/gate/image evidence.
- Label the result
Hard Definition of Done
Do not hand over a model unless every applicable item has evidence:
cad_read_report.json.gate.status == PASS; no unresolved conversion/read failure.- Config and spec pass their versioned JSON Schemas.
- Every configured source exists, every floor key is unique, every floor is nonempty, and
floor_orderhas no gaps/ghosts. - Multi-frame projects pass
frame_ledger; every detected plan frame is used or appears indiscarded_frameswith a reason. - Audit exits 0 and every gate is
PASS;WARN/SKIPblock delivery unless a named, reasoned waiver is recorded in evidence. - Derive emits no
WARNING topless_group; GLB build emits noWARNING mesh_from_polygons. - Campus output has a
scope_manifest.jsoncontaining every requested building. Every building and the site isPASS, with existing artifacts; aBLOCKEDentry means the campus request is not complete. - Campus output has proven transforms, no unexplained overlap, numeric neighbour gaps, boundary containment, and a top-view placement image.
verify_delivery.pywritesevidence_manifest.jsonwith overallPASS;BLOCKED/FAILmust never be described as complete, and a human has looked at the render.- 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. - After any script/schema/template change, run:
pytest tests/test_contracts.py tests/test_delivery.pypython3 tests/test_extraction_pipeline.pyruff format --check scripts tests && ruff check scripts testsnpm run check:js
Core Commands
Check prerequisites:
python3 scripts/cad_showcase.py doctor
Inspect/convert sources:
python3 scripts/cad_showcase.py inspect \
--input <cad-folder> --work work/<project> --output outputs/<project>/cad_read_report \
--converter auto
Run from an Agent-approved extraction config:
python3 scripts/cad_showcase.py run \
--dxf-dir work/<project>/dxf_sanitized \
--config work/<project>/extract_config.json \
--source-report outputs/<project>/cad_read_report/cad_read_report.json \
--frames work/<project>/frames_config.json \
--out-dir outputs/<project> --name <project> \
--backend trimesh --web --offline --scope-manifest work/<project>/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:
python3 scripts/cad_showcase.py inspect ... --converter oda
python3 scripts/extract_3d_solids.py \
--dxf work/<project>/dxf_sanitized/model.dxf \
--out-glb outputs/<project>/solids.glb \
--report outputs/<project>/solids_report.json
Modeling and Honesty Rules
- Prefer stable layered geometry over overfitted CAD noise.
- Preserve floor/category naming as
<floor_key>__<category>and glTF Y-up. - Keep source originals unchanged; write intermediates under
work/and deliveries underoutputs/. - 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.