---
name: bimdown
version: 2.2.0
description: Read, create and edit BIM models in the BimDown format (CSV attributes + GeoJSON geometry, one folder per level) with the `bimdown` CLI β architecture, structure, foundations and MEP. Use when asked to build a building model from drawings or a brief, to query or check an existing BimDown project, or when a task mentions BimDown / bim.jouledown.com.
metadata:
{
"openclaw": {
"emoji": "ποΈ",
"requires": {
"bins": ["bimdown"],
"install": { "npm": "bimdown-cli" }
},
"optionalEnv": ["BIMDOWN_API"],
"network": {
"publish": {
"endpoint": "https://bim.jouledown.com/api/shares/publish",
"method": "POST",
"description": "Optional sharing step. Uploads project CSV/GeoJSON/GLB files as a zip to bim.jouledown.com and returns a public share URL. Anonymous (no account or token required). The agent MUST ask the user for explicit permission before the first publish of any given project.",
"override": "Set BIMDOWN_API to point at a different backend (self-hosted)."
}
}
}
}
---
# BimDown
BimDown is a plain-text BIM format: **CSV for attributes, GeoJSON for geometry**, one directory per level. You create a model by writing files (usually from a script), then validate and inspect it with the `bimdown` CLI.
## Setup
`bimdown --version` must work. If it is missing, ask the user before running `npm install -g bimdown-cli`.
## 1. Project layout
```
project/
project_metadata.json { "format_version": 2, "units": "m" }
global/
level.csv id,number,name,elevation β Z source of truth
grid.csv id,number,start_x,start_y,end_x,end_y
.csv/.geojson elements spanning more than one level (multi-storey walls, risers)
lv-B1/ one directory per level; the directory name IS the level id
wall.csv + wall.geojson
door.csv hosted: CSV only
foundation.csv + foundation.geojson
...
lv-1/
beam.csv + beam.geojson
structure_slab.csv + structure_slab.geojson
```
- `project_metadata.json` takes only the known keys (`format_version`, `units`, β¦); unknown keys such as `name` fail `build`.
- Start with `bimdown init --units ` (default `m`), then edit `global/level.csv` (elevations are absolute, basements negative) and `global/grid.csv`.
- An element's base level is **always the directory it is in**. Put it in the level it starts from; only elements spanning more than one level go to `global/`.
- **Units**: use the units `project_metadata.json` declares (`m`, `ft`, `in`, `mm`; new project: the user's units, else `m`). Every number in every file is in that unit β never convert a project's declared units.
- **IDs**: `{prefix}-{n}` with digits (`w-12`, `sc-3`, `f-40`); `lv-*` / `gr-*` may use any suffix. IDs are unique per table **per level**. The CSV row and its GeoJSON Feature share the id (`properties.id`).
- Coordinates: project-local, `+X` east, `+Y` north, `+Z` up. No `crs`, no Y flip.
## 2. Vertical conventions (read this before writing any Z)
Most elements are **level-anchored**: their geometry is 2D and their height comes from the level elevation plus offsets. Framing and MEP are **spatial**: their geometry carries absolute Z.
| Table | Geometry | Bottom | Top |
|---|---|---|---|
| `wall`, `structure_wall`, `curtain_wall` | 2D LineString (centre line) | level + `base_offset` | `top_level_id` elevation + `top_offset` (default: next level up) |
| `column`, `structure_column` | 2D Point (centre) | level + `base_offset` | `top_level_id` elevation + `top_offset` |
| `slab`, `structure_slab` | 2D Polygon | top β `thickness` | **level + `base_offset` = TOP face** |
| `foundation` (raft, pad, pile cap, strip) | 2D Polygon / Point / LineString | top β `thickness` | **level + `base_offset` = TOP face** |
| `roof` | 2D Polygon | level + `base_offset` | (sits on top of the walls below) |
| `ceiling` | 2D Polygon | level + `height_offset` | β |
| `beam`, `brace` | **3D** LineString `[x, y, z]` | z β `size_y` | **z = TOP of the member** |
| `stair`, `ramp`, `railing` | 3D LineString | z of the walking surface (start = bottom of run) | |
| duct, pipe, cable_tray, conduit | 3D LineString | | z = **centre line** |
| `door`, `window`, `opening` | none (hosted) | **level** + `base_offset` (sill height above the level, not above the wall base) | + `height` |
So a 180 mm slab whose top is at 4.100 on level `lv-2` (elevation 4.2) is `base_offset: -0.1, thickness: 0.18` (relative to the level); a 300Γ700 beam whose top is flush with that slab has z = 4.1 (absolute) and `size_y: 0.7`.
- **Offsets are relative to a level; spatial z is absolute.** `base_offset` / `top_offset` are added to a level elevation. The z in a beam/duct/ramp coordinate is the absolute elevation β the same number whatever level directory the element is in (a beam at elevation 3.95 in `lv-2` whose elevation is 4.2 has z = 3.95, not β0.25).
- `top_level_id` may be the element's own level with a negative `top_offset` (e.g. a pit wall in `lv-B1` from β5.9 to β4.9 is `base_offset: -1.5, top_level_id: lv-B1, top_offset: -0.5`). Use whichever reads more clearly.
`bimdown query` reports the resulting extents in `bbox_min_z` / `bbox_max_z` for every element β use it to check your elevations (see Β§6).
## 3. Where each field lives
| Field | Lives in |
|---|---|
| `id` | both (CSV row β `properties.id`) |
| `base_offset`, `top_offset`, `arc`, `rotation`, `height_offset` | GeoJSON `properties` β **except hosted elements** (door / window / opening), which have no GeoJSON, so their `base_offset` is a CSV column |
| `base_level_id`, `top_level_id`, `host_id`, `position`, `thickness`, `size_x`, `size_y`, `shape`, `material`, `number`, enums | CSV |
| `length`, `area`, `net_area`, `height`, `x`, `y`, `start_*`, `end_*`, `points`, `volume`, `bbox_*`, `level_id` | **computed β never write them** (room `area` = centre lines, `net_area` = wall faces, the size to quote) |
Run `bimdown schema ` for the exact columns of any table. Use `number` for the element mark / type label you want to keep (e.g. `KL3(2) 300x700`, `FMη²1022`, `CT2`).
## 4. Geometry forms
```jsonc
// wall / structure_wall: centre line, exactly 2 points
{ "type": "Feature", "properties": { "id": "w-1" },
"geometry": { "type": "LineString", "coordinates": [[0, 0], [8.4, 0]] } }
// curved wall: the 2 end points + arc (or write a tessellated polyline; build converts it)
{ "type": "Feature", "properties": { "id": "w-2", "arc": { "radius": 11.47, "large_arc": false, "sweep": true } },
"geometry": { "type": "LineString", "coordinates": [[60, 10], [66, 20]] } }
// column: centre point; section in CSV (shape, size_x, size_y); rotation in degrees CCW in properties
{ "type": "Feature", "properties": { "id": "sc-1", "top_offset": -0.1 },
"geometry": { "type": "Point", "coordinates": [8.4, 6.0] } }
// slab with a shaft opening: outer ring + hole rings
{ "type": "Feature", "properties": { "id": "ss-1", "base_offset": -0.1 },
"geometry": { "type": "Polygon", "coordinates": [
[[0, 0], [16.8, 0], [16.8, 12], [0, 12], [0, 0]],
[[3, 3], [5, 3], [5, 6], [3, 6], [3, 3]] ] } }
// beam: 3D line at the top of the beam
{ "type": "Feature", "properties": { "id": "bm-1" },
"geometry": { "type": "LineString", "coordinates": [[0, 6, -0.1], [8.4, 6, -0.1]] } }
// pile cap / pad footing: give the real footprint as a Polygon (unambiguous size and orientation)
{ "type": "Feature", "properties": { "id": "f-7", "base_offset": -0.6 },
"geometry": { "type": "Polygon", "coordinates": [[[7.0, 4.6], [9.8, 4.6], [9.8, 7.4], [7.0, 7.4], [7.0, 4.6]]] } }
```
- **No Multi\* geometries.** A slab cut into disconnected pieces becomes separate Features with their own ids.
- **No boolean operations.** Elements may overlap (caps inside a raft, beams inside a slab, columns through beams) β that is normal and expected; do not carve one element out of another unless the drawing shows a real gap (e.g. a pour strip between two raft pieces, a shaft hole).
- `build` also accepts and normalises: tessellated arcs, columns written as 4-vertex polygons, unclosed rings, 3D coordinates on level-anchored elements with a constant Z.
## 5. Choosing tables
| You are modelling | Use |
|---|---|
| Partition / masonry / finish walls | `wall` |
| Concrete shear walls, retaining walls, core walls, pit walls | `structure_wall` (material concrete) |
| Architectural column casing | `column` |
| Structural columns | `structure_column` |
| Floor / roof slabs that are structure | `structure_slab` (`function`: floor / roof) |
| Finish floors, non-structural slabs | `slab` |
| Beams, girders | `beam` (`shape`, `size_x` = width, `size_y` = depth) |
| Raft / mat, slab-on-grade foundation, pile caps, pads, strip footings | `foundation` (Polygon for raft, caps and pads; LineString + `width` for strips) |
| Thickened raft zones / different raft levels | separate `foundation` polygons, each with its own `base_offset` and `thickness` |
| Sumps, lift pits | `foundation` polygon for the pit floor (its top = pit bottom) + `structure_wall` for the pit walls (negative `base_offset` / `top_offset`) |
| Pour strips / construction joints in a raft | their own `foundation` polygons, named in `number` |
| Piles | `foundation` Point or a small polygon per pile, or skip if not required |
| Car ramps | `ramp` (3D LineString + `width`) or sloped `structure_slab` pieces |
| Openings in walls | `door`, `window`, `opening` (hosted) |
| Shafts / holes in slabs | polygon holes in the slab |
| Room-closing lines without a wall | `room_separator` |
| Anything without a table | `mesh` (GLB) or the closest table + a clear `number` |
## 6. Workflow
1. **Read the brief or drawings first** and collect the numbers (grid, levels, sizes, elevations) before writing files.
2. **Generate the model from a script** (Python or Node) that holds the data and writes every CSV/GeoJSON. Re-running the script is how you fix things; hand-editing hundreds of rows is error-prone.
3. `bimdown build ` after every generation. It validates the schema, snaps endpoints within 5 cm, normalises geometry and computes room boundaries. **Errors must be fixed; warnings are advice** (see below).
4. `bimdown render -l -o /tmp/lv.png` and look at the image. Write renders **outside** the project directory. Render is a plan view of one level.
5. **Check Z with a query**, because the render is 2D:
```bash
bimdown query "SELECT id, number, round(bbox_min_z,3) lo, round(bbox_max_z,3) hi FROM structure_slab ORDER BY hi"
bimdown query "SELECT number, count(*) n FROM beam GROUP BY number"
bimdown info
```
SQL tips: `window`, `column` (and other SQL keywords) must be quoted: `SELECT * FROM "window"`. Computed fields (`length`, `area`, `net_area`, `height`, `bbox_*`) are available in queries (`net_area` after `build`).
6. Iterate until counts, plans and elevations are right.
**About build warnings**: "has no connected line element" means a wall end touches nothing β no other wall end, no other wall's body (a T-junction at its face counts as connected) and no column. That matters only where rooms must close (`space`); retaining, pit and free-standing walls may legitimately end free. Do not split or extend walls just to silence it. `build` also merges wall ends of the same level that are less than 5 cm apart and lists what it moved; anything farther apart is left exactly where you put it. Long warning lists are truncated β `bimdown build --verbose` prints all.
## 7. Doors and windows
Hosted on a wall, CSV only. Either give `host_id` + `position` (distance from the wall's start point to the opening centre), or give `host_x`, `host_y` (the opening centre) and let `build` resolve the nearest wall and position.
```csv
id,number,host_id,position,width,height,base_offset,operation,material
d-1,FMη²1022,w-3,1.5,1.0,2.2,0,single_swing,steel
```
```csv
id,number,host_id,position,width,height,base_offset,material
wn-1,C1515,w-7,4.2,1.5,1.5,0.9,aluminum
```
- `position Β± width/2` must stay within the wall; openings on one wall must not overlap.
- `base_offset` is measured from the level elevation (like Revit's sill height), even when the host wall starts below the level. Windows: always set it (0.9 typical); 0 puts the window on the level.
- Put the drawing's mark (e.g. `FMη²1022`, `C1515`) in `number`.
## 7b. Element types
Optional Revit-style types in `global/` (`bimdown init` writes a starter catalog scaled to the project units: metric sizes, names in mm; add imperial types in ft/in projects): `wall_type`, `slab_type`, `roof_type`, `ceiling_type` (layers in `type_layer.csv`), `door_type`, `window_type` (width, height, operation, `u_value`, `shgc`, `vt`), `curtain_wall_type`, `column_type`, `beam_type`.
- Elements set `type_id` and leave the type's fields empty (e.g. wall `thickness`, door `width`); a value they set overrides the type for that element.
- `type_layer.csv`: `id,type_id,seq,function,material,thickness,conductivity,name`; `seq` 1 = exterior / top, `function` core | substrate | insulation | air_gap | membrane | finish. Type thickness = sum of layers.
- A wall's layer 1 is on its left looking startβend: draw exterior walls clockwise seen from above.
- `bimdown query` returns effective values and joins types: `SELECT w.id, w.thickness, t.name FROM wall w JOIN wall_type t ON w.type_id = t.id`.
## 8. CLI reference
| Command | Purpose |
|---|---|
| `bimdown init [--units m\|mm\|ft\|in]` | new empty project |
| `bimdown import-ifc ` | new project from an IFC2x3 / IFC4 model (Revit, ArchiCAD β¦); builds it and reports skipped elements and room problems |
| `bimdown build ` | validate, snap, normalise, compute spaces β run after every edit |
| `bimdown render [-l level] [-o out.png] [-w width]` | plan image of a level |
| `bimdown query "" [--json]` | DuckDB SQL over all tables incl. computed fields |
| `bimdown info ` | element counts per level |
| `bimdown schema