bimdown-cli 0.3.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.
- package/README.md +24 -3
- package/dist/chunk-4SKM4RHY.js +142 -0
- package/dist/chunk-4SKM4RHY.js.map +1 -0
- package/dist/chunk-4YHVOWS4.js +255 -0
- package/dist/chunk-4YHVOWS4.js.map +1 -0
- package/dist/chunk-AYAXRYGP.js +2129 -0
- package/dist/chunk-AYAXRYGP.js.map +1 -0
- package/dist/chunk-EC5MR5ZH.js +648 -0
- package/dist/chunk-EC5MR5ZH.js.map +1 -0
- package/dist/chunk-HS3PO2LB.js +487 -0
- package/dist/chunk-HS3PO2LB.js.map +1 -0
- package/dist/chunk-IQJA3EFO.js +179 -0
- package/dist/chunk-IQJA3EFO.js.map +1 -0
- package/dist/chunk-JY6KWRDB.js +80 -0
- package/dist/chunk-JY6KWRDB.js.map +1 -0
- package/dist/chunk-KWSGJUMZ.js +2501 -0
- package/dist/chunk-KWSGJUMZ.js.map +1 -0
- package/dist/chunk-LWYIPR64.js +35 -0
- package/dist/chunk-LWYIPR64.js.map +1 -0
- package/dist/chunk-OBY3UYCO.js +44 -0
- package/dist/chunk-OBY3UYCO.js.map +1 -0
- package/dist/chunk-XC6WHJRL.js +29 -0
- package/dist/chunk-XC6WHJRL.js.map +1 -0
- package/dist/chunk-XQU52JKB.js +187 -0
- package/dist/chunk-XQU52JKB.js.map +1 -0
- package/dist/clash-load-D3LNQR6G.js +941 -0
- package/dist/clash-load-D3LNQR6G.js.map +1 -0
- package/dist/cli.js +431 -0
- package/dist/cli.js.map +1 -0
- package/dist/dehydrate-ZHAGOI7Q.js +90 -0
- package/dist/dehydrate-ZHAGOI7Q.js.map +1 -0
- package/dist/diff-T2KOK2WR.js +89 -0
- package/dist/diff-T2KOK2WR.js.map +1 -0
- package/dist/engine-2TPWJVEQ.js +12 -0
- package/dist/engine-2TPWJVEQ.js.map +1 -0
- package/dist/hydrate-V24H7IF3.js +673 -0
- package/dist/hydrate-V24H7IF3.js.map +1 -0
- package/dist/import-ifc-RCZSXDA6.js +5324 -0
- package/dist/import-ifc-RCZSXDA6.js.map +1 -0
- package/dist/info-QC7YXWNX.js +92 -0
- package/dist/info-QC7YXWNX.js.map +1 -0
- package/dist/init-VWDML3UC.js +112 -0
- package/dist/init-VWDML3UC.js.map +1 -0
- package/dist/lib.d.ts +492 -0
- package/dist/lib.js +6528 -0
- package/dist/lib.js.map +1 -0
- package/dist/mep-W4HJI363.js +25 -0
- package/dist/mep-W4HJI363.js.map +1 -0
- package/dist/merge-ESOPDSA5.js +413 -0
- package/dist/merge-ESOPDSA5.js.map +1 -0
- package/dist/publish-3TAXQCUV.js +80 -0
- package/dist/publish-3TAXQCUV.js.map +1 -0
- package/dist/render-UEWYHPN6.js +1807 -0
- package/dist/render-UEWYHPN6.js.map +1 -0
- package/dist/resolve-topology-AQ2RO3W3.js +338 -0
- package/dist/resolve-topology-AQ2RO3W3.js.map +1 -0
- package/dist/spec/csv-schema/annotation/dimension.yaml +77 -0
- package/dist/spec/csv-schema/annotation/tag.yaml +44 -0
- package/dist/spec/csv-schema/annotation/text_note.yaml +52 -0
- package/dist/spec/csv-schema/architecture/ceiling.yaml +8 -1
- package/dist/spec/csv-schema/architecture/column.yaml +5 -1
- package/dist/spec/csv-schema/architecture/curtain_wall.yaml +45 -5
- package/dist/spec/csv-schema/architecture/door.yaml +5 -0
- package/dist/spec/csv-schema/architecture/furniture.yaml +28 -0
- package/dist/spec/csv-schema/architecture/opening.yaml +27 -6
- package/dist/spec/csv-schema/architecture/railing.yaml +35 -0
- package/dist/spec/csv-schema/architecture/roof.yaml +34 -1
- package/dist/spec/csv-schema/architecture/slab.yaml +19 -0
- package/dist/spec/csv-schema/architecture/space.yaml +11 -1
- package/dist/spec/csv-schema/architecture/stair.yaml +49 -0
- package/dist/spec/csv-schema/architecture/stair_landing.yaml +36 -0
- package/dist/spec/csv-schema/architecture/stair_run.yaml +31 -0
- package/dist/spec/csv-schema/architecture/wall.yaml +14 -1
- package/dist/spec/csv-schema/architecture/window.yaml +19 -0
- package/dist/spec/csv-schema/base/element.yaml +20 -11
- package/dist/spec/csv-schema/base/furniture_params.yaml +60 -0
- package/dist/spec/csv-schema/base/hosted_element.yaml +10 -2
- package/dist/spec/csv-schema/base/mep_connectable.yaml +23 -0
- package/dist/spec/csv-schema/base/mep_design.yaml +24 -0
- package/dist/spec/csv-schema/base/mep_insulated.yaml +9 -0
- package/dist/spec/csv-schema/base/mep_system_tag.yaml +12 -0
- package/dist/spec/csv-schema/base/point_element.yaml +1 -0
- package/dist/spec/csv-schema/base/section_profile.yaml +5 -0
- package/dist/spec/csv-schema/base/spatial_line_element.yaml +4 -2
- package/dist/spec/csv-schema/base/structural_section_profile.yaml +50 -0
- package/dist/spec/csv-schema/base/vertical_span.yaml +9 -3
- package/dist/spec/csv-schema/base/wall_bounded.yaml +21 -0
- package/dist/spec/csv-schema/grid.yaml +5 -0
- package/dist/spec/csv-schema/mep/cable_tray.yaml +10 -3
- package/dist/spec/csv-schema/mep/circuit.yaml +70 -0
- package/dist/spec/csv-schema/mep/conduit.yaml +2 -2
- package/dist/spec/csv-schema/mep/connector.yaml +112 -0
- package/dist/spec/csv-schema/mep/duct.yaml +10 -3
- package/dist/spec/csv-schema/mep/equipment.yaml +18 -1
- package/dist/spec/csv-schema/mep/mep_node.yaml +91 -2
- package/dist/spec/csv-schema/mep/mep_system.yaml +21 -0
- package/dist/spec/csv-schema/mep/pipe.yaml +27 -3
- package/dist/spec/csv-schema/mep/terminal.yaml +22 -1
- package/dist/spec/csv-schema/model_group.yaml +40 -0
- package/dist/spec/csv-schema/sheet/sheet.yaml +50 -0
- package/dist/spec/csv-schema/sheet/sheet_viewport.yaml +86 -0
- package/dist/spec/csv-schema/structure/beam.yaml +29 -1
- package/dist/spec/csv-schema/structure/beam_system.yaml +29 -0
- package/dist/spec/csv-schema/structure/brace.yaml +24 -1
- package/dist/spec/csv-schema/structure/foundation.yaml +40 -7
- package/dist/spec/csv-schema/structure/structure_column.yaml +19 -1
- package/dist/spec/csv-schema/structure/structure_slab.yaml +32 -0
- package/dist/spec/csv-schema/structure/structure_wall.yaml +22 -0
- package/dist/spec/csv-schema/types/beam_type.yaml +11 -0
- package/dist/spec/csv-schema/types/ceiling_type.yaml +6 -0
- package/dist/spec/csv-schema/types/column_type.yaml +12 -0
- package/dist/spec/csv-schema/types/curtain_wall_type.yaml +32 -0
- package/dist/spec/csv-schema/types/door_type.yaml +27 -0
- package/dist/spec/csv-schema/types/element_type.yaml +21 -0
- package/dist/spec/csv-schema/types/fenestration.yaml +16 -0
- package/dist/spec/csv-schema/types/foundation_type.yaml +36 -0
- package/dist/spec/csv-schema/types/furniture_type.yaml +11 -0
- package/dist/spec/csv-schema/types/layered_type.yaml +13 -0
- package/dist/spec/csv-schema/types/railing_type.yaml +40 -0
- package/dist/spec/csv-schema/types/roof_type.yaml +7 -0
- package/dist/spec/csv-schema/types/slab_type.yaml +9 -0
- package/dist/spec/csv-schema/types/type_layer.yaml +47 -0
- package/dist/spec/csv-schema/types/wall_type.yaml +6 -0
- package/dist/spec/csv-schema/types/window_type.yaml +31 -0
- package/dist/spec/csv-schema/underlay.yaml +73 -0
- package/dist/spec/csv-schema/view.yaml +36 -0
- package/dist/spec/duckdb-strategy.md +4 -3
- package/dist/spec/geojson-schema/readme.md +380 -0
- package/dist/spec/mep-port-conventions.md +190 -0
- package/dist/spec/migration-guide.md +1 -1
- package/dist/spec/project_metadata.schema.yaml +52 -4
- package/dist/spec/readme.md +356 -97
- package/dist/spec/starter-types/global/beam_type.csv +5 -0
- package/dist/spec/starter-types/global/ceiling_type.csv +3 -0
- package/dist/spec/starter-types/global/column_type.csv +5 -0
- package/dist/spec/starter-types/global/curtain_wall_type.csv +2 -0
- package/dist/spec/starter-types/global/door_type.csv +6 -0
- package/dist/spec/starter-types/global/foundation_type.csv +7 -0
- package/dist/spec/starter-types/global/furniture_type.csv +11 -0
- package/dist/spec/starter-types/global/railing_type.csv +5 -0
- package/dist/spec/starter-types/global/roof_type.csv +3 -0
- package/dist/spec/starter-types/global/slab_type.csv +4 -0
- package/dist/spec/starter-types/global/type_layer.csv +40 -0
- package/dist/spec/starter-types/global/wall_type.csv +8 -0
- package/dist/spec/starter-types/global/window_type.csv +6 -0
- package/dist/spec/svg-schema/readme.md +47 -1
- package/package.json +17 -5
- package/dist/index.js +0 -3366
- package/dist/index.js.map +0 -1
- package/dist/spec/csv-schema/base/mep_connected_segment.yaml +0 -17
- 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 `
|
|
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.
|
|
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
|
+
```
|