Initial Commit
This commit is contained in:
229
openspec/changes/enterprise-osm-buildings/proposal.md
Normal file
229
openspec/changes/enterprise-osm-buildings/proposal.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# OpenSpec Change: enterprise-osm-buildings
|
||||
|
||||
- **Change ID**: enterprise-osm-buildings
|
||||
- **Package**: `@suaveplan/osm-buildings`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/geo/osm-buildings`
|
||||
- **Status**: IN PROGRESS
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/osm-buildings.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/osm-buildings` on the genesis branch from scratch at enterprise quality. The package provides OpenStreetMap building and road geometry extraction and mesh generation: OSM XML/PBF-lite parsing, building footprint extraction from `building=*` relations and ways, road network extraction from `highway=*` ways, polygon simplification (Ramer-Douglas-Peucker), 2.5D extruded building mesh generation (flat roof, pitched roof from `roof:shape=*`), LOD (level of detail) tile pyramid for buildings, elevation offset from `@suaveplan/heightmap-tiles`, GeoJSON and flat-buffer mesh output, and a streaming feature extractor. Genesis adds structured errors, Zod schemas, OTel instrumentation, and property-based tests.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet — this is a fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `OsmBuildingsError`; `OSM.*` error codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
|
||||
| `@suaveplan/geo` (`workspace:^`) | `LatLng`, `BoundingBox`, polygon area, coordinate utilities |
|
||||
| `@suaveplan/heightmap-tiles` (`workspace:^`) | Elevation offset for 3D building placement |
|
||||
| `@suaveplan/serialize` (`workspace:^`) | Binary flat-buffer output serialization |
|
||||
| `zod` (`catalog:forms`) | Schema validation |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||||
|
||||
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check` (all `catalog:testing`).
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
### Core types
|
||||
|
||||
```ts
|
||||
interface OsmBuilding {
|
||||
id: string // OSM way/relation ID
|
||||
footprint: LatLng[] // exterior ring, counter-clockwise
|
||||
holes: LatLng[][] // interior rings
|
||||
height: number // metres; 0 if unknown
|
||||
minHeight: number // metres above ground; for bridges/overhangs
|
||||
levels?: number
|
||||
roofShape?: RoofShape
|
||||
tags: Record<string, string> // raw OSM tags
|
||||
}
|
||||
|
||||
type RoofShape = 'flat' | 'pitched' | 'hipped' | 'dome' | 'pyramidal' | 'unknown'
|
||||
|
||||
interface OsmRoad {
|
||||
id: string
|
||||
points: LatLng[]
|
||||
highway: string // OSM highway value e.g. 'primary', 'residential'
|
||||
name?: string
|
||||
lanes?: number
|
||||
oneWay: boolean
|
||||
tags: Record<string, string>
|
||||
}
|
||||
|
||||
interface BuildingMesh {
|
||||
buildingId: string
|
||||
vertices: Float32Array // xyz triplets
|
||||
indices: Uint32Array // triangle indices
|
||||
uvs?: Float32Array // optional UV coords
|
||||
}
|
||||
```
|
||||
|
||||
### Parsers
|
||||
|
||||
```ts
|
||||
function parseOsmXml(xml: string, options?: ParseOptions): OsmFeatureSet
|
||||
function parseOsmPbfLite(buffer: Uint8Array, options?: ParseOptions): OsmFeatureSet
|
||||
|
||||
interface OsmFeatureSet {
|
||||
buildings: OsmBuilding[]
|
||||
roads: OsmRoad[]
|
||||
bbox: BoundingBox
|
||||
}
|
||||
|
||||
interface ParseOptions {
|
||||
bbox?: BoundingBox // filter to bounding box
|
||||
includeBuildings?: boolean // default true
|
||||
includeRoads?: boolean // default true
|
||||
signal?: AbortSignal
|
||||
}
|
||||
```
|
||||
|
||||
### Mesh generation
|
||||
|
||||
```ts
|
||||
function buildingToMesh(
|
||||
building: OsmBuilding,
|
||||
options?: MeshOptions
|
||||
): BuildingMesh
|
||||
|
||||
function buildingsToMeshes(
|
||||
buildings: OsmBuilding[],
|
||||
options?: MeshOptions
|
||||
): BuildingMesh[]
|
||||
|
||||
interface MeshOptions {
|
||||
store?: HeightmapTileStore // for elevation offset; optional
|
||||
lodLevel?: number // 0 = highest detail; higher = simplified
|
||||
uvScale?: number
|
||||
}
|
||||
```
|
||||
|
||||
### Simplification
|
||||
|
||||
```ts
|
||||
function simplifyPolygon(ring: LatLng[], toleranceMetres: number): LatLng[]
|
||||
function simplifyRoad(points: LatLng[], toleranceMetres: number): LatLng[]
|
||||
```
|
||||
|
||||
### Streaming extractor
|
||||
|
||||
```ts
|
||||
function createOsmFeatureStream(options?: ParseOptions): OsmFeatureStream
|
||||
|
||||
interface OsmFeatureStream {
|
||||
writable: WritableStream<Uint8Array> // OSM XML or PBF-lite bytes
|
||||
readable: ReadableStream<OsmBuilding | OsmRoad>
|
||||
}
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type OsmBuildingsErrorCode =
|
||||
| 'OSM_PARSE_FAILED'
|
||||
| 'OSM_INVALID_GEOMETRY'
|
||||
| 'OSM_MESH_FAILED'
|
||||
| 'OSM_ELEVATION_FAILED'
|
||||
| 'OSM_SIMPLIFY_FAILED'
|
||||
| 'OSM_ABORTED'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Genesis additions
|
||||
|
||||
1. **`OsmBuildingsError`** extends `SuaveplanError` with six stable codes.
|
||||
2. **Zod schemas** for `OsmBuilding`, `OsmRoad`, `OsmFeatureSet`, `ParseOptions`, `MeshOptions`, `BuildingMesh`.
|
||||
3. **PBF-lite parser** — supports a simplified subset of OSM PBF (nodes, ways, string table) without requiring a full protobuf library; implemented natively using `DataView` binary parsing.
|
||||
4. **LOD pyramid** — `lodLevel` in `MeshOptions` controls polygon simplification tolerance (level 0 = 0 m, level 1 = 1 m, level 2 = 5 m, level 3 = 20 m) for progressive rendering.
|
||||
5. **Elevation offset** — when a `HeightmapTileStore` is provided, building vertices receive a per-vertex Z offset from `@suaveplan/heightmap-tiles`; gracefully degrades to z=0 without a store.
|
||||
6. **OTel instrumentation** — counter `osm.buildings_parsed_total`; span `osm.parse` with attribute `osm.format`; histogram `osm.mesh_build_duration_ms`.
|
||||
7. **Property-based tests** — simplification never produces self-intersections; mesh index buffer references only valid vertex indices; Ramer-Douglas-Peucker preserves first and last points.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/geo/osm-buildings/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
parsers/
|
||||
osm-xml-parser/
|
||||
osm-xml-parser.ts
|
||||
osm-xml-parser.md
|
||||
osm-xml-parser.test.ts
|
||||
index.ts
|
||||
osm-pbf-parser/
|
||||
osm-pbf-parser.ts
|
||||
osm-pbf-parser.md
|
||||
osm-pbf-parser.test.ts
|
||||
index.ts
|
||||
feature-extractor/
|
||||
feature-extractor.ts
|
||||
feature-extractor.md
|
||||
feature-extractor.test.ts
|
||||
index.ts
|
||||
mesh/
|
||||
building-mesher/
|
||||
building-mesher.ts
|
||||
building-mesher.md
|
||||
building-mesher.types.ts
|
||||
building-mesher.test.ts
|
||||
index.ts
|
||||
roof-builder/
|
||||
roof-builder.ts
|
||||
roof-builder.md
|
||||
roof-builder.test.ts
|
||||
index.ts
|
||||
geometry/
|
||||
simplifier/
|
||||
simplifier.ts
|
||||
simplifier.md
|
||||
simplifier.test.ts
|
||||
index.ts
|
||||
streaming/
|
||||
osm-feature-stream/
|
||||
osm-feature-stream.ts
|
||||
osm-feature-stream.md
|
||||
osm-feature-stream.test.ts
|
||||
index.ts
|
||||
__benchmarks__/
|
||||
osm-buildings.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream consumers**: 3D map rendering services.
|
||||
|
||||
**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/geo`, `@suaveplan/heightmap-tiles`, `@suaveplan/serialize`.
|
||||
74
openspec/changes/enterprise-osm-buildings/tasks.md
Normal file
74
openspec/changes/enterprise-osm-buildings/tasks.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# Tasks: enterprise-osm-buildings
|
||||
|
||||
**Change ID**: enterprise-osm-buildings
|
||||
**Package**: `@suaveplan/osm-buildings`
|
||||
**Target path**: `universal/geo/osm-buildings`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/geo`, `@suaveplan/heightmap-tiles`, `@suaveplan/serialize`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create `universal/geo/osm-buildings/` with `src/`, `tests/`, `src/__benchmarks__/` and all feature subdirectories per the layout in `proposal.md`.
|
||||
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, correct `exports` map, `dependencies`, and `devDependencies`.
|
||||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||||
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Types + errors
|
||||
|
||||
- [ ] `src/types/common.ts` — `OsmBuilding`, `RoofShape`, `OsmRoad`, `OsmFeatureSet`, `ParseOptions`, `BuildingMesh`, `MeshOptions`, `OsmFeatureStream`.
|
||||
- [ ] `src/types/common.md` (≥200 words, both examples, API reference).
|
||||
- [ ] `src/error-codes.ts` — `OsmBuildingsErrorCode` (6 codes), metadata, register, eager call.
|
||||
- [ ] `src/types/schemas.ts` + `schemas.md` — Zod schemas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Core modules
|
||||
|
||||
- [ ] **`src/geometry/simplifier/`** — `simplifyPolygon(ring, toleranceMetres): LatLng[]`: Ramer-Douglas-Peucker algorithm; tolerance in metres (converted to degrees via approximate factor). `simplifyRoad(points, toleranceMetres): LatLng[]`. Tests: tolerance=0 preserves all points, high tolerance reduces to 2-4 points, first and last points always preserved.
|
||||
- [ ] **`src/parsers/feature-extractor/`** — `extractBuildings(nodes, ways, relations): OsmBuilding[]`: maps ways with `building=*` tag to footprints (outer ring from way nodes), handles multipolygon relations for buildings with holes. `extractRoads(ways): OsmRoad[]`: maps ways with `highway=*` tag. Tests: simple building way, multipolygon building with hole, road with name/lanes, skip ways without building/highway tags.
|
||||
- [ ] **`src/parsers/osm-xml-parser/`** — `parseOsmXml(xml, options): OsmFeatureSet`: parses `<node>`, `<way>`, `<relation>` elements using a SAX-style incremental parser (no DOM dependency); calls `extractBuildings`/`extractRoads`. Tests: minimal OSM XML with 2 buildings and 1 road, bbox filter, signal abort mid-parse.
|
||||
- [ ] **`src/parsers/osm-pbf-parser/`** — `parseOsmPbfLite(buffer, options): OsmFeatureSet`: parses OSM PBF blob header + primitive blocks using `DataView`; decodes string table; reconstructs nodes/ways; calls `extractBuildings`/`extractRoads`. Tests: small synthetic PBF buffer, bbox filter, malformed buffer throws `OSM_PARSE_FAILED`.
|
||||
- [ ] **`src/mesh/roof-builder/`** — `buildRoof(footprint, height, minHeight, roofShape): { vertices: number[], indices: number[] }`: generates roof geometry. `flat`: single quad. `pitched`: ridge along long axis. `hipped`, `pyramidal`: point apex. Unknown shape falls back to `flat`. Tests: flat roof vertex count, pitched ridge runs along correct axis, all indices reference valid vertices.
|
||||
- [ ] **`src/mesh/building-mesher/`** — `buildingToMesh(building, options): BuildingMesh`: triangulates footprint (ear clipping for convex, fan for convex shortcut), extrudes walls, calls `buildRoof`. Optional elevation offset from `HeightmapTileStore`. LOD simplification via `simplifyPolygon` based on `lodLevel`. `buildingsToMeshes` maps over array. Tests: unit square footprint → correct vertex count, hole in footprint handled, LOD=2 reduces vertex count vs LOD=0.
|
||||
- [ ] **`src/streaming/osm-feature-stream/`** — `createOsmFeatureStream(options): OsmFeatureStream`: Web Streams Transform; buffers bytes, detects format (XML starts with `<`, PBF has magic header), dispatches to appropriate parser incrementally, emits `OsmBuilding | OsmRoad` events. Tests: pipe a small OSM XML string, verify buildings/roads emitted, abort signal.
|
||||
|
||||
---
|
||||
|
||||
## 4. OTel instrumentation
|
||||
|
||||
- [ ] Counter `osm.buildings_parsed_total`; span `osm.parse` with attribute `osm.format` (`xml` or `pbf`); histogram `osm.mesh_build_duration_ms`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Property-based tests (`tests/property.test.ts`)
|
||||
|
||||
- [ ] Simplification: for arbitrary polylines, `simplifyRoad(points, tolerance)` never produces self-intersections and always preserves first/last point.
|
||||
- [ ] Mesh index validity: for arbitrary convex polygons as footprints, every index in `BuildingMesh.indices` is `< vertices.length / 3`.
|
||||
- [ ] Ramer-Douglas-Peucker: for arbitrary point arrays, output length ≤ input length.
|
||||
|
||||
---
|
||||
|
||||
## 6. Benchmarks (`src/__benchmarks__/osm-buildings.bench.ts`)
|
||||
|
||||
- [ ] `parseOsmXml` for a 500 KB OSM XML file with 200 buildings.
|
||||
- [ ] `buildingsToMeshes` for 200 buildings.
|
||||
|
||||
---
|
||||
|
||||
## 7. Docs + verify
|
||||
|
||||
- [ ] One `.md` per implementation file (≥200 words, both examples, API reference). Root `README.md`.
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/osm-buildings` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/osm-buildings` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/osm-buildings`.
|
||||
- [ ] Archive: `openspec/archive/2026-04-24-enterprise-osm-buildings/`.
|
||||
Reference in New Issue
Block a user