bimdown-cli 0.4.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/README.md +24 -3
  2. package/dist/chunk-4SKM4RHY.js +142 -0
  3. package/dist/chunk-4SKM4RHY.js.map +1 -0
  4. package/dist/chunk-4YHVOWS4.js +255 -0
  5. package/dist/chunk-4YHVOWS4.js.map +1 -0
  6. package/dist/chunk-AYAXRYGP.js +2129 -0
  7. package/dist/chunk-AYAXRYGP.js.map +1 -0
  8. package/dist/chunk-EC5MR5ZH.js +648 -0
  9. package/dist/chunk-EC5MR5ZH.js.map +1 -0
  10. package/dist/chunk-HS3PO2LB.js +487 -0
  11. package/dist/chunk-HS3PO2LB.js.map +1 -0
  12. package/dist/chunk-IQJA3EFO.js +179 -0
  13. package/dist/chunk-IQJA3EFO.js.map +1 -0
  14. package/dist/chunk-JY6KWRDB.js +80 -0
  15. package/dist/chunk-JY6KWRDB.js.map +1 -0
  16. package/dist/chunk-KWSGJUMZ.js +2501 -0
  17. package/dist/chunk-KWSGJUMZ.js.map +1 -0
  18. package/dist/chunk-LWYIPR64.js +35 -0
  19. package/dist/chunk-LWYIPR64.js.map +1 -0
  20. package/dist/chunk-OBY3UYCO.js +44 -0
  21. package/dist/chunk-OBY3UYCO.js.map +1 -0
  22. package/dist/chunk-XC6WHJRL.js +29 -0
  23. package/dist/chunk-XC6WHJRL.js.map +1 -0
  24. package/dist/chunk-XQU52JKB.js +187 -0
  25. package/dist/chunk-XQU52JKB.js.map +1 -0
  26. package/dist/clash-load-D3LNQR6G.js +941 -0
  27. package/dist/clash-load-D3LNQR6G.js.map +1 -0
  28. package/dist/cli.js +306 -3377
  29. package/dist/cli.js.map +1 -1
  30. package/dist/dehydrate-ZHAGOI7Q.js +90 -0
  31. package/dist/dehydrate-ZHAGOI7Q.js.map +1 -0
  32. package/dist/diff-T2KOK2WR.js +89 -0
  33. package/dist/diff-T2KOK2WR.js.map +1 -0
  34. package/dist/engine-2TPWJVEQ.js +12 -0
  35. package/dist/engine-2TPWJVEQ.js.map +1 -0
  36. package/dist/hydrate-V24H7IF3.js +673 -0
  37. package/dist/hydrate-V24H7IF3.js.map +1 -0
  38. package/dist/import-ifc-RCZSXDA6.js +5324 -0
  39. package/dist/import-ifc-RCZSXDA6.js.map +1 -0
  40. package/dist/info-QC7YXWNX.js +92 -0
  41. package/dist/info-QC7YXWNX.js.map +1 -0
  42. package/dist/init-VWDML3UC.js +112 -0
  43. package/dist/init-VWDML3UC.js.map +1 -0
  44. package/dist/lib.d.ts +427 -44
  45. package/dist/lib.js +6482 -225
  46. package/dist/lib.js.map +1 -1
  47. package/dist/mep-W4HJI363.js +25 -0
  48. package/dist/mep-W4HJI363.js.map +1 -0
  49. package/dist/merge-ESOPDSA5.js +413 -0
  50. package/dist/merge-ESOPDSA5.js.map +1 -0
  51. package/dist/publish-3TAXQCUV.js +80 -0
  52. package/dist/publish-3TAXQCUV.js.map +1 -0
  53. package/dist/render-UEWYHPN6.js +1807 -0
  54. package/dist/render-UEWYHPN6.js.map +1 -0
  55. package/dist/resolve-topology-AQ2RO3W3.js +338 -0
  56. package/dist/resolve-topology-AQ2RO3W3.js.map +1 -0
  57. package/dist/spec/csv-schema/annotation/dimension.yaml +77 -0
  58. package/dist/spec/csv-schema/annotation/tag.yaml +44 -0
  59. package/dist/spec/csv-schema/annotation/text_note.yaml +52 -0
  60. package/dist/spec/csv-schema/architecture/ceiling.yaml +8 -1
  61. package/dist/spec/csv-schema/architecture/column.yaml +5 -1
  62. package/dist/spec/csv-schema/architecture/curtain_wall.yaml +45 -5
  63. package/dist/spec/csv-schema/architecture/door.yaml +5 -0
  64. package/dist/spec/csv-schema/architecture/furniture.yaml +28 -0
  65. package/dist/spec/csv-schema/architecture/opening.yaml +27 -6
  66. package/dist/spec/csv-schema/architecture/railing.yaml +35 -0
  67. package/dist/spec/csv-schema/architecture/roof.yaml +34 -1
  68. package/dist/spec/csv-schema/architecture/slab.yaml +19 -0
  69. package/dist/spec/csv-schema/architecture/space.yaml +11 -1
  70. package/dist/spec/csv-schema/architecture/stair.yaml +49 -0
  71. package/dist/spec/csv-schema/architecture/stair_landing.yaml +36 -0
  72. package/dist/spec/csv-schema/architecture/stair_run.yaml +31 -0
  73. package/dist/spec/csv-schema/architecture/wall.yaml +14 -1
  74. package/dist/spec/csv-schema/architecture/window.yaml +19 -0
  75. package/dist/spec/csv-schema/base/element.yaml +20 -11
  76. package/dist/spec/csv-schema/base/furniture_params.yaml +60 -0
  77. package/dist/spec/csv-schema/base/hosted_element.yaml +10 -2
  78. package/dist/spec/csv-schema/base/mep_connectable.yaml +23 -0
  79. package/dist/spec/csv-schema/base/mep_design.yaml +24 -0
  80. package/dist/spec/csv-schema/base/mep_insulated.yaml +9 -0
  81. package/dist/spec/csv-schema/base/mep_system_tag.yaml +12 -0
  82. package/dist/spec/csv-schema/base/point_element.yaml +1 -0
  83. package/dist/spec/csv-schema/base/section_profile.yaml +5 -0
  84. package/dist/spec/csv-schema/base/spatial_line_element.yaml +4 -2
  85. package/dist/spec/csv-schema/base/structural_section_profile.yaml +50 -0
  86. package/dist/spec/csv-schema/base/vertical_span.yaml +5 -4
  87. package/dist/spec/csv-schema/base/wall_bounded.yaml +21 -0
  88. package/dist/spec/csv-schema/grid.yaml +5 -0
  89. package/dist/spec/csv-schema/mep/cable_tray.yaml +10 -3
  90. package/dist/spec/csv-schema/mep/circuit.yaml +70 -0
  91. package/dist/spec/csv-schema/mep/conduit.yaml +2 -2
  92. package/dist/spec/csv-schema/mep/connector.yaml +112 -0
  93. package/dist/spec/csv-schema/mep/duct.yaml +10 -3
  94. package/dist/spec/csv-schema/mep/equipment.yaml +18 -1
  95. package/dist/spec/csv-schema/mep/mep_node.yaml +91 -2
  96. package/dist/spec/csv-schema/mep/mep_system.yaml +21 -0
  97. package/dist/spec/csv-schema/mep/pipe.yaml +27 -3
  98. package/dist/spec/csv-schema/mep/terminal.yaml +22 -1
  99. package/dist/spec/csv-schema/model_group.yaml +40 -0
  100. package/dist/spec/csv-schema/sheet/sheet.yaml +50 -0
  101. package/dist/spec/csv-schema/sheet/sheet_viewport.yaml +86 -0
  102. package/dist/spec/csv-schema/structure/beam.yaml +29 -1
  103. package/dist/spec/csv-schema/structure/beam_system.yaml +29 -0
  104. package/dist/spec/csv-schema/structure/brace.yaml +24 -1
  105. package/dist/spec/csv-schema/structure/foundation.yaml +40 -7
  106. package/dist/spec/csv-schema/structure/structure_column.yaml +19 -1
  107. package/dist/spec/csv-schema/structure/structure_slab.yaml +32 -0
  108. package/dist/spec/csv-schema/structure/structure_wall.yaml +22 -0
  109. package/dist/spec/csv-schema/types/beam_type.yaml +11 -0
  110. package/dist/spec/csv-schema/types/ceiling_type.yaml +6 -0
  111. package/dist/spec/csv-schema/types/column_type.yaml +12 -0
  112. package/dist/spec/csv-schema/types/curtain_wall_type.yaml +32 -0
  113. package/dist/spec/csv-schema/types/door_type.yaml +27 -0
  114. package/dist/spec/csv-schema/types/element_type.yaml +21 -0
  115. package/dist/spec/csv-schema/types/fenestration.yaml +16 -0
  116. package/dist/spec/csv-schema/types/foundation_type.yaml +36 -0
  117. package/dist/spec/csv-schema/types/furniture_type.yaml +11 -0
  118. package/dist/spec/csv-schema/types/layered_type.yaml +13 -0
  119. package/dist/spec/csv-schema/types/railing_type.yaml +40 -0
  120. package/dist/spec/csv-schema/types/roof_type.yaml +7 -0
  121. package/dist/spec/csv-schema/types/slab_type.yaml +9 -0
  122. package/dist/spec/csv-schema/types/type_layer.yaml +47 -0
  123. package/dist/spec/csv-schema/types/wall_type.yaml +6 -0
  124. package/dist/spec/csv-schema/types/window_type.yaml +31 -0
  125. package/dist/spec/csv-schema/underlay.yaml +73 -0
  126. package/dist/spec/csv-schema/view.yaml +36 -0
  127. package/dist/spec/duckdb-strategy.md +4 -3
  128. package/dist/spec/geojson-schema/readme.md +380 -0
  129. package/dist/spec/mep-port-conventions.md +190 -0
  130. package/dist/spec/migration-guide.md +1 -1
  131. package/dist/spec/project_metadata.schema.yaml +52 -4
  132. package/dist/spec/readme.md +356 -97
  133. package/dist/spec/starter-types/global/beam_type.csv +5 -0
  134. package/dist/spec/starter-types/global/ceiling_type.csv +3 -0
  135. package/dist/spec/starter-types/global/column_type.csv +5 -0
  136. package/dist/spec/starter-types/global/curtain_wall_type.csv +2 -0
  137. package/dist/spec/starter-types/global/door_type.csv +6 -0
  138. package/dist/spec/starter-types/global/foundation_type.csv +7 -0
  139. package/dist/spec/starter-types/global/furniture_type.csv +11 -0
  140. package/dist/spec/starter-types/global/railing_type.csv +5 -0
  141. package/dist/spec/starter-types/global/roof_type.csv +3 -0
  142. package/dist/spec/starter-types/global/slab_type.csv +4 -0
  143. package/dist/spec/starter-types/global/type_layer.csv +40 -0
  144. package/dist/spec/starter-types/global/wall_type.csv +8 -0
  145. package/dist/spec/starter-types/global/window_type.csv +6 -0
  146. package/dist/spec/svg-schema/readme.md +47 -1
  147. package/package.json +6 -3
  148. package/dist/spec/csv-schema/base/mep_connected_segment.yaml +0 -17
  149. package/dist/spec/csv-schema/base/mep_system.yaml +0 -7
