@osmix/core 0.1.10 → 0.3.0

package/src/indirect-kd-index.ts

@@ -0,0 +1,212 @@
+/**
+ * A compact static KD index over coordinate columns owned by another object.
+ *
+ * The selection and traversal algorithms are adapted from KDBush 4.1.0,
+ * Copyright (c) 2018 Vladimir Agafonkin, distributed under the ISC License.
+ * Unlike KDBush, this index stores only a Uint32 permutation. Coordinates are
+ * dereferenced from the existing Int32 microdegree columns.
+ */
+
+import type { BufferType } from "./typed-arrays.ts";
+import { BufferConstructor } from "./typed-arrays.ts";
+
+const DEFAULT_NODE_SIZE = 64;
+
+export class IndirectKdIndex {
+  readonly indexes: Uint32Array;
+  private readonly lons: Int32Array;
+  private readonly lats: Int32Array;
+  private readonly nodeSize: number;
+
+  constructor(
+    lons: Int32Array,
+    lats: Int32Array,
+    indexes: Uint32Array,
+    nodeSize = DEFAULT_NODE_SIZE,
+  ) {
+    this.lons = lons;
+    this.lats = lats;
+    this.indexes = indexes;
+    this.nodeSize = nodeSize;
+  }
+
+  static build(
+    lons: Int32Array,
+    lats: Int32Array,
+    count: number,
+    fill: (indexes: Uint32Array) => void,
+  ): IndirectKdIndex {
+    const buffer = new BufferConstructor(count * Uint32Array.BYTES_PER_ELEMENT);
+    const indexes = new Uint32Array(buffer);
+    fill(indexes);
+    sortKd(indexes, lons, lats, DEFAULT_NODE_SIZE, 0, indexes.length - 1, 0);
+    return new IndirectKdIndex(lons, lats, indexes);
+  }
+
+  static from(lons: Int32Array, lats: Int32Array, buffer: BufferType): IndirectKdIndex {
+    if (buffer.byteLength % Uint32Array.BYTES_PER_ELEMENT !== 0) {
+      throw new Error("Indirect KD index buffer length must be divisible by four");
+    }
+    return new IndirectKdIndex(lons, lats, new Uint32Array(buffer));
+  }
+
+  get buffer(): BufferType {
+    return this.indexes.buffer as BufferType;
+  }
+
+  /**
+   * Find entity indexes within an inclusive bounding box.
+   *
+   * Bounds are **integer microdegrees** (the units of the underlying Int32
+   * coordinate columns), not degrees. `Nodes.findIndexesWithinBbox` performs
+   * the degree → microdegree conversion.
+   */
+  range(minLon: number, minLat: number, maxLon: number, maxLat: number): number[] {
+    const stack = [0, this.indexes.length - 1, 0];
+    const result: number[] = [];
+
+    while (stack.length > 0) {
+      const axis = stack.pop();
+      const right = stack.pop();
+      const left = stack.pop();
+      if (axis === undefined || right === undefined || left === undefined) {
+        throw new Error("Indirect KD index traversal stack is corrupt");
+      }
+
+      if (right - left <= this.nodeSize) {
+        for (let i = left; i <= right; i++) {
+          const entityIndex = entityAt(this.indexes, i);
+          const lon = coordinate(this.lons, this.lats, entityIndex, 0);
+          const lat = coordinate(this.lons, this.lats, entityIndex, 1);
+          if (lon >= minLon && lon <= maxLon && lat >= minLat && lat <= maxLat) {
+            result.push(entityIndex);
+          }
+        }
+        continue;
+      }
+
+      const middle = (left + right) >> 1;
+      const entityIndex = entityAt(this.indexes, middle);
+      const lon = coordinate(this.lons, this.lats, entityIndex, 0);
+      const lat = coordinate(this.lons, this.lats, entityIndex, 1);
+
+      if (lon >= minLon && lon <= maxLon && lat >= minLat && lat <= maxLat) {
+        result.push(entityIndex);
+      }
+
+      const splitCoordinate = axis === 0 ? lon : lat;
+      const minimum = axis === 0 ? minLon : minLat;
+      const maximum = axis === 0 ? maxLon : maxLat;
+      if (minimum <= splitCoordinate) stack.push(left, middle - 1, 1 - axis);
+      if (maximum >= splitCoordinate) stack.push(middle + 1, right, 1 - axis);
+    }
+
+    return result;
+  }
+}
+
+function sortKd(
+  indexes: Uint32Array,
+  lons: Int32Array,
+  lats: Int32Array,
+  nodeSize: number,
+  left: number,
+  right: number,
+  axis: number,
+) {
+  if (right - left <= nodeSize) return;
+  const middle = (left + right) >> 1;
+  select(indexes, lons, lats, middle, left, right, axis);
+  sortKd(indexes, lons, lats, nodeSize, left, middle - 1, 1 - axis);
+  sortKd(indexes, lons, lats, nodeSize, middle + 1, right, 1 - axis);
+}
+
+/** Floyd-Rivest selection adapted to dereference coordinates indirectly. */
+function select(
+  indexes: Uint32Array,
+  lons: Int32Array,
+  lats: Int32Array,
+  k: number,
+  initialLeft: number,
+  initialRight: number,
+  axis: number,
+) {
+  let left = initialLeft;
+  let right = initialRight;
+
+  while (right > left) {
+    if (right - left > 600) {
+      const n = right - left + 1;
+      const m = k - left + 1;
+      const z = Math.log(n);
+      const s = 0.5 * Math.exp((2 * z) / 3);
+      const sd = 0.5 * Math.sqrt((z * s * (n - s)) / n) * (m - n / 2 < 0 ? -1 : 1);
+      const newLeft = Math.max(left, Math.floor(k - (m * s) / n + sd));
+      const newRight = Math.min(right, Math.floor(k + ((n - m) * s) / n + sd));
+      select(indexes, lons, lats, k, newLeft, newRight, axis);
+    }
+
+    const pivotIndex = entityAt(indexes, k);
+    const pivot = coordinate(lons, lats, pivotIndex, axis);
+    let i = left;
+    let j = right;
+
+    swap(indexes, left, k);
+    if (compareCoordinate(lons, lats, entityAt(indexes, right), pivotIndex, axis) > 0) {
+      swap(indexes, left, right);
+    }
+
+    while (i < j) {
+      swap(indexes, i, j);
+      i++;
+      j--;
+      while (i <= right && coordinate(lons, lats, entityAt(indexes, i), axis) < pivot) i++;
+      while (j >= left && coordinate(lons, lats, entityAt(indexes, j), axis) > pivot) j--;
+    }
+
+    if (coordinate(lons, lats, entityAt(indexes, left), axis) === pivot) {
+      swap(indexes, left, j);
+    } else {
+      j++;
+      swap(indexes, j, right);
+    }
+
+    if (j <= k) left = j + 1;
+    if (k <= j) right = j - 1;
+  }
+}
+
+/**
+ * Read the permutation entry at `position`, throwing on an out-of-bounds read.
+ * A silent skip here would leave the permutation subtly unsorted and produce
+ * wrong query results, so fail loudly instead.
+ */
+function entityAt(indexes: Uint32Array, position: number): number {
+  const value = indexes[position];
+  if (value === undefined) {
+    throw new Error(`Indirect KD index read out of bounds at position ${position}`);
+  }
+  return value;
+}
+
+function coordinate(lons: Int32Array, lats: Int32Array, entityIndex: number, axis: number): number {
+  const value = axis === 0 ? lons[entityIndex] : lats[entityIndex];
+  if (value === undefined) throw new Error(`Missing coordinate for node index ${entityIndex}`);
+  return value;
+}
+
+function compareCoordinate(
+  lons: Int32Array,
+  lats: Int32Array,
+  a: number,
+  b: number,
+  axis: number,
+): number {
+  return coordinate(lons, lats, a, axis) - coordinate(lons, lats, b, axis);
+}
+
+function swap(indexes: Uint32Array, a: number, b: number) {
+  const valueA = entityAt(indexes, a);
+  indexes[a] = entityAt(indexes, b);
+  indexes[b] = valueA;
+}

