198 lines
9.1 KiB
Markdown
198 lines
9.1 KiB
Markdown
# building_spec.json Schema
|
|
|
|
Use `building_spec.json` as the versioned contract between extraction, Blender, trimesh, IFC, and Web delivery. The executable schema is `schemas/building_spec.schema.json`; validate with `python3 scripts/showcase_schema.py spec <file>`.
|
|
|
|
## Contents
|
|
|
|
1. Top-level contract
|
|
2. Segment/category/footprint semantics
|
|
3. Generation config keys
|
|
4. Object naming and metadata
|
|
5. Precision labels
|
|
|
|
## Top Level
|
|
|
|
```json
|
|
{
|
|
"schema_version": 1,
|
|
"project": {
|
|
"name": "Project name",
|
|
"description": "Short user-facing description"
|
|
},
|
|
"source": {
|
|
"dxf_dir": "work/cad_showcase/dxf_sanitized",
|
|
"config": {
|
|
"config_version": 1,
|
|
"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": []
|
|
},
|
|
"caps": [
|
|
{"z": 4.2, "polygons": [[[0, 0], [80, 0], [80, 42], [0, 42]]]}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 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.
|
|
- `cap_groups`: ordered `[pattern, group]` pairs used by derive and both exporters; `floor.caps` is the canonical generated-cap geometry.
|
|
|
|
Unknown config keys, duplicate floor keys, missing source files, incomplete `floor_order`, empty floors, and unsupported schema versions are hard validation failures. The exporters consume canonical `floor.caps`; they do not independently choose another floor grouping.
|
|
|
|
## 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.
|