Files
cad-building-showcase/references/building_spec_schema.md

9.1 KiB

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

{
  "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:

{
  "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:

<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:
[
  {"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.