bimdown-cli 0.1.5 → 0.1.9
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.
- package/dist/index.js +709 -72
- package/dist/index.js.map +1 -1
- package/dist/spec/csv-schema/architecture/ceiling.yaml +9 -0
- package/dist/spec/csv-schema/architecture/column.yaml +8 -0
- package/dist/spec/csv-schema/architecture/curtain_wall.yaml +31 -0
- package/dist/spec/csv-schema/architecture/door.yaml +35 -0
- package/dist/spec/csv-schema/architecture/opening.yaml +36 -0
- package/dist/spec/csv-schema/architecture/railing.yaml +7 -0
- package/dist/spec/csv-schema/architecture/ramp.yaml +7 -0
- package/dist/spec/csv-schema/architecture/roof.yaml +22 -0
- package/dist/spec/csv-schema/architecture/room_separator.yaml +5 -0
- package/dist/spec/csv-schema/architecture/slab.yaml +15 -0
- package/dist/spec/csv-schema/architecture/space.yaml +17 -0
- package/dist/spec/csv-schema/architecture/stair.yaml +11 -0
- package/dist/spec/csv-schema/architecture/wall.yaml +11 -0
- package/dist/spec/csv-schema/architecture/window.yaml +13 -0
- package/dist/spec/csv-schema/base/element.yaml +60 -0
- package/dist/spec/csv-schema/base/hosted_element.yaml +15 -0
- package/dist/spec/csv-schema/base/line_element.yaml +25 -0
- package/dist/spec/csv-schema/base/materialized.yaml +22 -0
- package/dist/spec/csv-schema/base/mep_connected_segment.yaml +17 -0
- package/dist/spec/csv-schema/base/mep_system.yaml +7 -0
- package/dist/spec/csv-schema/base/point_element.yaml +17 -0
- package/dist/spec/csv-schema/base/polygon_element.yaml +14 -0
- package/dist/spec/csv-schema/base/section_profile.yaml +16 -0
- package/dist/spec/csv-schema/base/spatial_line_element.yaml +13 -0
- package/dist/spec/csv-schema/base/structural_section_profile.yaml +21 -0
- package/dist/spec/csv-schema/base/vertical_span.yaml +17 -0
- package/dist/spec/csv-schema/grid.yaml +26 -0
- package/dist/spec/csv-schema/level.yaml +17 -0
- package/dist/spec/csv-schema/mep/cable_tray.yaml +8 -0
- package/dist/spec/csv-schema/mep/conduit.yaml +8 -0
- package/dist/spec/csv-schema/mep/duct.yaml +8 -0
- package/dist/spec/csv-schema/mep/equipment.yaml +22 -0
- package/dist/spec/csv-schema/mep/mep_node.yaml +6 -0
- package/dist/spec/csv-schema/mep/pipe.yaml +8 -0
- package/dist/spec/csv-schema/mep/terminal.yaml +19 -0
- package/dist/spec/csv-schema/mesh.yaml +40 -0
- package/dist/spec/csv-schema/structure/beam.yaml +7 -0
- package/dist/spec/csv-schema/structure/brace.yaml +7 -0
- package/dist/spec/csv-schema/structure/foundation.yaml +22 -0
- package/dist/spec/csv-schema/structure/structure_column.yaml +8 -0
- package/dist/spec/csv-schema/structure/structure_slab.yaml +14 -0
- package/dist/spec/csv-schema/structure/structure_wall.yaml +9 -0
- package/dist/spec/duckdb-strategy.md +93 -0
- package/dist/spec/llm-classification.md +453 -0
- package/dist/spec/migration-guide.md +248 -0
- package/dist/spec/project_metadata.schema.yaml +21 -0
- package/dist/spec/readme.md +247 -0
- package/dist/spec/svg-schema/readme.md +165 -0
- package/package.json +1 -1
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
# BimDown Spec Migration Guide
|
|
2
|
+
|
|
3
|
+
This document records all spec changes across versions to guide editor and CLI adaptation.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Version 3.0 (Current)
|
|
8
|
+
|
|
9
|
+
### SVG Format: `<line>` → `<path>`
|
|
10
|
+
|
|
11
|
+
**All line-type elements** now use `<path>` instead of `<line>` in SVG.
|
|
12
|
+
|
|
13
|
+
Before:
|
|
14
|
+
```xml
|
|
15
|
+
<line id="w-1" x1="0" y1="0" x2="5" y2="0" stroke="black" stroke-width="0.2" stroke-linecap="square" />
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
After:
|
|
19
|
+
```xml
|
|
20
|
+
<path id="w-1" d="M 0,0 L 5,0" />
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
- Only `M`, `L`, `A` commands allowed (no bezier `C`/`Q`)
|
|
24
|
+
- `A` command supports arc geometry (curved walls, ramps)
|
|
25
|
+
- Affects: wall, structure_wall, beam, brace, stair, ramp, railing, curtain_wall, room_separator, duct, pipe, cable_tray, conduit, strip foundations
|
|
26
|
+
|
|
27
|
+
**Editor action**: SVG parser must handle `<path d="M x1,y1 L x2,y2">` instead of `<line x1=... y1=...>`. Parse the `d` attribute to extract start/end coordinates.
|
|
28
|
+
|
|
29
|
+
### SVG Styling Removed
|
|
30
|
+
|
|
31
|
+
No `stroke`, `fill`, `stroke-width`, `stroke-linecap` attributes are written or read. SVG elements only have `id` and geometry attributes (`d`, `x`, `y`, `width`, `height`, `cx`, `cy`, `r`, `points`, `transform`).
|
|
32
|
+
|
|
33
|
+
**Editor action**: Don't rely on `stroke-width` for wall thickness or any styling attributes for data. Thickness comes from CSV only.
|
|
34
|
+
|
|
35
|
+
### Door/Window Removed from SVG
|
|
36
|
+
|
|
37
|
+
Doors and windows **no longer have SVG files**. They are fully defined in CSV via `host_id` + `position` (0-1 parametric location on host wall).
|
|
38
|
+
|
|
39
|
+
Before: `door.svg` existed with `<line data-host="w-1" ...>` elements.
|
|
40
|
+
After: Only `door.csv` exists. No `door.svg`, no `window.svg`.
|
|
41
|
+
|
|
42
|
+
**Editor action**: Render doors/windows by computing position on host wall from CSV `position` field. Remove any SVG-based door/window loading.
|
|
43
|
+
|
|
44
|
+
### Space Removed from SVG
|
|
45
|
+
|
|
46
|
+
Spaces (rooms) **no longer have SVG files**. Defined by seed point `(x, y)` in CSV. Boundary auto-derived from surrounding walls and room separators.
|
|
47
|
+
|
|
48
|
+
Before: `space.svg` existed with `<polygon>` elements.
|
|
49
|
+
After: Only `space.csv` exists with `x`, `y`, `name` fields.
|
|
50
|
+
|
|
51
|
+
**Editor action**: Render space boundaries by computing enclosed regions from wall geometry, not from SVG polygons.
|
|
52
|
+
|
|
53
|
+
### Foundation Unified (3 → 1)
|
|
54
|
+
|
|
55
|
+
`isolated_foundation`, `strip_foundation`, `raft_foundation` merged into single `foundation` table.
|
|
56
|
+
|
|
57
|
+
Before:
|
|
58
|
+
```
|
|
59
|
+
isolated_foundation.csv + isolated_foundation.svg (point: <rect>/<circle>)
|
|
60
|
+
strip_foundation.csv + strip_foundation.svg (line: <line>)
|
|
61
|
+
raft_foundation.csv + raft_foundation.svg (polygon: <polygon>)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
After:
|
|
65
|
+
```
|
|
66
|
+
foundation.csv + foundation.svg (mixed: <rect>/<circle>, <path>, or <polygon>)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The geometry type in SVG determines the foundation form. CSV fields are a superset: `thickness`, `width`, `length`, `material`. Unused fields are empty.
|
|
70
|
+
|
|
71
|
+
ID prefix changed: `if-1`/`sf-1`/`rf-1` → `f-1`
|
|
72
|
+
|
|
73
|
+
**Editor action**: Load single `foundation` table. Detect geometry type from SVG element (`<rect>` = isolated, `<path>` = strip, `<polygon>` = raft). Handle all three geometry types in one table renderer.
|
|
74
|
+
|
|
75
|
+
### New Element Types
|
|
76
|
+
|
|
77
|
+
#### `ramp` (architecture)
|
|
78
|
+
- Base: `spatial_line_element`
|
|
79
|
+
- Fields: `width`
|
|
80
|
+
- SVG: `<path>`
|
|
81
|
+
- ID prefix: `rp`
|
|
82
|
+
- Similar to `stair` but without `step_count`
|
|
83
|
+
|
|
84
|
+
#### `railing` (architecture)
|
|
85
|
+
- Base: `spatial_line_element`
|
|
86
|
+
- Fields: `height`
|
|
87
|
+
- SVG: `<path>`
|
|
88
|
+
- ID prefix: `rl`
|
|
89
|
+
- Previously exported as `mesh` (GLB fallback); now has parametric schema
|
|
90
|
+
|
|
91
|
+
#### `room_separator` (architecture)
|
|
92
|
+
- Base: `line_element`
|
|
93
|
+
- Fields: none (pure geometry)
|
|
94
|
+
- SVG: `<path>`
|
|
95
|
+
- ID prefix: `rs`
|
|
96
|
+
- Invisible boundary line for defining room boundaries where no wall exists
|
|
97
|
+
- Was defined in spec v2 but never had export/import implementation; now fully implemented
|
|
98
|
+
|
|
99
|
+
**Editor action**: Add table loaders, renderers, and property panels for these three new element types.
|
|
100
|
+
|
|
101
|
+
### Opening Dual Mode
|
|
102
|
+
|
|
103
|
+
`opening` now supports two modes in the same table:
|
|
104
|
+
|
|
105
|
+
1. **Wall opening**: `host_id` references a wall. Has `position`, `width`, `height`, `shape`. No SVG.
|
|
106
|
+
2. **Slab opening**: `host_id` references a slab. Has SVG geometry (`<rect>` or `<polygon>`).
|
|
107
|
+
|
|
108
|
+
Opening no longer extends `hosted_element` base. It extends `element` directly with its own `host_id` and `position` fields.
|
|
109
|
+
|
|
110
|
+
For shaft openings spanning multiple floors: one `opening` per level, each hosted on its slab.
|
|
111
|
+
|
|
112
|
+
**Editor action**: Check `host_id` target type. If host is wall → render as parametric opening on wall. If host is slab → render from SVG geometry.
|
|
113
|
+
|
|
114
|
+
### MEP System Type: Enum → String
|
|
115
|
+
|
|
116
|
+
`mep_system.system_type` changed from enum (`hvac`, `plumbing`, etc.) to free-form string matching Revit's system classification (e.g. `"CHWS"`, `"CHR"`, `"SA"`, `"RA"`, `"DW"`).
|
|
117
|
+
|
|
118
|
+
**Editor action**: Display system_type as text, not dropdown. Remove enum validation for this field.
|
|
119
|
+
|
|
120
|
+
### MEP Topology Model
|
|
121
|
+
|
|
122
|
+
MEP networks are a **bipartite graph**: curves connect to nodes, nodes connect to curves. Two curves never connect directly.
|
|
123
|
+
|
|
124
|
+
- `mep_curve` (duct/pipe/cable_tray/conduit) endpoints come from **connector positions** (not centerline). This ensures endpoints coincide with fitting/accessory positions.
|
|
125
|
+
- `mep_node` represents fittings and accessories. Minimal data: just position and system_type.
|
|
126
|
+
- `equipment` and `terminal` also serve as network endpoints.
|
|
127
|
+
- `start_node_id` / `end_node_id` on curves reference the connected node/equipment/terminal.
|
|
128
|
+
|
|
129
|
+
AI authoring: draw curves → call CLI `validate`/`resolve-topology` → auto-generates nodes and fills connectivity.
|
|
130
|
+
|
|
131
|
+
Revit export: fittings/accessories exported as `mep_node`. Curve endpoints taken from `Connector.Origin` (not `LocationCurve`), naturally coinciding with node positions.
|
|
132
|
+
|
|
133
|
+
**Editor action**: Render MEP network as graph. Curve endpoints should visually connect to node positions. Support resolve-topology validation.
|
|
134
|
+
|
|
135
|
+
### Mesh Category: Enum → String
|
|
136
|
+
|
|
137
|
+
`mesh.category` changed from enum (`railing`, `generic_model`, etc.) to free-form string containing Revit's category name.
|
|
138
|
+
|
|
139
|
+
ID prefix changed: `mesh-1` → `ms-1`
|
|
140
|
+
|
|
141
|
+
**Editor action**: Display category as text. Remove enum validation.
|
|
142
|
+
|
|
143
|
+
### Project Metadata
|
|
144
|
+
|
|
145
|
+
New file `project_metadata.json` at project root:
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
{
|
|
149
|
+
"format_version": "3.0",
|
|
150
|
+
"project_name": "My Project",
|
|
151
|
+
"units": "meters",
|
|
152
|
+
"source": "Revit 2026"
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Schema defined in `spec/project_metadata.schema.yaml`.
|
|
157
|
+
|
|
158
|
+
**Editor action**: Read `format_version` to detect spec version. Display project name. Validate format compatibility.
|
|
159
|
+
|
|
160
|
+
### Partitioning Rules Clarified
|
|
161
|
+
|
|
162
|
+
Elements are partitioned into level directories vs `global/`:
|
|
163
|
+
|
|
164
|
+
- **Level directory**: Elements whose `top_level_id` is at most one level above their base level (normal single-story elements)
|
|
165
|
+
- **Global directory**: Elements whose `top_level_id` is **more than one level above** their base (true multi-story elements), plus elements without `level_id`, plus `level.csv` and `grid.csv`
|
|
166
|
+
|
|
167
|
+
Before: any element without level_id went to global. Now: the rule is based on level index gap.
|
|
168
|
+
|
|
169
|
+
**Editor action**: When loading a project, read both level directories and `global/` directory. Merge global elements into the appropriate level views.
|
|
170
|
+
|
|
171
|
+
### Directory Typo Fixed
|
|
172
|
+
|
|
173
|
+
`spec/csv-schema/architechture/` → `spec/csv-schema/architecture/`
|
|
174
|
+
|
|
175
|
+
**Editor action**: Update any hardcoded paths referencing the old directory name.
|
|
176
|
+
|
|
177
|
+
### New ID Prefixes
|
|
178
|
+
|
|
179
|
+
| Element | Old Prefix | New Prefix |
|
|
180
|
+
|---------|-----------|------------|
|
|
181
|
+
| foundation | `if`/`sf`/`rf` | `f` |
|
|
182
|
+
| mesh | `mesh` | `ms` |
|
|
183
|
+
| ramp | (new) | `rp` |
|
|
184
|
+
| railing | (new) | `rl` |
|
|
185
|
+
| room_separator | (new) | `rs` |
|
|
186
|
+
| curtain_wall | (new) | `cw` |
|
|
187
|
+
| mep_node | (new) | `mn` |
|
|
188
|
+
|
|
189
|
+
### LLM Classification (New Feature — Design Only)
|
|
190
|
+
|
|
191
|
+
A planned feature for LLM-based classification of Revit family parameters and material names. See `spec/llm-classification.md` for the design document. Not yet implemented — no editor action needed yet.
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Version 2.0 (Previous — commit `f1c93ef`)
|
|
196
|
+
|
|
197
|
+
These changes were made before v3.0 and should already be implemented in the editor.
|
|
198
|
+
|
|
199
|
+
### Hosted Elements Become CSV-Only
|
|
200
|
+
|
|
201
|
+
Doors and windows changed from SVG-rendered elements to CSV-only with parametric position:
|
|
202
|
+
- `position`: 0.0–1.0 normalized parameter along host wall (center of opening)
|
|
203
|
+
- `host_id`: reference to host wall element
|
|
204
|
+
|
|
205
|
+
SVG representation was `<line data-host="w-1">` with white stroke to show openings. This was replaced with pure CSV data.
|
|
206
|
+
|
|
207
|
+
### Space Changed to Seed Point
|
|
208
|
+
|
|
209
|
+
Space (room) changed from polygon (`<polygon>` in SVG) to seed point:
|
|
210
|
+
- CSV fields: `x`, `y` (interior point), `name`
|
|
211
|
+
- Boundary auto-derived from walls and room separators
|
|
212
|
+
|
|
213
|
+
### Wall Thickness Source of Truth
|
|
214
|
+
|
|
215
|
+
`wall.thickness` is `required: true` in CSV (source of truth). SVG `stroke-width` may visually represent thickness but CSV overrides on conflict. CLI auto-heals SVG to match CSV.
|
|
216
|
+
|
|
217
|
+
### Material Enum
|
|
218
|
+
|
|
219
|
+
`materialized.material` changed from free-text string to fixed enum: `concrete`, `steel`, `wood`, `clt`, `glass`, `aluminum`, `brick`, `stone`, `gypsum`, `insulation`, `copper`, `pvc`, `ceramic`, `fiber_cement`, `composite`.
|
|
220
|
+
|
|
221
|
+
### Room Separator Added
|
|
222
|
+
|
|
223
|
+
New element `room_separator` (line_element, no extra fields). Used to define room boundaries where no physical wall exists. Was spec-only in v2; fully implemented in v3.
|
|
224
|
+
|
|
225
|
+
### Roof, Ceiling, Opening Added (v2.5 — commit `2c58336`)
|
|
226
|
+
|
|
227
|
+
- `roof`: polygon_element + materialized, fields: `roof_type` (enum), `slope`, `thickness`
|
|
228
|
+
- `ceiling`: polygon_element + materialized, fields: `height_offset`
|
|
229
|
+
- `opening`: hosted_element on wall, fields: `width`, `height`, `shape`
|
|
230
|
+
- `mesh`: fallback for elements without parametric schema, fields: `category` (was enum), `mesh_file` (GLB path), position/rotation
|
|
231
|
+
|
|
232
|
+
### Defaults
|
|
233
|
+
|
|
234
|
+
- `base_offset` defaults to 0
|
|
235
|
+
- `top_level_id` empty means next level above current level
|
|
236
|
+
- IDs are level-scoped (unique within each level directory)
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
## Version 1.0 (Original)
|
|
241
|
+
|
|
242
|
+
Original spec with:
|
|
243
|
+
- SVG `<line>` for line elements, `<rect>`/`<circle>` for points, `<polygon>` for polygons
|
|
244
|
+
- All elements had SVG representation (including doors, windows, spaces)
|
|
245
|
+
- Separate foundation types (isolated, strip, raft)
|
|
246
|
+
- Free-text material field
|
|
247
|
+
- No room_separator, roof, ceiling, opening, mesh
|
|
248
|
+
- No project metadata
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
name: project_metadata
|
|
2
|
+
description: Schema for project_metadata.json at the project root.
|
|
3
|
+
|
|
4
|
+
fields:
|
|
5
|
+
- name: format_version
|
|
6
|
+
type: string
|
|
7
|
+
required: true
|
|
8
|
+
description: BimDown format version (e.g. "1.0")
|
|
9
|
+
|
|
10
|
+
- name: project_name
|
|
11
|
+
type: string
|
|
12
|
+
description: Human-readable project name
|
|
13
|
+
|
|
14
|
+
- name: units
|
|
15
|
+
type: string
|
|
16
|
+
description: Coordinate unit system (always "meters")
|
|
17
|
+
default: meters
|
|
18
|
+
|
|
19
|
+
- name: source
|
|
20
|
+
type: string
|
|
21
|
+
description: Export source (e.g. "Revit 2026", "BimDown CLI")
|
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# BimDown Spec
|
|
2
|
+
|
|
3
|
+
This directory defines the **BimDown data format** — a "Minimum Viable Building" representation optimized for AI-native building design and bidirectional sync with BIM tools (Revit).
|
|
4
|
+
|
|
5
|
+
BimDown uses **CSV for attributes** and **SVG for 2D geometry**, both human-readable and AI-friendly. A CLI tool with DuckDB provides relational query and auto-sync capabilities.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Project Structure
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
{project-id}/
|
|
13
|
+
├── project_metadata.json # Format version, project name, units, source
|
|
14
|
+
├── global/
|
|
15
|
+
│ ├── level.csv # Floor level definitions
|
|
16
|
+
│ ├── grid.csv # Structural grid lines
|
|
17
|
+
│ ├── wall.csv / wall.svg # Multi-story walls (span > 1 level above)
|
|
18
|
+
│ ├── stair.csv / stair.svg # Multi-story stairs
|
|
19
|
+
│ └── ... # Any element spanning > 1 level above
|
|
20
|
+
├── 1F/
|
|
21
|
+
│ ├── wall.csv / wall.svg
|
|
22
|
+
│ ├── column.csv / column.svg
|
|
23
|
+
│ ├── slab.csv / slab.svg
|
|
24
|
+
│ ├── door.csv # No SVG (hosted, parametric position)
|
|
25
|
+
│ ├── window.csv # No SVG (hosted, parametric position)
|
|
26
|
+
│ ├── space.csv # No SVG (seed point only)
|
|
27
|
+
│ └── ...
|
|
28
|
+
├── 2F/
|
|
29
|
+
│ └── ...
|
|
30
|
+
└── _IdMap.csv # UUID ↔ short ID mapping (Revit round-trip)
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Partitioning Rules (Level vs Global)
|
|
36
|
+
|
|
37
|
+
All elements belong to a **base level** (their `level_id`).
|
|
38
|
+
|
|
39
|
+
- **Level directory**: Elements whose vertical extent stays within one level above their base (e.g. a 1F wall with `top_level_id` = 2F is normal single-story — goes in `1F/`).
|
|
40
|
+
- **Global directory**: Elements that span **more than one level above** their base (e.g. a 1F wall with `top_level_id` = 3F). Also: `level.csv`, `grid.csv`.
|
|
41
|
+
- **Elements without `vertical_span`**: Always go in their level directory.
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Schema Overview
|
|
46
|
+
|
|
47
|
+
### Global Tables
|
|
48
|
+
|
|
49
|
+
| Table | SVG | Description |
|
|
50
|
+
|---------|-----|-------------|
|
|
51
|
+
| `level` | No | Floor levels by elevation |
|
|
52
|
+
| `grid` | No | Structural/reference grid lines |
|
|
53
|
+
|
|
54
|
+
### Architecture
|
|
55
|
+
|
|
56
|
+
| Table | Geometry | SVG | Description |
|
|
57
|
+
|------------------|-----------------|---------|-------------|
|
|
58
|
+
| `wall` | Line | `<path>` | Architectural wall with thickness and vertical span |
|
|
59
|
+
| `column` | Point | `<rect>`/`<circle>` | Architectural column with section profile |
|
|
60
|
+
| `slab` | Polygon | `<polygon>` | Floor/roof/finish slab |
|
|
61
|
+
| `space` | Seed point | No | Named space/room (boundary derived from walls + room_separator) |
|
|
62
|
+
| `door` | Hosted on wall | No | Door with operation type |
|
|
63
|
+
| `window` | Hosted on wall | No | Window with dimensions |
|
|
64
|
+
| `opening` | Hosted | Conditional | Wall opening (no SVG) or slab opening (`<rect>`/`<polygon>`) |
|
|
65
|
+
| `stair` | Spatial line | `<path>` | Stair run with vertical span |
|
|
66
|
+
| `ramp` | Spatial line | `<path>` | Accessibility ramp |
|
|
67
|
+
| `railing` | Spatial line | `<path>` | Railing along path |
|
|
68
|
+
| `curtain_wall` | Line | `<path>` | Curtain wall with grid parameters |
|
|
69
|
+
| `ceiling` | Polygon | `<polygon>` | Ceiling surface |
|
|
70
|
+
| `roof` | Polygon | `<polygon>` | Roof surface |
|
|
71
|
+
| `room_separator` | Line | `<path>` | Invisible boundary line for room separation |
|
|
72
|
+
|
|
73
|
+
### Structure
|
|
74
|
+
|
|
75
|
+
| Table | Geometry | SVG | Description |
|
|
76
|
+
|--------------------|------------|---------|-------------|
|
|
77
|
+
| `structure_wall` | Line | `<path>` | Structural wall |
|
|
78
|
+
| `structure_column` | Point | `<rect>`/`<circle>` | Structural column |
|
|
79
|
+
| `structure_slab` | Polygon | `<polygon>` | Structural slab |
|
|
80
|
+
| `beam` | Spatial line | `<path>` | Structural beam |
|
|
81
|
+
| `brace` | Spatial line | `<path>` | Structural brace |
|
|
82
|
+
| `foundation` | Mixed | `<rect>`/`<circle>`, `<path>`, or `<polygon>` | Unified foundation (geometry determines form) |
|
|
83
|
+
|
|
84
|
+
### MEP
|
|
85
|
+
|
|
86
|
+
| Table | Geometry | SVG | Description |
|
|
87
|
+
|--------------|-------------|---------|-------------|
|
|
88
|
+
| `duct` | Spatial line | `<path>` | HVAC duct (endpoints from connectors) |
|
|
89
|
+
| `pipe` | Spatial line | `<path>` | Plumbing/process pipe (endpoints from connectors) |
|
|
90
|
+
| `cable_tray` | Spatial line | `<path>` | Electrical cable tray (endpoints from connectors) |
|
|
91
|
+
| `conduit` | Spatial line | `<path>` | Electrical conduit (endpoints from connectors) |
|
|
92
|
+
| `equipment` | Point | `<rect>`/`<circle>` | MEP equipment (AHU, chiller, pump...) |
|
|
93
|
+
| `terminal` | Point | `<rect>`/`<circle>` | MEP terminal (diffuser, outlet...) |
|
|
94
|
+
| `mep_node` | Point | `<rect>`/`<circle>` | Topology node (fitting/accessory in Revit) |
|
|
95
|
+
|
|
96
|
+
### Fallback
|
|
97
|
+
|
|
98
|
+
| Table | SVG | Description |
|
|
99
|
+
|--------|-----|-------------|
|
|
100
|
+
| `mesh` | No | Generic 3D model (GLB) for elements without parametric schema |
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Schema Field Metadata
|
|
105
|
+
|
|
106
|
+
### `required: true`
|
|
107
|
+
|
|
108
|
+
Semantic **source of truth**. Written directly in `.csv` by AI. If SVG geometry contradicts a required field, the CLI uses the CSV value to auto-correct SVG on sync.
|
|
109
|
+
|
|
110
|
+
### `computed: true`
|
|
111
|
+
|
|
112
|
+
Spatial derivatives extracted from SVG at runtime. **Not stored in CSV**. The DuckDB CLI engine hydrates these as virtual columns during queries.
|
|
113
|
+
|
|
114
|
+
**Rule**: Elements with SVG have their geometry fields as `computed`. Elements without SVG (door, window, space, grid, level) have geometry fields as `required`.
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Base Mixins
|
|
119
|
+
|
|
120
|
+
| Mixin | Key Fields |
|
|
121
|
+
|------------------------------|------------|
|
|
122
|
+
| `element` | `id` (short ID, PK), `number`, `base_offset`, `mesh_file` |
|
|
123
|
+
| `line_element` | `start_x/y`, `end_x/y`, `length` (all computed from SVG `<path>`) |
|
|
124
|
+
| `spatial_line_element` | extends `line_element` + `start_z`, `end_z` (required, CSV) |
|
|
125
|
+
| `point_element` | `x`, `y`, `rotation` (all computed from SVG) |
|
|
126
|
+
| `polygon_element` | `points`, `area` (all computed from SVG) |
|
|
127
|
+
| `hosted_element` | `host_id` (reference), `position` (0-1 along host) |
|
|
128
|
+
| `vertical_span` | `top_level_id`, `top_offset`, `height` (computed) |
|
|
129
|
+
| `materialized` | `material` (enum: concrete, steel, wood, clt, glass, aluminum, brick, stone, gypsum, insulation, copper, pvc, ceramic, fiber_cement, composite) |
|
|
130
|
+
| `section_profile` | `shape` (rect/round), `size_x`, `size_y` |
|
|
131
|
+
| `structural_section_profile` | `shape` (rect/round/i/t/l/c/cross), `size_x`, `size_y` |
|
|
132
|
+
| `mep_system` | `system_type` (string, e.g. "CHWS", "SA", "DW") |
|
|
133
|
+
| `mep_connected_segment` | `start_node_id`, `end_node_id` (auto-resolved by CLI) |
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## ID System
|
|
138
|
+
|
|
139
|
+
All elements use prefixed short IDs: `{prefix}-{n}`. Counters are 1-based per table, scoped to the level directory.
|
|
140
|
+
|
|
141
|
+
| Table | Prefix | Example |
|
|
142
|
+
|---|---|---|
|
|
143
|
+
| `level` | `lv` | `lv-1` |
|
|
144
|
+
| `grid` | `gr` | `gr-1` |
|
|
145
|
+
| `wall` | `w` | `w-1` |
|
|
146
|
+
| `column` | `c` | `c-1` |
|
|
147
|
+
| `slab` | `sl` | `sl-1` |
|
|
148
|
+
| `space` | `sp` | `sp-1` |
|
|
149
|
+
| `door` | `d` | `d-1` |
|
|
150
|
+
| `window` | `wn` | `wn-1` |
|
|
151
|
+
| `opening` | `op` | `op-1` |
|
|
152
|
+
| `stair` | `st` | `st-1` |
|
|
153
|
+
| `ramp` | `rp` | `rp-1` |
|
|
154
|
+
| `railing` | `rl` | `rl-1` |
|
|
155
|
+
| `curtain_wall` | `cw` | `cw-1` |
|
|
156
|
+
| `ceiling` | `cl` | `cl-1` |
|
|
157
|
+
| `roof` | `ro` | `ro-1` |
|
|
158
|
+
| `room_separator` | `rs` | `rs-1` |
|
|
159
|
+
| `structure_wall` | `sw` | `sw-1` |
|
|
160
|
+
| `structure_column` | `sc` | `sc-1` |
|
|
161
|
+
| `structure_slab` | `ss` | `ss-1` |
|
|
162
|
+
| `beam` | `bm` | `bm-1` |
|
|
163
|
+
| `brace` | `br` | `br-1` |
|
|
164
|
+
| `foundation` | `f` | `f-1` |
|
|
165
|
+
| `duct` | `du` | `du-1` |
|
|
166
|
+
| `pipe` | `pi` | `pi-1` |
|
|
167
|
+
| `cable_tray` | `ct` | `ct-1` |
|
|
168
|
+
| `conduit` | `co` | `co-1` |
|
|
169
|
+
| `equipment` | `eq` | `eq-1` |
|
|
170
|
+
| `terminal` | `tm` | `tm-1` |
|
|
171
|
+
| `mep_node` | `mn` | `mn-1` |
|
|
172
|
+
| `mesh` | `ms` | `ms-1` |
|
|
173
|
+
|
|
174
|
+
Round-trip fidelity with Revit is maintained via a `BimDown_Id` shared parameter stored on each Revit element, and `_IdMap.csv` at the project root.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## Design Decisions
|
|
179
|
+
|
|
180
|
+
### Architecture vs Structure Decoupling
|
|
181
|
+
|
|
182
|
+
Architectural and structural elements are fully independent. `structure_column`, `structure_wall`, `structure_slab` inherit from geometry bases directly, not from architecture types. This prevents cross-discipline field conflicts and allows independent modeling.
|
|
183
|
+
|
|
184
|
+
### Section Profiles
|
|
185
|
+
|
|
186
|
+
- Architecture columns use `section_profile` (rect/round).
|
|
187
|
+
- Structural elements use `structural_section_profile` with engineering shapes (I, T, L, C, cross).
|
|
188
|
+
|
|
189
|
+
### SVG as AI-Native Geometry Storage
|
|
190
|
+
|
|
191
|
+
SVG is **not** used for visualization — it is a geometry storage format chosen because AI models have extensive training data on SVG and strong spatial reasoning with it. The spec uses standard SVG subset (`<path>`, `<rect>`, `<circle>`, `<polygon>`) without custom attributes or styling requirements.
|
|
192
|
+
|
|
193
|
+
Line elements use `<path>` with `M`, `L`, `A` commands. This naturally supports both straight lines and arcs (curved walls, ramps) using standard SVG syntax that AI models already understand well.
|
|
194
|
+
|
|
195
|
+
### Elements Without SVG
|
|
196
|
+
|
|
197
|
+
Some elements have no SVG representation:
|
|
198
|
+
- **Door/Window**: Fully defined by `host_id` + `position` (parametric placement on wall). Absolute coordinates would require re-syncing whenever the host wall moves.
|
|
199
|
+
- **Space**: Defined by seed point `(x, y)`. Boundary is auto-derived from surrounding walls and room separators.
|
|
200
|
+
- **Grid/Level**: Global reference data with coordinates in CSV.
|
|
201
|
+
|
|
202
|
+
### Unified Foundation Type
|
|
203
|
+
|
|
204
|
+
Rather than separate types for isolated/strip/raft foundations, a single `foundation` table covers all forms. The geometry type (point/line/polygon) is determined by the SVG element. This reduces table count while the SVG naturally disambiguates the form.
|
|
205
|
+
|
|
206
|
+
### Opening: Wall and Slab Voids
|
|
207
|
+
|
|
208
|
+
`opening` supports two modes via the same table:
|
|
209
|
+
- **Wall opening**: `host_id` → wall, with `position`, `width`, `height`. No SVG.
|
|
210
|
+
- **Slab opening**: `host_id` → slab, with SVG geometry (`<rect>` or `<polygon>`).
|
|
211
|
+
|
|
212
|
+
For multi-story shaft openings: export one `opening` per level, each hosted on its respective slab.
|
|
213
|
+
|
|
214
|
+
### MEP Topology
|
|
215
|
+
|
|
216
|
+
MEP networks form a **bipartite graph**: `mep_curve` (duct, pipe, cable_tray, conduit) connects to `mep_node` (fittings, accessories), and nodes connect back to curves. Two curves never connect directly — there is always a node in between.
|
|
217
|
+
|
|
218
|
+
- **mep_curve** geometry is defined by its two connector endpoints (not the physical centerline). In SVG this is a `<path>`. In Revit, endpoints are taken from `Connector.Origin` positions, which naturally align with the connectors of adjacent fittings.
|
|
219
|
+
- **mep_node** is a minimal topology node with position only. In SVG this is a `<rect>`. In Revit it maps to fittings (`DuctFitting`, `PipeFitting`, etc.) and accessories (`DuctAccessory`, `PipeAccessory`).
|
|
220
|
+
- **equipment** and **terminal** also serve as network endpoints — curves can connect directly to them.
|
|
221
|
+
|
|
222
|
+
**AI authoring workflow**:
|
|
223
|
+
1. Place equipment and terminals (anchors)
|
|
224
|
+
2. Draw duct/pipe segments connecting them (endpoint coordinates)
|
|
225
|
+
3. Call CLI `validate` / `resolve-topology` — this detects coincident endpoints, generates `mep_node` entries at junctions, and back-fills `start_node_id`/`end_node_id` on each segment. Warns about disconnected endpoints.
|
|
226
|
+
|
|
227
|
+
**Revit export**: Fittings and accessories are exported as `mep_node`. Curve endpoints are taken from connector positions (not `LocationCurve`), so they naturally coincide with node positions. `start_node_id`/`end_node_id` are derived from Revit's connector relationships.
|
|
228
|
+
|
|
229
|
+
**Revit import**: Curves are created from endpoint coordinates. Fittings are auto-inserted at junctions where curves meet nodes.
|
|
230
|
+
|
|
231
|
+
### Material Enum
|
|
232
|
+
|
|
233
|
+
A fixed enum of 15 common structural/architectural materials. Represents the **primary material** of an element. Composite/multi-layer constructions are not modeled — the Revit plugin handles layer composition independently.
|
|
234
|
+
|
|
235
|
+
### Format Versioning
|
|
236
|
+
|
|
237
|
+
`project_metadata.json` at the project root includes `format_version` for forward compatibility.
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Storage & Query Architecture
|
|
242
|
+
|
|
243
|
+
See **[DuckDB & CLI Strategy](duckdb-strategy.md)** for details on:
|
|
244
|
+
1. **Hydration**: Merging partitioned CSVs + parsing SVG geometry into in-memory DuckDB tables.
|
|
245
|
+
2. **Execution**: Standard SQL queries over unified, geometry-enriched views.
|
|
246
|
+
3. **Sync-Out**: Stripping computed fields, auto-healing SVG from CSV source-of-truth, re-partitioning by level.
|
|
247
|
+
4. **Resolve-Topology**: Auto-generating MEP connectivity graph from endpoint coordinates.
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# BimDown SVG Spec
|
|
2
|
+
|
|
3
|
+
SVG is the **geometry storage layer** for BimDown. It is not used for visualization — it is chosen because AI models have extensive training data on SVG and strong spatial reasoning with the format.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. File Organization
|
|
8
|
+
|
|
9
|
+
SVG files are co-located with their CSV counterparts, organized by level:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
{project-id}/
|
|
13
|
+
{level}/
|
|
14
|
+
wall.svg
|
|
15
|
+
column.svg
|
|
16
|
+
slab.svg
|
|
17
|
+
...
|
|
18
|
+
global/
|
|
19
|
+
wall.svg (multi-story walls)
|
|
20
|
+
...
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Each SVG file corresponds to one element table for one directory. Multi-story elements in `global/*.csv` have their SVG in `global/*.svg`. When rendering a floor plan, the CLI composites `global/` SVG onto the active level's view.
|
|
24
|
+
|
|
25
|
+
### Elements Without SVG
|
|
26
|
+
|
|
27
|
+
The following element types have **no SVG files**:
|
|
28
|
+
- `door`, `window` — Parametric placement via `host_id` + `position` on wall
|
|
29
|
+
- `space` — Seed point `(x, y)` in CSV; boundary auto-derived from walls
|
|
30
|
+
- `opening` (wall mode) — Parametric placement via `host_id` + `position`
|
|
31
|
+
- `level`, `grid` — Global reference data with coordinates in CSV
|
|
32
|
+
- `mesh` — 3D geometry in GLB files
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 2. Coordinate System
|
|
37
|
+
|
|
38
|
+
- **Origin**: Project Cartesian origin `(0, 0)`
|
|
39
|
+
- **Units**: Meters
|
|
40
|
+
- **Y-Axis**: Architectural convention (+Y = North). When rendering, apply `<g transform="scale(1, -1)">` to flip to SVG screen coordinates.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## 3. SVG Subset
|
|
45
|
+
|
|
46
|
+
### Allowed Elements
|
|
47
|
+
|
|
48
|
+
| SVG Element | BimDown Usage |
|
|
49
|
+
|-------------|---------------|
|
|
50
|
+
| `<svg>`, `<g>` | Structure and grouping |
|
|
51
|
+
| `<path>` | Line elements (walls, beams, ducts, stairs, ramps, railings, etc.) |
|
|
52
|
+
| `<rect>` | Point elements with rectangular profile |
|
|
53
|
+
| `<circle>` | Point elements with round profile |
|
|
54
|
+
| `<polygon>` | Polygon elements (slabs, ceilings, roofs, etc.) |
|
|
55
|
+
| `<text>` | Optional labels |
|
|
56
|
+
|
|
57
|
+
### Allowed `<path>` Commands
|
|
58
|
+
|
|
59
|
+
Only the following path commands are permitted:
|
|
60
|
+
- `M` / `m` — Move to (start point)
|
|
61
|
+
- `L` / `l` — Line to (straight segment)
|
|
62
|
+
- `A` / `a` — Arc to (circular arc segment)
|
|
63
|
+
|
|
64
|
+
**Bezier curves (`C`, `Q`, `S`, `T`) are forbidden.** Arcs cover the curved geometry needed in architecture (curved walls, ramps).
|
|
65
|
+
|
|
66
|
+
### Forbidden Features
|
|
67
|
+
|
|
68
|
+
- `<defs>`, `<use>`, gradients, filters, animations
|
|
69
|
+
- Embedded scripts (`<script>`)
|
|
70
|
+
- Bezier path commands
|
|
71
|
+
|
|
72
|
+
### Styling
|
|
73
|
+
|
|
74
|
+
The spec does **not** require or read any styling attributes (`stroke`, `stroke-width`, `fill`, etc.). AI may write them freely for valid SVG, but they are ignored on import. Only geometric attributes and `id` are meaningful.
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## 4. Element Representation
|
|
79
|
+
|
|
80
|
+
Every SVG element **must** have an `id` attribute matching the CSV short ID (e.g. `w-1`, `c-3`).
|
|
81
|
+
|
|
82
|
+
### 4.1 Line Elements → `<path>`
|
|
83
|
+
|
|
84
|
+
Walls, beams, braces, ducts, pipes, stairs, ramps, railings, curtain walls, room separators, strip foundations.
|
|
85
|
+
|
|
86
|
+
```xml
|
|
87
|
+
<!-- Straight wall from (0,0) to (5,0) -->
|
|
88
|
+
<path id="w-1" d="M 0,0 L 5,0" />
|
|
89
|
+
|
|
90
|
+
<!-- Curved wall: arc from (0,0) to (5,0) -->
|
|
91
|
+
<path id="w-2" d="M 0,0 A 3,3 0 0,1 5,0" />
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
- Straight segments: `M x1,y1 L x2,y2`
|
|
95
|
+
- Arcs: `M x1,y1 A rx,ry rotation large-arc-flag sweep-flag x2,y2`
|
|
96
|
+
- One `<path>` per element (one-to-one mapping with CSV rows)
|
|
97
|
+
|
|
98
|
+
### 4.2 Point Elements → `<rect>` or `<circle>`
|
|
99
|
+
|
|
100
|
+
Columns, structure columns, equipment, terminals, mep_nodes, isolated foundations.
|
|
101
|
+
|
|
102
|
+
```xml
|
|
103
|
+
<!-- Rectangular column 0.4×0.4 at (2,2) -->
|
|
104
|
+
<rect id="c-1" x="1.8" y="1.8" width="0.4" height="0.4" />
|
|
105
|
+
|
|
106
|
+
<!-- Round column at (5,3) with radius 0.2 -->
|
|
107
|
+
<circle id="c-2" cx="5" cy="3" r="0.2" />
|
|
108
|
+
|
|
109
|
+
<!-- Rotated rectangular column -->
|
|
110
|
+
<rect id="c-3" x="1.8" y="1.8" width="0.4" height="0.6" transform="rotate(45, 2, 2.1)" />
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
- `shape = "round"` → `<circle>`, otherwise → `<rect>`
|
|
114
|
+
- Rotation via `transform="rotate(angle, center_x, center_y)"`
|
|
115
|
+
|
|
116
|
+
### 4.3 Polygon Elements → `<polygon>`
|
|
117
|
+
|
|
118
|
+
Slabs, structure slabs, ceilings, roofs, raft foundations, slab openings.
|
|
119
|
+
|
|
120
|
+
```xml
|
|
121
|
+
<!-- Floor slab -->
|
|
122
|
+
<polygon id="sl-1" points="0,0 10,0 10,8 0,8" />
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
- `points` attribute: space-separated `x,y` coordinate pairs
|
|
126
|
+
|
|
127
|
+
### 4.4 Foundation (Mixed Geometry)
|
|
128
|
+
|
|
129
|
+
A single `foundation` table uses different SVG elements depending on the form:
|
|
130
|
+
- Isolated (pad): `<rect>` or `<circle>` (point-based)
|
|
131
|
+
- Strip (continuous): `<path>` (line-based)
|
|
132
|
+
- Raft (mat): `<polygon>` (polygon-based)
|
|
133
|
+
|
|
134
|
+
```xml
|
|
135
|
+
<!-- Isolated foundation -->
|
|
136
|
+
<rect id="f-1" x="0.4" y="0.4" width="1.2" height="1.2" />
|
|
137
|
+
<!-- Strip foundation -->
|
|
138
|
+
<path id="f-2" d="M 0,0 L 10,0" />
|
|
139
|
+
<!-- Raft foundation -->
|
|
140
|
+
<polygon id="f-3" points="0,0 10,0 10,8 0,8" />
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### 4.5 Slab Opening
|
|
144
|
+
|
|
145
|
+
When `opening.host_id` references a slab, the opening has SVG geometry:
|
|
146
|
+
|
|
147
|
+
```xml
|
|
148
|
+
<!-- Rectangular slab opening -->
|
|
149
|
+
<rect id="op-1" x="3" y="3" width="2" height="1.5" />
|
|
150
|
+
<!-- Irregular slab opening -->
|
|
151
|
+
<polygon id="op-2" points="3,3 5,3 5,4.5 3,4.5" />
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## 5. Computed Field Hydration
|
|
157
|
+
|
|
158
|
+
The CLI parses SVG elements and injects computed fields into DuckDB:
|
|
159
|
+
|
|
160
|
+
| SVG Element | Computed Fields |
|
|
161
|
+
|-------------|----------------|
|
|
162
|
+
| `<path>` (line) | `start_x`, `start_y`, `end_x`, `end_y`, `length` |
|
|
163
|
+
| `<rect>` | `x`, `y`, `size_x` (width), `size_y` (height), `rotation` |
|
|
164
|
+
| `<circle>` | `x` (cx), `y` (cy), `size_x` (2r), `size_y` (2r), `shape="round"` |
|
|
165
|
+
| `<polygon>` | `points` (serialized), `area` |
|