@jarenjs/core 0.9.2 → 0.34.0

package/src/geo/index-tree.js

@@ -0,0 +1,294 @@
+//@ts-check
+
+//#region Static bounding-box index
+// A packed Hilbert R-tree over bounding boxes: build once, query many.
+// Scanning n boxes to find the ones overlapping a query box is O(n); this
+// is O(log n + k) for k hits, which is the difference between a spatial
+// join being usable and not.
+//
+// **Static** is the deliberate part. A dynamic R-tree must keep its nodes
+// splittable, which costs both memory and insert time; a compiled query's
+// geometry never changes after the index is built, so the tree can be
+// packed into flat typed arrays with no per-node objects at all. The
+// tree is therefore built bottom-up: leaves are sorted along a Hilbert
+// curve — which keeps boxes that are near each other in space near each
+// other in the array — and then every `nodeSize` consecutive entries
+// become a parent.
+//
+// The query returns **candidates**, not answers. Box overlap is a
+// necessary condition for containment and for real intersection, never a
+// sufficient one, so a caller confirms each candidate with the exact
+// predicate. That is what makes indexing safe to apply automatically:
+// the index can only ever remove work, never change a result.
+
+/** Children per node. 16 is the usual sweet spot for cache behaviour. */
+const DEFAULT_NODE_SIZE = 16;
+
+/**
+ * Interleave the low 16 bits of x and y into a Hilbert distance.
+ * Boxes ordered by this stay spatially clustered, which is what makes
+ * the packed parents tight.
+ *
+ * Bit-parallel: all sixteen levels of the per-bit quadrant rotation run
+ * at once as mask arithmetic (the public-domain transform from
+ * rawrunprotected/hilbert_curves), which is what makes computing 100k of
+ * these a millisecond instead of the build's dominant cost. The values
+ * are identical to the classical per-bit walk of the curve.
+ *
+ * @param {number} x - 0..65535
+ * @param {number} y - 0..65535
+ * @returns {number}
+ */
+export function hilbertDistance(x, y) {
+  let a = x ^ y;
+  let b = 0xFFFF ^ a;
+  let c = 0xFFFF ^ (x | y);
+  let d = x & (y ^ 0xFFFF);
+  let A = a | (b >> 1);
+  let B = (a >> 1) ^ a;
+  let C = ((c >> 1) ^ (b & (d >> 1))) ^ c;
+  let D = ((a & (c >> 1)) ^ (d >> 1)) ^ d;
+
+  a = A; b = B; c = C; d = D;
+  A = (a & (a >> 2)) ^ (b & (b >> 2));
+  B = (a & (b >> 2)) ^ (b & ((a ^ b) >> 2));
+  C ^= (a & (c >> 2)) ^ (b & (d >> 2));
+  D ^= (b & (c >> 2)) ^ ((a ^ b) & (d >> 2));
+
+  a = A; b = B; c = C; d = D;
+  A = (a & (a >> 4)) ^ (b & (b >> 4));
+  B = (a & (b >> 4)) ^ (b & ((a ^ b) >> 4));
+  C ^= (a & (c >> 4)) ^ (b & (d >> 4));
+  D ^= (b & (c >> 4)) ^ ((a ^ b) & (d >> 4));
+
+  a = A; b = B; c = C; d = D;
+  C ^= (a & (c >> 8)) ^ (b & (d >> 8));
+  D ^= (b & (c >> 8)) ^ ((a ^ b) & (d >> 8));
+
+  a = C ^ (C >> 1);
+  b = D ^ (D >> 1);
+
+  let i0 = x ^ y;
+  let i1 = b | (0xFFFF ^ (i0 | a));
+
+  i0 = (i0 | (i0 << 8)) & 0x00FF00FF;
+  i0 = (i0 | (i0 << 4)) & 0x0F0F0F0F;
+  i0 = (i0 | (i0 << 2)) & 0x33333333;
+  i0 = (i0 | (i0 << 1)) & 0x55555555;
+
+  i1 = (i1 | (i1 << 8)) & 0x00FF00FF;
+  i1 = (i1 | (i1 << 4)) & 0x0F0F0F0F;
+  i1 = (i1 | (i1 << 2)) & 0x33333333;
+  i1 = (i1 | (i1 << 1)) & 0x55555555;
+
+  return ((i1 << 1) | i0) >>> 0;
+}
+
+/**
+ * A queryable static index over bounding boxes.
+ * @typedef {Object} BboxIndex
+ * @property {number} size - how many boxes were indexed
+ * @property {(minX: number, minY: number, maxX: number, maxY: number) => number[]} search
+ *   the indexes of every box whose bounds overlap the query box
+ */
+
+/**
+ * Build a static index over `[west, south, east, north]` boxes.
+ *
+ * The returned `search` yields **candidate** indexes into the original
+ * array: every box that truly overlaps is included, and boxes that merely
+ * share a tree node may be too. Confirm each with the exact test.
+ *
+ * A null entry (a value with no positions, so no box) is indexed as a
+ * degenerate box that overlaps nothing, so it can never be a candidate
+ * while the array indexes stay aligned with the caller's data.
+ *
+ * @param {Array<number[] | null>} boxes
+ * @param {number} [nodeSize] - children per node
+ * @returns {BboxIndex}
+ * @example
+ * const index = createBboxIndex(regions.map(bboxOf));
+ * for (const i of index.search(...bboxOf(point))) confirm(regions[i]);
+ */
+export function createBboxIndex(boxes, nodeSize = DEFAULT_NODE_SIZE) {
+  const count = boxes.length;
+  if (count === 0)
+    return { size: 0, search: () => [] };
+
+  const size = Math.max(2, Math.min(nodeSize | 0, 65535));
+
+  // level 0 is the leaves; each level packs the previous one
+  const levelBounds = [];
+  let n = count;
+  let total = n;
+  levelBounds.push(n * 4);
+  do {
+    n = Math.ceil(n / size);
+    total += n;
+    levelBounds.push(total * 4);
+  } while (n !== 1);
+
+  const bounds = new Float64Array(total * 4);
+  const indices = new Uint32Array(total);
+
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (let i = 0; i < count; i++) {
+    const box = boxes[i];
+    if (box === null || box === undefined)
+      continue;
+    if (box[0] < minX) minX = box[0];
+    if (box[1] < minY) minY = box[1];
+    if (box[2] > maxX) maxX = box[2];
+    if (box[3] > maxY) maxY = box[3];
+  }
+
+  // Sort a permutation along the Hilbert curve of the box centres, then
+  // write the bounds once, already in leaf order. The sort itself moves
+  // only a key and an index per swap — permuting the four-wide bounds
+  // rows through every partition swap is what made the build memory-bound.
+  const order = new Uint32Array(count);
+  for (let i = 0; i < count; i++)
+    order[i] = i;
+  if (count > 1 && Number.isFinite(minX)) {
+    const width = maxX - minX || 1;
+    const height = maxY - minY || 1;
+    const hilbert = new Uint32Array(count);
+    for (let i = 0; i < count; i++) {
+      const box = boxes[i];
+      if (box === null || box === undefined) {
+        // empties sort to the end (a real box may share this key, which
+        // is harmless: an empty's bounds can never match a query)
+        hilbert[i] = 0xFFFFFFFF;
+        continue;
+      }
+      const cx = Math.floor(65535 * ((box[0] + box[2]) / 2 - minX) / width);
+      const cy = Math.floor(65535 * ((box[1] + box[3]) / 2 - minY) / height);
+      hilbert[i] = hilbertDistance(cx, cy);
+    }
+    sortOrder(hilbert, order, 0, count - 1);
+  }
+
+  for (let i = 0; i < count; i++) {
+    const at = order[i];
+    const box = boxes[at];
+    const p = i * 4;
+    if (box === null || box === undefined) {
+      // a box that overlaps nothing: min above max on both axes
+      bounds[p] = Infinity;
+      bounds[p + 1] = Infinity;
+      bounds[p + 2] = -Infinity;
+      bounds[p + 3] = -Infinity;
+    }
+    else {
+      bounds[p] = box[0];
+      bounds[p + 1] = box[1];
+      bounds[p + 2] = box[2];
+      bounds[p + 3] = box[3];
+    }
+    indices[i] = at;
+  }
+
+  // pack each level into the next
+  let readAt = 0;
+  for (let level = 0; level < levelBounds.length - 1; level++) {
+    const levelEnd = levelBounds[level] / 4;
+    let writeAt = levelEnd;
+    while (readAt < levelEnd) {
+      const nodeStart = readAt;
+      let nodeMinX = Infinity;
+      let nodeMinY = Infinity;
+      let nodeMaxX = -Infinity;
+      let nodeMaxY = -Infinity;
+      for (let i = 0; i < size && readAt < levelEnd; i++, readAt++) {
+        const p = readAt * 4;
+        if (bounds[p] < nodeMinX) nodeMinX = bounds[p];
+        if (bounds[p + 1] < nodeMinY) nodeMinY = bounds[p + 1];
+        if (bounds[p + 2] > nodeMaxX) nodeMaxX = bounds[p + 2];
+        if (bounds[p + 3] > nodeMaxY) nodeMaxY = bounds[p + 3];
+      }
+      // a parent records where its children start, not a data index
+      indices[writeAt] = nodeStart;
+      const q = writeAt * 4;
+      bounds[q] = nodeMinX;
+      bounds[q + 1] = nodeMinY;
+      bounds[q + 2] = nodeMaxX;
+      bounds[q + 3] = nodeMaxY;
+      writeAt++;
+    }
+  }
+
+  const rootStart = total - 1;
+
+  return {
+    size: count,
+    search(qMinX, qMinY, qMaxX, qMaxY) {
+      const out = [];
+      // an explicit stack of [nodeIndex, levelEnd] rather than recursion
+      const stack = [rootStart, levelBounds.length - 1];
+      while (stack.length > 0) {
+        const level = stack.pop();
+        const nodeIndex = stack.pop();
+        const isLeafLevel = level === 0;
+        const end = Math.min(
+          nodeIndex + size,
+          levelBounds[level] / 4);
+        for (let pos = nodeIndex; pos < end; pos++) {
+          const p = pos * 4;
+          if (qMaxX < bounds[p] || qMaxY < bounds[p + 1]
+            || qMinX > bounds[p + 2] || qMinY > bounds[p + 3])
+            continue;
+          if (isLeafLevel)
+            out.push(indices[pos]);
+          else {
+            stack.push(indices[pos]);
+            stack.push(level - 1);
+          }
+        }
+      }
+      return out;
+    },
+  };
+}
+
+// In-place quicksort of the permutation by Hilbert distance: each swap
+// moves one key and one index, nothing wider. Small partitions finish
+// by insertion sort, which beats partitioning once a run fits in cache.
+function sortOrder(hilbert, order, left, right) {
+  if (right - left < 20) {
+    for (let i = left + 1; i <= right; i++) {
+      const h = hilbert[i];
+      const n = order[i];
+      let j = i - 1;
+      while (j >= left && hilbert[j] > h) {
+        hilbert[j + 1] = hilbert[j];
+        order[j + 1] = order[j];
+        j--;
+      }
+      hilbert[j + 1] = h;
+      order[j + 1] = n;
+    }
+    return;
+  }
+  const pivot = hilbert[(left + right) >> 1];
+  let i = left - 1;
+  let j = right + 1;
+  for (;;) {
+    do i++; while (hilbert[i] < pivot);
+    do j--; while (hilbert[j] > pivot);
+    if (i >= j)
+      break;
+    const h = hilbert[i];
+    hilbert[i] = hilbert[j];
+    hilbert[j] = h;
+    const n = order[i];
+    order[i] = order[j];
+    order[j] = n;
+  }
+  sortOrder(hilbert, order, left, j);
+  sortOrder(hilbert, order, j + 1, right);
+}
+
+//#endregion