package/src/limits.ts

@@ -0,0 +1,73 @@
+/**
+ * Hard capacity limits set by the typed-array layout of `Osm` storage.
+ *
+ * See `docs/limits.md` for the full list, including limits that come from the
+ * JavaScript engine rather than from this layout.
+ */
+
+/** Largest number of node refs one way can hold (`Ways.refCount` is a `Uint16Array`). */
+export const MAX_WAY_REFS = 0xffff;
+
+/** Largest number of members one relation can hold (`Relations.memberCount` is a `Uint16Array`). */
+export const MAX_RELATION_MEMBERS = 0xffff;
+
+/** Largest UTF-8 byte length of one string (`StringTable.count` is a `Uint16Array`). */
+export const MAX_STRING_BYTES = 0xffff;
+
+/**
+ * Largest element offset a `Uint32Array` offset column can store. Bounds the total
+ * way refs, relation members and string-table bytes in one dataset.
+ */
+export const MAX_UINT32_OFFSET = 0xffffffff;
+
+/** The storage limit an {@link OsmCapacityError} reports. */
+export type OsmCapacityLimit =
+  | "way-refs"
+  | "relation-members"
+  | "string-bytes"
+  | "total-way-refs"
+  | "total-relation-members"
+  | "total-string-bytes";
+
+/** Thrown when an entity or dataset is larger than the storage layout can hold. */
+export class OsmCapacityError extends Error {
+  readonly code = "OSM_CAPACITY_EXCEEDED";
+  readonly limit: OsmCapacityLimit;
+  readonly value: number;
+  readonly max: number;
+
+  constructor(limit: OsmCapacityLimit, value: number, max: number, subject: string) {
+    super(
+      `${subject} has ${value.toLocaleString("en-US")} ${capacityUnit(limit)}; ` +
+        `Osmix stores at most ${max.toLocaleString("en-US")}.`,
+    );
+    this.name = "OsmCapacityError";
+    this.limit = limit;
+    this.value = value;
+    this.max = max;
+  }
+}
+
+function capacityUnit(limit: OsmCapacityLimit): string {
+  switch (limit) {
+    case "way-refs":
+    case "total-way-refs":
+      return "node refs";
+    case "relation-members":
+    case "total-relation-members":
+      return "members";
+    case "string-bytes":
+    case "total-string-bytes":
+      return "UTF-8 bytes";
+  }
+}
+
+/** Throw {@link OsmCapacityError} when `value` is above `max`. */
+export function assertCapacity(
+  limit: OsmCapacityLimit,
+  value: number,
+  max: number,
+  subject: () => string,
+): void {
+  if (value > max) throw new OsmCapacityError(limit, value, max, subject());
+}