@@ -0,0 +1,73 @@
1
+ name: underlay
2
+ description: |
3
+ A reference drawing placed under one level for tracing (raster image, one
4
+ PDF page, or DXF vectors). Not a building element: build, render, query and
5
+ exports ignore it. The source file lives in `underlays/` at the project root.
6
+ Placement maps the file's own coordinates (image pixels with the origin at
7
+ the bottom-left, PDF points from the page's bottom-left, DXF drawing units)
8
+ to plan coordinates: plan = (x, y) + rotate(rotation) · (scale · local).
9
+
10
+ fields:
11
+ - name: id
12
+ type: string
13
+ required: true
14
+
15
+ - name: name
16
+ type: string
17
+ description: Display name (defaults to the file name)
18
+
19
+ - name: level_id
20
+ type: reference
21
+ reference: level
22
+ required: true
23
+ description: Level whose plan view shows the underlay
24
+
25
+ - name: file
26
+ type: string
27
+ required: true
28
+ description: Path relative to the project root, under underlays/ (.png, .jpg, .jpeg, .webp, .pdf, .dxf)
29
+
30
+ - name: page
31
+ type: int
32
+ default: 1
33
+ description: PDF page number (1-based); ignored for images and DXF
34
+
35
+ - name: x
36
+ type: float
37
+ default: 0
38
+ description: Plan X of the file's local origin
39
+
40
+ - name: y
41
+ type: float
42
+ default: 0
43
+ description: Plan Y of the file's local origin
44
+
45
+ - name: rotation
46
+ type: float
47
+ default: 0
48
+ description: Counter-clockwise rotation in degrees about the local origin
49
+
50
+ - name: scale
51
+ type: float
52
+ default: 1
53
+ description: Project units per local unit (per pixel, PDF point or DXF unit); set by two-point calibration
54
+
55
+ - name: opacity
56
+ type: float
57
+ default: 0.5
58
+ description: 0 (invisible) to 1 (opaque)
59
+
60
+ - name: visible
61
+ type: enum
62
+ values: ["true", "false"]
63
+ default: "true"
64
+
65
+ - name: locked
66
+ type: enum
67
+ values: ["true", "false"]
68
+ default: "false"
69
+ description: A locked underlay can't be moved, rotated or calibrated
70
+
71
+ - name: hidden_layers
72
+ type: string
73
+ description: DXF layer names turned off, separated by ";"
@@ -0,0 +1,36 @@
1
+ name: view
2
+ description: "Saved drawing views (global/view.csv only). A `section` is a vertical cut along the plan line start→end, looking to the LEFT of that direction (a line drawn west→east looks north). Elevations and plans are derived and need no rows."
3
+
4
+ fields:
5
+ - name: id
6
+ type: string
7
+ required: true
8
+
9
+ - name: name
10
+ type: string
11
+
12
+ - name: view_type
13
+ type: enum
14
+ required: true
15
+ values:
16
+ - section
17
+
18
+ - name: start_x
19
+ type: float
20
+ required: true
21
+
22
+ - name: start_y
23
+ type: float
24
+ required: true
25
+
26
+ - name: end_x
27
+ type: float
28
+ required: true
29
+
30
+ - name: end_y
31
+ type: float
32
+ required: true
33
+
34
+ - name: depth
35
+ type: float
36
+ description: Far clip distance in front of the cut line (project units). Empty = unlimited.
@@ -73,13 +73,14 @@ AI designs MEP networks by placing duct/pipe segments with endpoint coordinates.
73
73
  1. Collects all MEP segment endpoints and equipment/terminal positions.
