Files
cad-building-showcase/SKILL.md
zhengwr 9d7d3cb973
Some checks failed
ci / test (macos-latest, 3.10) (push) Has been cancelled
ci / test (macos-latest, 3.12) (push) Has been cancelled
ci / test (ubuntu-latest, 3.10) (push) Has been cancelled
ci / test (ubuntu-latest, 3.12) (push) Has been cancelled
ci / test (windows-latest, 3.10) (push) Has been cancelled
ci / test (windows-latest, 3.12) (push) Has been cancelled
ci / browser-smoke (push) Has been cancelled
fix: enforce Revit roof views and orphan geometry gates
2026-07-21 13:10:04 +08:00

13 KiB
Raw Blame History

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. 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.
    • 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> --scope-manifest <scope_manifest.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 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:<gate>=<evidence-based reason>'; 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:

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.