package/src/geo/index.js

@@ -0,0 +1,52 @@
+//@ts-check
+
+//#region @jarenjs/core/geo
+// The suite's spatial kernel. There is no geometry type: the
+// representation is GeoJSON (RFC 7946), whose positions are
+// `[longitude, latitude]` arrays and whose rings are arrays of those —
+// already JSON items, so they are patchable, schema-checkable and
+// addressable by pointer and path. A wrapper class would break all four,
+// the same way it does for dates.
+//
+// Everything here therefore takes plain numbers and plain arrays. A
+// Polygon's `coordinates` IS an array of rings, so a function that takes
+// a ring takes GeoJSON without needing to know the `type` discriminator;
+// walking a tagged geometry belongs to the layer above.
+//
+//   angle.js       the degree↔radian factors the trigonometry shares
+//   predicates.js  robust orientation — the sign every test rests on
+//   distance.js    great-circle measurement over the WGS 84 sphere
+//   ring.js        ring closure, winding, area and containment
+//   bbox.js        bounding boxes: the cheap half of every spatial test
+//   geohash.js     the string encoding that needs no new vocabulary
+//   geojson.js     the one layer that knows the `type` discriminator
+//   valid.js       the one-call structural judgment (rings must close)
+//   wkt.js         a validity tester for the databases' text encoding
+//   index-tree.js  a static packed-Hilbert box index for spatial joins
+//   mercator.js    the projection out, for anything that draws a map
+//   simplify.js    dropping the vertices that land on the same pixel
+//
+// RFC 7946 removed coordinate-reference-system support and mandates WGS
+// 84 in decimal degrees, so there is deliberately no SRID table and no
+// reprojection *in*: conformance removes the need rather than an
+// omission hiding it. The one projection that does exist goes the other
+// way — a sphere has to become a rectangle before anyone can look at it
+// — and it comes with the rule that keeps the two apart: **never
+// measure on a projected coordinate.** `geometryArea` and
+// `haversineDistance` work on the sphere; `projectMercator` is for
+// drawing, and a Mercator "area" is off by a factor of fourteen at
+// Greenland.
+
+export * from './predicates.js';
+export * from './distance.js';
+export * from './ring.js';
+export * from './bbox.js';
+export * from './geohash.js';
+export * from './geojson.js';
+export * from './valid.js';
+export * from './wkt.js';
+export * from './index-tree.js';
+export * from './mercator.js';
+export * from './simplify.js';
+
+//#endregion

