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
13 KiB
13 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. If the source report finds two or more plan identities in one drawing,--framesis mandatory; do not letframe_ledgerbecomeNOT_APPLICABLE. - Treat detector clips as proposals. If Revit views share world coordinates, keep the detector's per-floor
include_block_namesplus top-levelexpand_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.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. For ordinary DWG input,--converter autotries 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.
-
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> --scope-manifest <scope_manifest.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 applicable audit
WARN/SKIPasBLOCKED, not success.NOT_APPLICABLEmeans 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_footprintsfailure. A small remote polygon is usually a leaked sheet component that becomes a floating fin; only recordallowed_disconnected_footprintswhen 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.
- 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. - For
--offline, the pipeline embeds the retained uncompressedstandard.raw.glb, opensviewer.htmlthrough a realfile://Chromium page, and recordsoffline_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.__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. A reasoned partialWARNis usable only with a user-approvedcad_source_reportwaiver and must remain visible in evidence.- 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;--framesis mandatory when the source reports multiple plan identities, and every detected frame key and required block selector is mapped one-to-one or appears indiscarded_frameswith a reason.RFandPHcannot satisfy each other merely because their clips overlap. - A required single-building/campus
scope_manifest.jsonmatches the requested scope and its artifacts exist. - Numbered floors are vertically continuous; representative typical-floor drawings are repeated into source-supported storeys instead of leaving large empty gaps.
- Audit exits 0 and every gate is
PASS;WARN/SKIPblock delivery unless a named, user-approved waiver is recorded in evidence. - Derive emits no
WARNING topless_group; GLB build emits noWARNING mesh_from_polygons. - Campus output contains every requested building and the site as
PASS, 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.
disconnected_footprintspasses; iso/front/side/plan review shows no floating fins, orphan slabs, duplicated roof volumes, or unexplained detached geometry.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. - Offline delivery includes a passing
file://browser smoke report proving the readiness marker, canvas, and first render; an embedded payload check alone is insufficient. - 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.