Files
cad-building-showcase/references/building_spec_schema.md
zhengwr a6ac166049 Initial commit: cad-building-showcase skill
Agent-led CAD-drawing → 3D web showcase pipeline. Inspects CAD reports,
maps layers/floors, extracts a normalized building spec (with block-probed
glazing and audit gates), builds Blender/trimesh GLB variants, and assembles
a Three.js web viewer. Includes XREF-shell detection and a regression test.

Large inputs/outputs (work/, outputs/, source_cad/, renders) are gitignored.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-12 16:16:04 +08:00

183 lines
8.3 KiB
Markdown

# building_spec.json Schema
Use `building_spec.json` as the contract between CAD extraction, Blender generation, and the Web showcase.
## Top Level
```json
{
"project": {
"name": "Project name",
"description": "Short user-facing description"
},
"source": {
"cad_folder": "work/XREF",
"report": "outputs/cad_read_report.json",
"config": {
"generate_footprints": true,
"use_footprint_slabs": true,
"use_footprint_roofs": true,
"footprint_categories": ["walls", "glazing", "floor_lines", "railings", "columns"],
"slab_thickness": 0.38,
"default_disabled_categories": []
}
},
"units": {
"source": "millimeters",
"scale_to_meters": 0.001,
"origin_source": [0.0, 0.0]
},
"categories": {
"walls": {"label": "墙体", "color": "#d4cbb8"},
"glazing": {"label": "玻璃/幕墙", "color": "#79b8c9"},
"roof": {"label": "屋顶/屋盖", "color": "#b8ae98"},
"columns": {"label": "柱", "color": "#f58a1f"},
"beams": {"label": "梁/结构", "color": "#1f66c2"},
"railings": {"label": "栏杆/扶手", "color": "#6f746d"},
"doors": {"label": "门/开启线", "color": "#8a6a45"},
"detail_lines": {"label": "平面细节", "color": "#8c9088"},
"floor_lines": {"label": "楼面线", "color": "#18a058"},
"grid": {"label": "轴网", "color": "#20242a"},
"slab": {"label": "楼板", "color": "#c8ccc2"}
},
"floors": {
"1F": {
"name": "首层",
"z": 0.0,
"height": 4.2,
"bounds": [0.0, 0.0, 80.0, 42.0],
"source_file": "A208.dxf",
"footprint": {
"method": "concave_hull",
"source_categories": ["walls", "glazing", "floor_lines", "railings", "columns"],
"area": 3120.4,
"polygons": [
[[0.0, 0.0], [80.0, 0.0], [80.0, 42.0], [0.0, 42.0]]
]
},
"segments": {
"walls": [],
"glazing": [],
"roof": [],
"columns": [],
"beams": [],
"railings": [],
"doors": [],
"detail_lines": [],
"floor_lines": [],
"grid": []
}
}
}
}
```
## Segment Shape
Each segment is a straight prism centerline in meters:
```json
{
"start": [12.0, 3.5],
"end": [18.0, 3.5],
"width": 0.2,
"layer": "I-WALL",
"source_type": "LINE"
}
```
Use short chord segments for polylines and arcs. The showcase model does not need exact NURBS/curve preservation unless the user asks for close-up modeling.
`derive_showcase_spec.py` supports `LINE`, `LWPOLYLINE`, `POLYLINE`, `ARC`, `CIRCLE`, and `SPLINE` by converting curves into short line segments. Configure curve density with `curve_chord_source_length`.
It can also expand `INSERT` blocks when the Agent enables `expand_blocks`. Keep the block expansion decision in the config so the final notes can explain whether block geometry was used.
## Category Semantics
- `walls`: vertical extrusions from floor `z` to `z + height`. Include architectural wall layers and obvious site/partition wall layers.
- `glazing`: transparent full-height extrusions for curtain wall, window wall, or glass layers. Keep separate from opaque walls so missing walls are not confused with glass.
- `roof`: opaque or near-opaque cover geometry for roof slabs, canopies, or generated roof caps. It may be generated from `roof_specs` instead of direct CAD roof line segments when roof drawings are sparse.
- `columns`: vertical extrusions from floor `z` to `z + height`. For CAD outlines, extrude the visible outline linework rather than trying to infer a single solid column unless the source is clean.
- `beams`: horizontal extrusions near the floor ceiling, normally `z + height - beam_drop` to `z + height`.
- `railings`: low vertical extrusions, normally about 1.1-1.2 m above the floor.
- `doors`: door leaf/opening arcs and swing lines, normally about 2.1-2.3 m above the floor for visual context.
- `detail_lines`: low plan strips for generic details, parking, area, thin detail, and other high-value linework that should remain visible without being misclassified as vertical walls.
- `floor_lines`: low visual strips just above the slab. Use for floor finish edges and important plan guide lines that are not better represented by a specific category.
- `grid`: thin low strips. Use for axes/control grid only; keep toggleable.
- `slab`: generated by Blender script from each floor `footprint.polygons` when present, otherwise from `bounds`. A footprint slab is a CAD-derived visual plate, not a validated BIM slab with openings, joins, quantities, or fire/acoustic properties.
## Footprint Shape
`derive_showcase_spec.py` can generate `floor.footprint` when the Agent enables footprint generation in the extraction config.
- `method`: usually `concave_hull`.
- `source_categories`: categories used to collect source points, commonly `walls`, `glazing`, `floor_lines`, `railings`, and `columns`.
- `area`: total footprint polygon area in square meters after simplification.
- `polygons`: one or more closed polygon rings in meters. Keep only high-confidence, high-area polygons; do not include annotation islands or tiny hatch fragments.
Blender uses these polygons for generated `slab` meshes and can also use them for generated roof/roof-cap meshes. This improves visual accuracy compared with rectangular bounds but is still a presentation approximation unless BIM semantics are generated separately.
## Generation Config Keys
Common `source.config` keys used by `derive_showcase_spec.py` and `build_blender_showcase.py`:
- `generate_footprints`: enables CAD-derived `floor.footprint`.
- `footprint_categories`: source segment categories for footprints. For presentation models, include `columns` when column rows define usable floor plate extents.
- `footprint_concave_ratio`, `footprint_simplify_tolerance`, `footprint_min_area`, `footprint_max_polygons`: tune the concave hull and remove noise.
- `use_footprint_slabs`: use `floor.footprint.polygons` instead of rectangular `bounds` for generated `slab`.
- `use_footprint_roofs`: allow `roof_specs[].footprint_from` polygons to drive generated roof caps.
- `slab_thickness`: display thickness in meters. Use about `0.35-0.40` for Web presentation so floor edges remain visible through glazing.
- `roof_specs[]`: generated roof/canopy definitions. Use `floor_key`, `bounds_from`, and `footprint_from`; do not union lower-floor footprints unless there is CAD evidence for an overhang.
- `shorten_unsupported_columns`: shortens display columns that have no upper support.
- `shorten_unsupported_columns_floor_keys`: optional floor-key filter, commonly ground or podium levels.
- `unsupported_column_height`: shortened display height in meters.
- `column_support_distance`: XY tolerance for matching upper structural support.
- `column_support_requires_upper_plate`: require an adjacent upper floor/roof footprint before accepting nearby upper structure as support.
- `column_support_allow_plate_only`: if true, an upper plate alone is enough support; leave false when broad footprints would keep too many isolated columns.
## Object Naming
Blender objects for Web output must use:
```text
<floor_key>__<category>
```
Examples:
- `1F__walls`
- `RF__roof`
- `B1__columns`
- `RF__grid`
The Web template parses this double-underscore pattern.
## Metadata
`build_blender_showcase.py` writes `model_metadata.json` for the Web viewer. Keep it aligned with `building_spec.json` and include:
- project name/description
- ordered floors with keys/names/z values
- category labels/colors
- model bounds
- generated file names
- optional `viewer_defaults.disabled_categories`; keep `slab` enabled for presentation/digital-twin views
- optional `model_variants`, normally written by `write_web_showcase.py` from `variants_manifest.json`, for example:
```json
[
{"key": "overview", "label": "总览轻量版", "file": "overview.glb"},
{"key": "standard", "label": "展示标准版", "file": "standard.glb"},
{"key": "detail", "label": "完整审图版", "file": "detail.glb"}
]
```
## Precision Labels
Use these labels in notes:
- `Web showcase`: visual architectural walkthrough/exploded diagram from CAD linework.
- `Massing/LOD100-150`: slabs, walls, columns, beams, floor lines, grid; not parametric BIM.
- `BIM proof`: IFC entities exist and validate, but may not be production BIM.
- `BIM replacement candidate`: only after semantic IFC, openings, spaces, quantities, materials, levels, and coordination checks pass.