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>
8.3 KiB
building_spec.json Schema
Use building_spec.json as the contract between CAD extraction, Blender generation, and the Web showcase.
Top Level
{
"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:
{
"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 floorztoz + 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 fromroof_specsinstead of direct CAD roof line segments when roof drawings are sparse.columns: vertical extrusions from floorztoz + 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, normallyz + height - beam_droptoz + 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 floorfootprint.polygonswhen present, otherwise frombounds. 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: usuallyconcave_hull.source_categories: categories used to collect source points, commonlywalls,glazing,floor_lines,railings, andcolumns.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-derivedfloor.footprint.footprint_categories: source segment categories for footprints. For presentation models, includecolumnswhen 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: usefloor.footprint.polygonsinstead of rectangularboundsfor generatedslab.use_footprint_roofs: allowroof_specs[].footprint_frompolygons to drive generated roof caps.slab_thickness: display thickness in meters. Use about0.35-0.40for Web presentation so floor edges remain visible through glazing.roof_specs[]: generated roof/canopy definitions. Usefloor_key,bounds_from, andfootprint_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:
<floor_key>__<category>
Examples:
1F__wallsRF__roofB1__columnsRF__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; keepslabenabled for presentation/digital-twin views - optional
model_variants, normally written bywrite_web_showcase.pyfromvariants_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.