74
74
  2. Detects coincident coordinates (within tolerance).
75
75
  3. Auto-generates `mep_node` entries at pure junction points (where no equipment/terminal exists).
76
- 4. Back-fills `start_node_id` and `end_node_id` on each duct/pipe/cable_tray/conduit.
76
+ 4. Back-fills `from` and `to` on each duct/pipe/cable_tray/conduit. Values are port refs of the form `host_id:port_name` (or bare `host_id` for passive fittings). See [`mep-port-conventions.md`](mep-port-conventions.md).
77
77
 
78
78
  After resolution, DuckDB graph queries work naturally:
79
79
  ```sql
80
- -- Find all ducts connected to equipment eq-1
80
+ -- Find all ducts connected to equipment eq-1 (any port)
81
81
  SELECT d.* FROM duct d
82
- WHERE d.start_node_id = 'eq-1' OR d.end_node_id = 'eq-1';
82
+ WHERE d.from = 'eq-1' OR d.to = 'eq-1'
83
+ OR d.from LIKE 'eq-1:%' OR d.to LIKE 'eq-1:%';
83
84
  ```
84
85
 
85
86
  ---
@@ -0,0 +1,380 @@
1
+ # BimDown GeoJSON Spec
2
+
3
+ GeoJSON is one of **two interchangeable geometry storage layers** for BimDown — the other is [SVG](../svg-schema/readme.md). Both are first-class and fully supported; a project picks one, declared by `format_version` (see §9). GeoJSON (`format_version: 2`) is the **default for new projects** and the encoding the BimClaw editor consumes. It was chosen as the default after empirical testing on Gemini 3 Flash: it produces equivalent or better AI generation/edit quality at lower token cost, has native 3D support, and integrates with the GIS toolchain (turf.js, DuckDB spatial). The SVG encoding (`format_version: 1`) remains fully supported for 2D projects and for tools with existing SVG pipelines.
4
+
5
+ GeoJSON files are **not** used for visualization — they are a structured geometry storage format. The editor and renderers consume the parsed canonical element model, not raw GeoJSON.
6
+
7
+ ---
8
+
9
+ ## 1. File Organization
10
+
11
+ GeoJSON files are co-located with their CSV counterparts, organized by level:
12
+
13
+ ```text
14
+ {project-id}/
15
+ {level}/
16
+ wall.csv wall.geojson
17
+ column.csv column.geojson
18
+ slab.csv slab.geojson
19
+ door.csv # no geometry file (hosted)
20
+ window.csv # no geometry file (hosted)
21
+ space.csv # no geometry file (seed point in CSV)
22
+ ...
23
+ global/
24
+ level.csv grid.csv # global reference, CSV only
25
+ wall.geojson # multi-story walls
26
+ curtain_wall.geojson
27
+ pipe.geojson # vertical pipe risers
28
+ ...
29
+ ```
30
+
31
+ Each `.geojson` file is a single `FeatureCollection` whose `features[]` contains one Feature per element row in the paired CSV.
32
+
33
+ ### Partitioning Rules
34
+
35
+ All elements belong to a **base level**, and **`base_level_id` is always the level of the containing directory** — never cross-directory. To express cross-level geometry:
36
+
37
+ - Element confined to its base level (single-story wall, slab on one level): goes in that level directory.
38
+ - Element extending more than one level above its base (multi-story wall, vertical pipe riser): goes in `global/`.
39
+ - `level.csv` and `grid.csv`: global reference data, always in `global/`.
40
+
41
+ Consequence: when parsing or editing a single level view, agents and tools only need to load **two directories** — the current level and `global/`.
42
+
43
+ ### Elements Without Geometry File
44
+
45
+ These element types have no `.geojson` file; their geometry is fully expressed in CSV:
46
+
47
+ | Element | Reason |
48
+ |---|---|
49
+ | `door`, `window`, wall `opening` | Hosted on wall (CSV: `host_id` + `position` along host) |
50
+ | `space` | Seed point `(x, y, z)` in CSV; boundary auto-derived by `build` |
51
+ | `level`, `grid` | Global reference data with coordinates in CSV |
52
+ | `mesh` | Geometry is the referenced GLB file |
53
+
54
+ ---
55
+
56
+ ## 2. Coordinate System
57
+
58
+ - **Units**: meters
59
+ - **Origin**: project Cartesian origin `(0, 0, 0)`
60
+ - **Axes**: `+X` = East, `+Y` = North, `+Z` = Up (architectural convention)
61
+ - **Coordinate dimension**: 2D `[x, y]` or 3D `[x, y, z]` — element-dependent (see §4)
62
+ - **CRS**: BimDown coordinates are project-local, **not** geographic. Do not emit a `crs` member; per GeoJSON RFC 7946 the absence implies WGS84, but readers must treat BimDown coordinates as local Cartesian. Parsers can rely on `project_metadata.json` `units: "m"` to disambiguate.
63
+
64
+ ---
65
+
66
+ ## 3. GeoJSON Subset
67
+
68
+ ### Allowed Geometry Types
69
+
70
+ | GeoJSON type | BimDown usage |
71
+ |---|---|
72
+ | `Point` | Point elements (column, equipment, terminal, mep_node) |
73
+ | `LineString` | Line elements (wall, beam, duct, stair, ramp, …) — always exactly 2 coordinates in canonical form |
74
+ | `Polygon` | Polygon elements (slab, ceiling, roof, slab opening) — single outer ring, optional inner rings for holes |
75
+
76
+ `MultiPoint`, `MultiLineString`, `MultiPolygon`, `GeometryCollection` are **forbidden in canonical (build-output) form**. An element with disconnected sub-geometries must be split into multiple Features with suffixed IDs (`sl-18ba`, `sl-18bb`).
77
+
78
+ AI may submit any geometry type as input; build normalizes to canonical (see §6).
79
+
80
+ ### Feature Shape
81
+
82
+ Every Feature **must** have:
83
+ - `properties.id` matching the paired CSV row's `id` field
84
+ - a non-null `geometry`
85
+
86
+ ```jsonc
87
+ {
88
+ "type": "FeatureCollection",
89
+ "features": [
90
+ {
91
+ "type": "Feature",
92
+ "properties": { "id": "w-1" /*, …optional geometry hints… */ },
93
+ "geometry": { "type": "LineString", "coordinates": [[0, 0], [5, 0]] }
94
+ }
95
+ ]
96
+ }
97
+ ```
98
+
99
+ ### Forbidden in Canonical Form
100
+
101
+ - `MultiPolygon` / `MultiLineString` / `MultiPoint` / `GeometryCollection`
102
+ - Properties unrelated to geometry (use CSV for attributes; see §5)
103
+ - `bbox` member (computed by hydrate, not stored)
104
+ - `crs` member
105
+
106
+ ---
107
+
108
+ ## 4. Z-Axis Handling
109
+
110
+ LLM spatial arithmetic is unreliable. BimDown therefore encodes Z **semantically** (by level reference) for level-anchored elements, and only uses **absolute Z in coordinates** when the element genuinely lives in free 3D space.
111
+
112
+ ### 4.1 Level-Anchored Elements → 2D Coordinates + Level Properties
113
+
114
+ Walls, columns, slabs, ceilings, roofs, curtain walls, room separators, and any element whose Z is defined relative to a floor level.
115
+
116
+ - `geometry.coordinates` are 2D `[x, y]`
117
+ - Numeric Z lives in GeoJSON `properties` (default values mean it can be omitted entirely):
118
+ - `base_offset` (float, meters, default `0`) — vertical offset from `base_level_id`
119
+ - `top_offset` (float, meters, default `0`) — vertical offset from `top_level_id`
120
+ - Level references (FKs) live in **CSV**, consistent with all other FKs (`host_id`, etc.) and supporting tabular queries like "walls spanning lv-1 → lv-3":
121
+ - `base_level_id` — defaults to the containing directory's level (implicit for level-N/, must be set explicitly in `global/`)
122
+ - `top_level_id` — defaults to the level immediately above `base_level_id`
123
+
124
+ Result: changing a level's elevation in `level.csv` automatically updates every anchored element's Z without touching geometry files; "all elements spanning lv-2 to lv-4" is a CSV column filter.
125
+
126
+ ```jsonc
127
+ // canonical: single-story wall on lv-1, full height
128
+ {
129
+ "type": "Feature",
130
+ "properties": { "id": "w-1" },
131
+ "geometry": { "type": "LineString", "coordinates": [[0, 0], [5, 0]] }
132
+ }
133
+ // base_level_id is implicit (lv-1 from directory); top_level_id default = lv-2;
134
+ // base_offset = 0; top_offset = 0.
135
+ ```
136
+
137
+ ```jsonc
138
+ // canonical: column on lv-1, base 0.1m above slab, top -0.05m below lv-2 ceiling
139
+ {
140
+ "type": "Feature",
141
+ "properties": {
142
+ "id": "c-3",
143
+ "base_offset": 0.1,
144
+ "top_offset": -0.05,
145
+ "section": { "shape": "rect", "size_x": 0.4, "size_y": 0.4, "rotation": 0 }
146
+ },
147
+ "geometry": { "type": "Point", "coordinates": [2.0, 2.0] }
148
+ }
149
+ ```
150
+
151
+ ### 4.2 Spatial Elements → 3D Coordinates
152
+
153
+ Beams, braces, stairs, ramps, railings, ducts, pipes, cable trays, conduits — elements whose endpoint Z is genuinely 3D design input rather than "as tall as the floor".
154
+
155
+ - `geometry.coordinates` are 3D `[x, y, z]`
156
+ - Z is **absolute** in project coordinates (meters)
157
+ - `base_level_id` is still implicit from the containing directory (used for partitioning and queries, not for geometry)
158
+ - Spatial elements should be placed in the level directory they primarily belong to. Only elements that genuinely span multiple levels (e.g. a vertical pipe riser) go in `global/`.
159
+
160
+ ```jsonc
161
+ // canonical: beam on lv-2, slightly sloped
162
+ {
163
+ "type": "Feature",
164
+ "properties": { "id": "bm-7" },
165
+ "geometry": { "type": "LineString", "coordinates": [[0, 0, 3.5], [10, 5, 3.7]] }
166
+ }
167
+ ```
168
+
169
+ ### 4.3 Why Two Modes
170
+
171
+ | Concern | Level-anchored mode | Spatial mode |
172
+ |---|---|---|
173
+ | LLM arithmetic on level elevations | avoided (no Z in coords) | required (small, scoped) |
174
+ | Resilience to level elevation edits | automatic | manual update needed |
175
+ | Natural expression for designer/AI | "wall on lv-1" | "duct at z=3.7m" |
176
+ | Suits | wall, column, slab, ceiling, roof, curtain_wall | beam, brace, stair, ramp, duct, pipe, etc. |
177
+
178
+ ---
179
+
180
+ ## 5. Attribute Split: CSV vs `properties`
181
+
182
+ Empirical testing showed CSV-for-attributes / file-for-geometry beats both extremes. This spec keeps that split with a strict rule:
183
+
184
+ | Goes in | What |
185
+ |---|---|
186
+ | **CSV** | All scalar attributes (material, thickness, function, operation, size_x, size_y, shape, …), enum values, foreign keys (`host_id`, `base_level_id`, `top_level_id`), parametric placement (`position`), `id`, `number` |
187
+ | **GeoJSON `properties`** | `id` (link to CSV) + **numeric geometry hints only** — Z offsets (`base_offset`, `top_offset`), curve params (`arc`), point orientation (`rotation`) |
188
+ | **Neither (computed)** | `length`, `area`, `height`, `start_x/y/z`, `end_x/y/z`, `x`, `y`, `rotation`, `points`, `volume`, `bbox_*` |
189
+
190
+ Rationale:
191
+ - CSV is dense and tabular — LLMs are strong at column-wise reasoning and bulk edits.
192
+ - Per-Feature property bags would repeat keys for every element (1000 walls × all keys), inflating tokens 2-3×.
193
+ - Geometry-disambiguating hints are **logically part of the geometry** (you cannot draw a rectangular column without knowing its size), so they belong adjacent to the geometry.
194
+
195
+ If a future field is unclear, ask: *"does this define what the geometry looks like, or does it describe what the element is?"* The former → properties. The latter → CSV.
196
+
197
+ ---
198
+
199
+ ## 6. AI Input Flexibility & Build Normalization
200
+
201
+ To accommodate LLMs that prefer one representation over another, BimDown accepts multiple equivalent inputs and normalizes them during `bimdown build`. **The editor and downstream consumers only see canonical form.**
202
+
203
+ ### 6.1 Arc Lines (Walls, Curtain Walls, Ramps, Railings, etc.)
204
+
205
+ Canonical: 2-point `LineString` + `properties.arc`.
206
+
207
+ | AI input variant | Build detects | Normalized to |
208
+ |---|---|---|
209
+ | `LineString` with 2 points, no `arc` property | straight line | unchanged |
210
+ | `LineString` with 2 points + `properties.arc = {radius, large_arc, sweep}` | already canonical | unchanged |
211
+ | `LineString` with N≥3 points where intermediate points lie on a circle through the endpoints (distance variance < ε) | tessellated arc | 2 endpoints + computed `properties.arc` |
212
+ | `LineString` with N≥3 collinear points | redundant polyline | first + last only |
213
+
214
+ `arc` schema:
215
+ ```jsonc
216
+ "arc": {
217
+ "radius": 3.0, // meters; sign convention: positive
218
+ "large_arc": false, // SVG-A semantics; false = arc < 180°
219
+ "sweep": true // false = counterclockwise from start to end (in +Y-up frame)
220
+ }
221
+ ```
222
+
223
+ ### 6.2 Point Elements with Section Profile (Columns, Equipment, MEP Nodes, Terminals)
224
+
225
+ Canonical: `Point` geometry; section attributes (`shape`, `size_x`, `size_y`) in **CSV**; orientation in `properties.rotation` if non-zero.
226
+
227
+ | AI input variant | Build behavior |
228
+ |---|---|
229
+ | `Point` + CSV `shape/size_x/size_y` | canonical; no rotation written (default `0`) |
230
+ | `Point` + `properties.rotation` | canonical; section from CSV |
231
+ | `Point` + `properties.section = {shape, size_x, size_y, rotation}` | extract `shape/size_x/size_y` into CSV; keep `rotation` in properties if non-zero; drop `section` bag |
232
+ | `Polygon` with 4 vertices, opposite sides parallel and equal | derive `shape="rect"`, `size_x`, `size_y` → CSV; derive `rotation` → properties; reduce geometry to `Point` at centroid |
233
+ | `Polygon` with N≥8 vertices, all equidistant from centroid | derive `shape="round"`, `size_x=size_y=2r` → CSV; reduce geometry to `Point` at center |
234
+ | `Point`, no `section`, CSV section empty | reject with validation error |
235
+
236
+ `rotation` in `properties`:
237
+ ```jsonc
238
+ "rotation": 30 // degrees, CCW about +Z axis, applied to the local section frame
239
+ ```
240
+
241
+ ### 6.3 Polygons (Slabs, Ceilings, Roofs, Slab Openings)
242
+
243
+ Canonical: `Polygon` with a closed outer ring (last coord = first coord), optional holes as inner rings.
244
+
245
+ | AI input variant | Build behavior |
246
+ |---|---|
247
+ | Unclosed ring (last coord ≠ first coord) | auto-close |
248
+ | Counterclockwise outer ring | rewind to clockwise (RFC 7946 §3.1.6 right-hand rule applied flipped for screen Y; build canonicalizes to **clockwise** in BimDown frame) |
249
+ | Self-intersecting ring | reject with validation error |
250
+ | `MultiPolygon` (disconnected) | split into multiple Features with suffix IDs (`sl-18ba`, `sl-18bb`); CSV row is duplicated |
251
+ | 3D coords on level-anchored polygon (all Z equal) | drop Z; if any vary, reject with error |
252
+
253
+ ### 6.4 Z-Axis Variants
254
+
255
+ | AI input | Build behavior |
256
+ |---|---|
257
+ | Level-anchored element with 2D coords | canonical |
258
+ | Level-anchored element with 3D coords (Z varies) | reject |
259
+ | Level-anchored element with 3D coords (Z constant) | drop Z; if Z != `base_level.elevation + base_offset`, recompute `base_offset` |
260
+ | Spatial element with 2D coords | reject (need Z); CLI suggests inferring from `base_level.elevation` |
261
+ | Spatial element with 3D coords | canonical |
262
+ | Element with `properties.base_offset` referring to non-containing-directory level | reject (`base_level_id` is structural, not data) |
263
+
264
+ ### 6.5 Other Normalizations (Inherited from Existing CLI)
265
+
266
+ - **Snap endpoints**: cluster nearby endpoints within tolerance `max(0.10m, max wall thickness)`. Works across `current_level/` and `global/` (the two-directory rule).
267
+ - **Resolve hosted coords**: door/window/opening `position` validated against host wall length.
268
+ - **Resolve MEP topology**: detect coincident curve endpoints, materialize `mep_node` entries, back-fill `from`/`to` (port refs `host_id:port_name`).
269
+ - **Compute space boundaries**: half-edge face tracing from walls + curtain_walls + room_separators + structure_walls; emit `space.geojson` with `Polygon` features. (Space CSV is source of truth for seed points; the generated `.geojson` is a build artifact.)
270
+ - **Auto-heal CSV ↔ geometry conflict**: if a CSV `required` field disagrees with hydrated geometry, CSV wins and geometry is corrected on next sync-out.
271
+
272
+ ---
273
+
274
+ ## 7. Canonical Forms by Element Type
275
+
276
+ | Element | Geometry | Mandatory properties | Optional properties |
277
+ |---|---|---|---|
278
+ | `wall`, `curtain_wall`, `room_separator` | `LineString` 2D, 2 points | — | `base_offset`, `top_offset`, `arc` |
279
+ | `stair`, `ramp`, `railing` | `LineString` 3D, 2 points | — | `arc` |
280
+ | `beam`, `brace` | `LineString` 3D, 2 points | — | `arc` |
281
+ | `duct`, `pipe`, `cable_tray`, `conduit` | `LineString` 3D, 2 points | — | — |
282
+ | `column`, `structure_column` | `Point` 2D | — | `base_offset`, `top_offset`, `rotation` |
283
+ | `equipment`, `terminal`, `mep_node` | `Point` 3D | — | `rotation` |
284
+ | `slab`, `ceiling`, `roof`, `structure_slab` | `Polygon` 2D, closed CW | — | `base_offset` |
285
+ | `slab_opening` (opening with slab host) | `Polygon` 2D, closed CW | — | — |
286
+ | `foundation` | `Point` 2D / `LineString` 2D / `Polygon` 2D (form chooses) | — | `base_offset`, `top_offset`, `rotation` (if point) |
287
+
288
+ Notes:
289
+ - `point_element` mixin computed fields (`x`, `y`, `rotation`) are hydrated from geometry + `properties.section.rotation`.
290
+ - `line_element` and `spatial_line_element` mixin computed fields (`start_x/y[/z]`, `end_x/y[/z]`, `length`) are hydrated from coordinates; arc length is computed from `properties.arc` when present.
291
+ - `polygon_element` mixin computed fields (`points`, `area`) are hydrated from coordinates.
292
+ - `vertical_span` mixin computed field (`height`) is hydrated as `top_level.elevation + top_offset − base_level.elevation − base_offset`.
293
+
294
+ ---
295
+
296
+ ## 8. Computed Field Hydration
297
+
298
+ | Computed field | Source |
299
+ |---|---|
300
+ | `start_x`, `start_y`, `start_z` | first coordinate of `LineString` (Z from coord for spatial, from `base_level.elevation + base_offset` for level-anchored) |
301
+ | `end_x`, `end_y`, `end_z` | last coordinate of `LineString` (Z same convention as above) |
302
+ | `length` | Euclidean distance along the line; if `properties.arc` present, computed as arc length |
303
+ | `x`, `y` | `Point` coordinates (Z from `base_level.elevation + base_offset` for level-anchored) |
304
+ | `rotation` | `properties.section.rotation` (default `0`) |
305
+ | `points` | flattened `"x1,y1 x2,y2 …"` string of outer ring vertices |
306
+ | `area` | shoelace on outer ring minus holes |
307
+ | `height` | `top_level.elevation + top_offset − base_level.elevation − base_offset` |
308
+ | `volume` | per-type formula (e.g. `area × height` for slabs, `length × thickness × height` for walls — straight only; arcs use polygon area) |
309
+ | `bbox_min_*`, `bbox_max_*` | from geometry + extruded height |
310
+ | `level_id` | base_level_id (= containing directory) |
311
+
312
+ ---
313
+
314
+ ## 9. Format Version
315
+
316
+ `project_metadata.json`:
317
+
318
+ ```json
319
+ {
320
+ "format_version": 2,
321
+ "project_name": "…",
322
+ "units": "m",
323
+ "source": "revit",
324
+ "spatial_z": "absolute"
325
+ }
326
+ ```
327
+
328
+ - `spatial_z: "absolute"` — optional marker that spatial coordinates follow §4.2 (absolute Z). Tools that guarantee it write it; a project without it may come from an older BimClaw editor that stored level-relative Z.
329
+
330
+ - `format_version: 1` — CSV + **SVG** (see [svg-schema/readme.md](../svg-schema/readme.md)). Fully supported; 2D geometry.
331
+ - `format_version: 2` — CSV + **GeoJSON** (this spec). Fully supported; 2D and 3D geometry. Default for new projects.
332
+
333
+ Both encodings are maintained; neither is deprecated. Tools may also detect the encoding directly from the geometry files present (`*.geojson` vs `*.svg`). To convert an existing SVG project to GeoJSON (e.g. to gain 3D fidelity for spatial elements), use `bimdown migrate svg-to-geojson <path>` or `scripts/svg-to-geojson.ts`.
334
+
335
+ ---
336
+
337
+ ## 10. Example Files
338
+
339
+ ### `lv-1/wall.csv`
340
+ ```csv
341
+ id,number,thickness,top_level_id,material
342
+ w-1,1,0.2,,concrete
343
+ w-2,2,0.2,,concrete
344
+ w-3,3,0.15,lv-3,gypsum
345
+ ```
346
+ (`w-3` spans lv-1 → lv-3; `top_level_id` empty for `w-1`/`w-2` means default = lv-2.)
347
+
348
+ ### `lv-1/wall.geojson`
349
+ ```json
350
+ {
351
+ "type": "FeatureCollection",
352
+ "features": [
353
+ { "type": "Feature", "properties": { "id": "w-1" },
354
+ "geometry": { "type": "LineString", "coordinates": [[0,0],[5,0]] } },
355
+ { "type": "Feature", "properties": { "id": "w-2",
356
+ "arc": { "radius": 3, "large_arc": false, "sweep": true } },
357
+ "geometry": { "type": "LineString", "coordinates": [[5,0],[5,6]] } },
358
+ { "type": "Feature", "properties": { "id": "w-3", "top_offset": -0.3 },
359
+ "geometry": { "type": "LineString", "coordinates": [[0,6],[0,0]] } }
360
+ ]
361
+ }
362
+ ```
363
+ Note: `w-3` is a 2-level wall, but per partitioning rules it should live in `global/` if it spans more than one level above its base. The example above is illustrative; the validator will warn.
364
+
365
+ ### `lv-2/beam.csv`
366
+ ```csv
367
+ id,number,material,structural_section_profile_shape,size_x,size_y
368
+ bm-1,1,steel,i,0.2,0.4
369
+ ```
370
+
371
+ ### `lv-2/beam.geojson`
372
+ ```json
373
+ {
374
+ "type": "FeatureCollection",
375
+ "features": [
376
+ { "type": "Feature", "properties": { "id": "bm-1" },
377
+ "geometry": { "type": "LineString", "coordinates": [[0,0,3.5],[10,0,3.5]] } }
378
+ ]
379
+ }
380
+ ```