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
172 lines
14 KiB
Markdown
172 lines
14 KiB
Markdown
---
|
||
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 <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.
|
||
- When RF and PH are both floor keys, put them in separate `cap_groups` and give each an explicit evidence-derived `roof_specs` elevation. This prevents the automatic setback-cap calculation from creating a duplicate full-roof plate between the main roof and machine-room roof.
|
||
- Model each building separately before campus assembly.
|
||
- A campus request must run and audit one config per building, then use `assemble_campus.py`; do not merge building configs into one shortcut run, even when their source coordinates already share a site system.
|
||
- 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. For ordinary DWG input, `--converter auto` tries 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.
|
||
|
||
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.
|
||
- Use the `thumbnail.png` emitted by the Web smoke. It is exported directly from the WebGL canvas with the canonical camera; do not manually crop the browser screenshot or iterate on UI-free framing.
|
||
- 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:
|
||
|
||
```bash
|
||
python3 scripts/cad_showcase.py doctor
|
||
```
|
||
|
||
Inspect/convert sources:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|