Files
cad-building-showcase/SKILL.md

159 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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.
- 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.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 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.
- 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 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.
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:
```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.