package/src/mocks.ts

@@ -1,49 +1,50 @@
-import type { OsmNode } from "@osmix/shared/types"
-import { Osm } from "./osm.ts"
+import type { OsmNode } from "@osmix/types";
 
-const YAKIM_LAT = 46.60207
-const YAKIM_LON = -120.505898
+import { Osm } from "./osm.ts";
 
-const ONE_KM_LON = 0.0131 // approximately
-const ONE_KM_LAT = 0.009
+const YAKIM_LAT = 46.60207;
+const YAKIM_LON = -120.505898;
+
+const ONE_KM_LON = 0.0131; // approximately
+const ONE_KM_LAT = 0.009;
 
 const node0: OsmNode = {
-	id: 0,
-	lat: YAKIM_LAT,
-	lon: YAKIM_LON,
-}
+  id: 0,
+  lat: YAKIM_LAT,
+  lon: YAKIM_LON,
+};
 
 const node1: OsmNode = {
-	id: 1,
-	lat: YAKIM_LAT,
-	lon: YAKIM_LON - ONE_KM_LON, // approximately 1km west
-}
+  id: 1,
+  lat: YAKIM_LAT,
+  lon: YAKIM_LON - ONE_KM_LON, // approximately 1km west
+};
 
 function addBaseNodes(osm: Osm) {
-	osm.nodes.addNode(node0)
-	osm.nodes.addNode(node1)
+  osm.nodes.addNode(node0);
+  osm.nodes.addNode(node1);
 }
 
 function addBaseWays(osm: Osm) {
-	osm.ways.addWay({
-		id: 1,
-		refs: [0, 1],
-		tags: {
-			highway: "primary",
-		},
-	})
+  osm.ways.addWay({
+    id: 1,
+    refs: [0, 1],
+    tags: {
+      highway: "primary",
+    },
+  });
 }
 
 /**
  * Create a base OSM with one way and two nodes.
  */
 export function createMockBaseOsm(): Osm {
-	const base = new Osm()
-	addBaseNodes(base)
-	base.nodes.buildIndex()
-	addBaseWays(base)
-	base.buildIndexes()
-	return base
+  const base = new Osm();
+  addBaseNodes(base);
+  base.nodes.buildIndex();
+  addBaseWays(base);
+  base.buildIndexes();
+  return base;
 }
 
 /**
@@ -53,88 +54,88 @@ export function createMockBaseOsm(): Osm {
  * - A way that crosses over the first way, but does not share a node and so starts disconnected
  */
 export function createMockPatchOsm(): Osm {
-	const osm = new Osm()
-
-	addBaseNodes(osm)
-
-	// Add way the connects with base way node 0 (will replace it)
-	osm.nodes.addNode({
-		...node0,
-		id: 2,
-		tags: {
-			crossing: "yes",
-		},
-	})
-	osm.nodes.addNode({
-		...node1,
-		id: 3,
-		lon: YAKIM_LON + ONE_KM_LON, // ends 1km east of the center point
-	})
-
-	// Add nodes for disconnected way
-	osm.nodes.addNode({
-		id: 4,
-		lat: YAKIM_LAT - ONE_KM_LAT, // 1km south
-		lon: YAKIM_LON + ONE_KM_LON / 4, // 250m east
-	})
-	osm.nodes.addNode({
-		id: 5,
-		lat: YAKIM_LAT + ONE_KM_LAT, // 1km north
-		lon: YAKIM_LON + ONE_KM_LON / 4, // 250m east
-	})
-
-	// Add nodes for crossing way
-	osm.nodes.addNode({
-		id: 6,
-		lat: YAKIM_LAT - ONE_KM_LAT, // 1km south
-		lon: YAKIM_LON + ONE_KM_LON / 2, // 500m east
-	})
-	osm.nodes.addNode({
-		id: 7,
-		lat: YAKIM_LAT + ONE_KM_LAT, // 1km north
-		lon: YAKIM_LON + ONE_KM_LON / 2, // 500m east
-	})
-
-	osm.nodes.buildIndex()
-
-	// Add same base way with new tags
-	osm.ways.addWay({
-		id: 1,
-		refs: [0, 1],
-		tags: {
-			highway: "primary",
-			version: "2",
-		},
-	})
-
-	// Add way that overlaps with base way node 1. Node should be de-duplicated.
-	osm.ways.addWay({
-		id: 2,
-		refs: [2, 3],
-		tags: {
-			highway: "secondary",
-		},
-	})
-
-	// Add way that crosses way 2, and should generate 1 intersection.
-	osm.ways.addWay({
-		id: 3,
-		refs: [4, 5],
-		tags: {
-			highway: "primary",
-		},
-	})
-
-	// Add a way that crosses way 2, but has a tag indicating it is an underpass and should be left alone
-	osm.ways.addWay({
-		id: 4,
-		refs: [6, 7],
-		tags: {
-			highway: "underpass",
-			tunnel: "yes",
-		},
-	})
-
-	osm.buildIndexes()
-	return osm
+  const osm = new Osm();
+
+  addBaseNodes(osm);
+
+  // Add way the connects with base way node 0 (will replace it)
+  osm.nodes.addNode({
+    ...node0,
+    id: 2,
+    tags: {
+      crossing: "yes",
+    },
+  });
+  osm.nodes.addNode({
+    ...node1,
+    id: 3,
+    lon: YAKIM_LON + ONE_KM_LON, // ends 1km east of the center point
+  });
+
+  // Add nodes for disconnected way
+  osm.nodes.addNode({
+    id: 4,
+    lat: YAKIM_LAT - ONE_KM_LAT, // 1km south
+    lon: YAKIM_LON + ONE_KM_LON / 4, // 250m east
+  });
+  osm.nodes.addNode({
+    id: 5,
+    lat: YAKIM_LAT + ONE_KM_LAT, // 1km north
+    lon: YAKIM_LON + ONE_KM_LON / 4, // 250m east
+  });
+
+  // Add nodes for crossing way
+  osm.nodes.addNode({
+    id: 6,
+    lat: YAKIM_LAT - ONE_KM_LAT, // 1km south
+    lon: YAKIM_LON + ONE_KM_LON / 2, // 500m east
+  });
+  osm.nodes.addNode({
+    id: 7,
+    lat: YAKIM_LAT + ONE_KM_LAT, // 1km north
+    lon: YAKIM_LON + ONE_KM_LON / 2, // 500m east
+  });
+
+  osm.nodes.buildIndex();
+
+  // Add same base way with new tags
+  osm.ways.addWay({
+    id: 1,
+    refs: [0, 1],
+    tags: {
+      highway: "primary",
+      version: "2",
+    },
+  });
+
+  // Add way that overlaps with base way node 1. Node should be de-duplicated.
+  osm.ways.addWay({
+    id: 2,
+    refs: [2, 3],
+    tags: {
+      highway: "secondary",
+    },
+  });
+
+  // Add way that crosses way 2, and should generate 1 intersection.
+  osm.ways.addWay({
+    id: 3,
+    refs: [4, 5],
+    tags: {
+      highway: "primary",
+    },
+  });
+
+  // Add a way that crosses way 2, but has a tag indicating it is an underpass and should be left alone
+  osm.ways.addWay({
+    id: 4,
+    refs: [6, 7],
+    tags: {
+      highway: "underpass",
+      tunnel: "yes",
+    },
+  });
+
+  osm.buildIndexes();
+  return osm;
 }