package/src/geo/mercator.js

@@ -0,0 +1,124 @@
+//@ts-check
+
+//#region Web Mercator
+// The projection maps go out through, and the only one this module
+// family carries. RFC 7946 fixes the coordinate reference *system* to
+// WGS 84, so there is nothing to configure on the way in; a projection
+// is what happens on the way **out**, when a sphere has to become a
+// rectangle somebody can draw.
+//
+// Web Mercator (EPSG:3857) is the choice because it is what every tile
+// server, every slippy map and every reader's intuition already uses.
+// Its costs are worth stating rather than discovering: it is conformal
+// (shapes stay locally correct, which is why it looks right) but wildly
+// area-distorting toward the poles — Greenland renders about the size of
+// Africa and is fourteen times smaller. **Never measure on a projected
+// coordinate.** `geometryArea` and `haversineDistance` work on the
+// sphere for exactly this reason; these functions are for drawing.
+//
+// Latitude is clamped to ±85.051129°, where the projection reaches a
+// square. Beyond that y runs to infinity, so the poles are not
+// representable and a caller asking for them gets the edge instead of a
+// NaN that would poison a whole path string.
+
+import { clamp01 } from '../math/float64.js';
+import { DEG, RAD } from './angle.js';
+
+/**
+ * The latitude where Web Mercator's y reaches the edge of its square.
+ * Poleward of this the projection is unbounded.
+ */
+export const MERCATOR_MAX_LAT = 85.05112877980659;
+
+/**
+ * Project a position into the Web Mercator unit square: x and y both in
+ * `[0, 1]`, with **y increasing southward** so the result is already in
+ * screen order and a renderer needs no flip.
+ *
+ * Latitude is clamped, longitude is not: a latitude past the Mercator
+ * limit has a defensible answer (the edge) while a longitude past ±180
+ * is simply invalid under RFC 7946, and folding it silently into range
+ * would move a shape to the wrong side of the world rather than let the
+ * defect show.
+ *
+ * @param {number} lon - longitude in degrees, `[-180, 180]`
+ * @param {number} lat - latitude in degrees, clamped to ±85.051129
+ * @returns {[number, number]} `[x, y]` in the unit square
+ * @example
+ * projectMercator(0, 0);      // [0.5, 0.5] — null island is the centre
+ * projectMercator(-180, 85.05112877980659); // [0, 0] — the north-west corner
+ */
+export function projectMercator(lon, lat) {
+  const clamped = lat > MERCATOR_MAX_LAT
+    ? MERCATOR_MAX_LAT
+    : (lat < -MERCATOR_MAX_LAT ? -MERCATOR_MAX_LAT : lat);
+  const x = (lon + 180) / 360;
+  const s = Math.sin(clamped * DEG);
+  // atanh(sin lat), spelled out: the log form is the standard one and
+  // avoids a tan that runs to infinity as the latitude nears the pole.
+  // Clamped because at exactly ±MERCATOR_MAX_LAT the true answer is 0 or
+  // 1 and the arithmetic lands an ULP outside — so the clamp is the more
+  // accurate value, not a fudge, and it makes the `[0, 1]` range a fact.
+  const y = clamp01(0.5 - Math.log((1 + s) / (1 - s)) / (4 * Math.PI));
+  return [x, y];
+}
+
+/**
+ * The inverse of {@link projectMercator}: a unit-square point back to a
+ * position. Needed to turn a click or a viewport corner back into
+ * longitude and latitude.
+ *
+ * @param {number} x - 0..1
+ * @param {number} y - 0..1, increasing southward
+ * @returns {[number, number]} `[longitude, latitude]` in degrees
+ */
+export function unprojectMercator(x, y) {
+  const lon = x * 360 - 180;
+  const lat = (2 * Math.atan(Math.exp((0.5 - y) * 2 * Math.PI)) - Math.PI / 2) * RAD;
+  return [lon, lat];
+}
+
+/**
+ * A projection fitted to a geographic bounding box: the transform that
+ * maps positions inside `bbox` into `[0, 1]` on both axes, **without
+ * distorting the aspect ratio**, centring whichever axis has room left
+ * over.
+ *
+ * Stretching a map to fill its frame is the single most common way to
+ * make one look wrong, so the fit is uniform by construction and the
+ * spare room becomes margin rather than distortion. `aspect` is the
+ * width:height ratio of the frame the result will be drawn into: the fit
+ * happens in a box `aspect` wide and 1 tall, then x is divided back down
+ * so both outputs are in `[0, 1]` — the same unit-square convention the
+ * treemap uses, where the renderer maps height from width by the same
+ * ratio.
+ *
+ * @param {number[]} bbox - `[west, south, east, north]`
+ * @param {number} [aspect] - frame width:height (default 1, a square)
+ * @returns {(lon: number, lat: number) => [number, number]}
+ * @example
+ * const fit = fitMercator([4, 52, 5, 53], 1.6);
+ * fit(4.5, 52.5); // near [0.5, 0.5] whatever the box's shape
+ */
+export function fitMercator(bbox, aspect = 1) {
+  const [x0, y1] = projectMercator(bbox[0], bbox[1]); // west, south -> y is max
+  const [x1, y0] = projectMercator(bbox[2], bbox[3]); // east, north -> y is min
+  const width = x1 - x0;
+  const height = y1 - y0;
+  // one scale for both axes — whichever runs out of frame first sets it
+  const scale = Math.min(
+    width > 0 ? aspect / width : Infinity,
+    height > 0 ? 1 / height : Infinity);
+  // a degenerate box (one position, or a box with no extent either way)
+  // has nothing to scale by; centre everything rather than divide by zero
+  if (!(scale > 0) || !Number.isFinite(scale))
+    return () => [0.5, 0.5];
+  const padX = (aspect - width * scale) / 2;
+  const padY = (1 - height * scale) / 2;
+  return (lon, lat) => {
+    const [px, py] = projectMercator(lon, lat);
+    return [((px - x0) * scale + padX) / aspect, (py - y0) * scale + padY];
+  };
+}
+
+//#endregion