Files
cad-building-showcase/SKILL.md

9.9 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.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 <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.
  2. Select the branch.

    • Use standard line extraction for architectural DWG/DXF plans.
    • Use detect_sheet_frames.py for multi-frame sheets.
    • 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 <config.json> --dxf-dir <sanitized-dxf>.
    • 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 <dxf> --config <config> --source-report <cad_read_report.json> --out-dir <out> --name <name> --frames <frames.json> --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:<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.
  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 starts a temporary local server, runs web_smoke_test.mjs at desktop and 390px widths, 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. 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:

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 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.