# 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 __ ``` 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.