@jarenjs/core 0.9.2 → 0.34.0

package/src/geo/predicates.js

@@ -0,0 +1,313 @@
+//@ts-check
+
+//#region Robust geometric predicates
+// The orientation test every spatial operation rests on: is point c left
+// of, right of, or exactly on the directed line a->b? Point-in-polygon,
+// segment intersection, convex hull and ring winding are all sign tests
+// on this one determinant.
+//
+// Computing it directly in floating point is WRONG, not merely imprecise.
+// The subtractions and products each round, and on near-collinear input
+// the accumulated error can exceed the determinant itself, so the sign
+// flips. A predicate that returns the wrong sign is not a small error:
+// it makes a containment test contradict itself and a clipper emit
+// self-intersecting output.
+//
+// The insidious part is that it does not fail on ordinary data. It needs
+// coordinates that are close to collinear relative to their magnitude —
+// which is exactly what real survey and OpenStreetMap data contains, and
+// exactly what a hand-written test does not. So the exact path is here
+// from the start rather than added after something looked correct.
+//
+// The method is Shewchuk's adaptive precision arithmetic (Jonathan R.
+// Shewchuk, "Adaptive Precision Floating-Point Arithmetic and Fast
+// Robust Geometric Predicates", 1996): evaluate with a cheap error
+// bound, and only when the sign is not certain fall back to exact
+// arithmetic carried in non-overlapping floating-point expansions. The
+// common case pays one comparison over the naive form; the exact path
+// runs only where the naive form would have been wrong.
+
+// The unit roundoff for IEEE doubles, and Shewchuk's derived bounds.
+const EPSILON = 1.1102230246251565e-16; // 2^-53
+const CCW_ERRBOUND_A = (3 + 16 * EPSILON) * EPSILON;
+const CCW_ERRBOUND_B = (2 + 12 * EPSILON) * EPSILON;
+const CCW_ERRBOUND_C = (9 + 64 * EPSILON) * EPSILON * EPSILON;
+const RESULT_ERRBOUND = (3 + 8 * EPSILON) * EPSILON;
+
+// Dekker's splitter, 2^ceil(53/2) + 1: splits a double into two halves
+// whose product with another half is exact.
+const SPLITTER = 134217729;
+
+// Scratch expansions. Reused across calls to keep the exact path
+// allocation-free; the predicate is synchronous and never re-entered.
+const B = new Float64Array(4);
+const C1 = new Float64Array(8);
+const C2 = new Float64Array(12);
+const D = new Float64Array(16);
+const U = new Float64Array(4);
+
+/**
+ * Sum two expansions, eliminating zero components (Shewchuk's
+ * `fast_expansion_sum_zeroelim`). Both inputs are non-overlapping and
+ * increasing in magnitude; so is the result.
+ * @param {number} elen
+ * @param {Float64Array} e
+ * @param {number} flen
+ * @param {Float64Array} f
+ * @param {Float64Array} h - output
+ * @returns {number} the number of components written
+ */
+function expansionSum(elen, e, flen, f, h) {
+  let enow = e[0];
+  let fnow = f[0];
+  let eindex = 0;
+  let findex = 0;
+  let Q, Qnew, hh, bvirt;
+  if ((fnow > enow) === (fnow > -enow)) {
+    Q = enow;
+    enow = e[++eindex];
+  }
+  else {
+    Q = fnow;
+    fnow = f[++findex];
+  }
+  let hindex = 0;
+  if (eindex < elen && findex < flen) {
+    if ((fnow > enow) === (fnow > -enow)) {
+      Qnew = enow + Q;
+      hh = Q - (Qnew - enow);
+      enow = e[++eindex];
+    }
+    else {
+      Qnew = fnow + Q;
+      hh = Q - (Qnew - fnow);
+      fnow = f[++findex];
+    }
+    Q = Qnew;
+    if (hh !== 0)
+      h[hindex++] = hh;
+    while (eindex < elen && findex < flen) {
+      if ((fnow > enow) === (fnow > -enow)) {
+        Qnew = Q + enow;
+        bvirt = Qnew - Q;
+        hh = Q - (Qnew - bvirt) + (enow - bvirt);
+        enow = e[++eindex];
+      }
+      else {
+        Qnew = Q + fnow;
+        bvirt = Qnew - Q;
+        hh = Q - (Qnew - bvirt) + (fnow - bvirt);
+        fnow = f[++findex];
+      }
+      Q = Qnew;
+      if (hh !== 0)
+        h[hindex++] = hh;
+    }
+  }
+  while (eindex < elen) {
+    Qnew = Q + enow;
+    bvirt = Qnew - Q;
+    hh = Q - (Qnew - bvirt) + (enow - bvirt);
+    enow = e[++eindex];
+    Q = Qnew;
+    if (hh !== 0)
+      h[hindex++] = hh;
+  }
+  while (findex < flen) {
+    Qnew = Q + fnow;
+    bvirt = Qnew - Q;
+    hh = Q - (Qnew - bvirt) + (fnow - bvirt);
+    fnow = f[++findex];
+    Q = Qnew;
+    if (hh !== 0)
+      h[hindex++] = hh;
+  }
+  if (Q !== 0 || hindex === 0)
+    h[hindex++] = Q;
+  return hindex;
+}
+
+/**
+ * The approximate value of an expansion: its components summed.
+ * @param {number} elen
+ * @param {Float64Array} e
+ * @returns {number}
+ */
+function estimate(elen, e) {
+  let Q = e[0];
+  for (let i = 1; i < elen; i++)
+    Q += e[i];
+  return Q;
+}
+
+/**
+ * The exact stage: the determinant as an expansion, returning its
+ * (exactly correct) leading component.
+ * @returns {number}
+ */
+function orient2dExact(ax, ay, bx, by, cx, cy, detsum) {
+  let acx, acy, bcx, bcy, acxtail, acytail, bcxtail, bcytail;
+  let s1, s0, t1, t0, u3, bvirt, c, ahi, alo, bhi, blo, _i, _j, _0;
+
+  acx = ax - cx;
+  bcx = bx - cx;
+  acy = ay - cy;
+  bcy = by - cy;
+
+  // two_product(acx, bcy) and two_product(acy, bcx), exactly
+  s1 = acx * bcy;
+  c = SPLITTER * acx;
+  ahi = c - (c - acx);
+  alo = acx - ahi;
+  c = SPLITTER * bcy;
+  bhi = c - (c - bcy);
+  blo = bcy - bhi;
+  s0 = alo * blo - (s1 - ahi * bhi - alo * bhi - ahi * blo);
+  t1 = acy * bcx;
+  c = SPLITTER * acy;
+  ahi = c - (c - acy);
+  alo = acy - ahi;
+  c = SPLITTER * bcx;
+  bhi = c - (c - bcx);
+  blo = bcx - bhi;
+  t0 = alo * blo - (t1 - ahi * bhi - alo * bhi - ahi * blo);
+
+  // two_two_diff(s1, s0, t1, t0) -> B
+  _i = s0 - t0;
+  bvirt = s0 - _i;
+  B[0] = s0 - (_i + bvirt) + (bvirt - t0);
+  _j = s1 + _i;
+  bvirt = _j - s1;
+  _0 = s1 - (_j - bvirt) + (_i - bvirt);
+  _i = _0 - t1;
+  bvirt = _0 - _i;
+  B[1] = _0 - (_i + bvirt) + (bvirt - t1);
+  u3 = _j + _i;
+  bvirt = u3 - _j;
+  B[2] = _j - (u3 - bvirt) + (_i - bvirt);
+  B[3] = u3;
+
+  let det = estimate(4, B);
+  let errbound = CCW_ERRBOUND_B * detsum;
+  if (det >= errbound || -det >= errbound)
+    return det;
+
+  // recover the exact tails of the four differences
+  bvirt = ax - acx;
+  acxtail = ax - (acx + bvirt) + (bvirt - cx);
+  bvirt = bx - bcx;
+  bcxtail = bx - (bcx + bvirt) + (bvirt - cx);
+  bvirt = ay - acy;
+  acytail = ay - (acy + bvirt) + (bvirt - cy);
+  bvirt = by - bcy;
+  bcytail = by - (bcy + bvirt) + (bvirt - cy);
+
+  if (acxtail === 0 && acytail === 0 && bcxtail === 0 && bcytail === 0)
+    return det; // the differences were exact, so B is the exact answer
+
+  errbound = CCW_ERRBOUND_C * detsum + RESULT_ERRBOUND * Math.abs(det);
+  det += (acx * bcytail + bcy * acxtail) - (acy * bcxtail + bcx * acytail);
+  if (det >= errbound || -det >= errbound)
+    return det;
+
+  // the full exact determinant, accumulated through the expansions
+  let len = expansionSum(4, B, twoProduct(acxtail, bcy, U), U, C1);
+  len = expansionSum(len, C1, twoProduct(acx, bcytail, U), U, C2);
+  const c1len = len;
+  len = expansionSum(c1len, C2, twoProduct(acytail, bcx, U, true), U, C1);
+  len = expansionSum(len, C1, twoProduct(acy, bcxtail, U, true), U, D);
+  return D[len - 1];
+}
+
+/**
+ * Exact product of two doubles as a two-component expansion, written
+ * into `out`. With `negate` the product's sign is flipped, which is how
+ * the subtracted half of the determinant is folded into a sum.
+ * @returns {number} always 2
+ */
+function twoProduct(a, b, out, negate = false) {
+  const x = a * b;
+  let c = SPLITTER * a;
+  const ahi = c - (c - a);
+  const alo = a - ahi;
+  c = SPLITTER * b;
+  const bhi = c - (c - b);
+  const blo = b - bhi;
+  const y = alo * blo - (x - ahi * bhi - alo * bhi - ahi * blo);
+  out[0] = negate ? -y : y;
+  out[1] = negate ? -x : x;
+  return 2;
+}
+
+/**
+ * The orientation of the triple (a, b, c): **positive** when c lies to
+ * the left of the directed line a->b (counter-clockwise), **negative**
+ * when it lies to the right, and **exactly zero** when the three points
+ * are collinear.
+ *
+ * The sign is always correct. The magnitude is twice the signed area of
+ * the triangle, but only approximately — callers must use this for its
+ * sign, and `ringArea` for a measurement.
+ *
+ * Coordinates are raw numbers rather than vector objects so a GeoJSON
+ * position (`[lon, lat]`) can be passed straight through.
+ *
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} cx
+ * @param {number} cy
+ * @returns {number} positive, negative, or zero
+ * @example
+ * orient2d(0, 0, 1, 0, 0, 1);  // > 0 — (0,1) is left of the x axis
+ * orient2d(0, 0, 1, 0, 0, -1); // < 0
+ * orient2d(0, 0, 2, 2, 1, 1);  // 0 — exactly collinear
+ */
+export function orient2d(ax, ay, bx, by, cx, cy) {
+  // the same two halves the exact stage forms, in the same order: a
+  // mismatch here would make the filter and the fallback disagree about
+  // which direction is counter-clockwise
+  const detleft = (ax - cx) * (by - cy);
+  const detright = (ay - cy) * (bx - cx);
+  const det = detleft - detright;
+
+  // the cheap filter: when the two halves have opposite signs, or one is
+  // zero, the subtraction cannot have destroyed the sign
+  const detsum = detleft > 0
+    ? (detright <= 0 ? det : detleft + detright)
+    : detleft < 0
+      ? (detright >= 0 ? det : -detleft - detright)
+      : det;
+  if (detleft === 0 || detright === 0 || (detleft > 0) !== (detright > 0))
+    return det;
+
+  const errbound = CCW_ERRBOUND_A * detsum;
+  if (det >= errbound || -det >= errbound)
+    return det;
+
+  return orient2dExact(ax, ay, bx, by, cx, cy, detsum);
+}
+
+/**
+ * The same determinant without the exact fallback: fast, and **wrong on
+ * near-collinear input**.
+ *
+ * This exists for the one case where that is acceptable — a bounding
+ * pre-filter whose answer is checked by `orient2d` afterwards. Anything
+ * that decides containment, winding or intersection must use `orient2d`;
+ * a wrong sign there is a wrong answer, not a rounding error.
+ *
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} cx
+ * @param {number} cy
+ * @returns {number}
+ */
+export function orient2dFast(ax, ay, bx, by, cx, cy) {
+  return (ax - cx) * (by - cy) - (ay - cy) * (bx - cx);
+}
+
+//#endregion

package/src/geo/ring.js

@@ -0,0 +1,182 @@
+//@ts-check
+
+//#region Rings, areas and containment
+// A GeoJSON linear ring is an array of at least four positions whose
+// first and last are identical (RFC 7946 section 3.1.6). A Polygon's
+// `coordinates` is an array of rings — exterior first, holes after — so
+// everything here takes plain position arrays and needs no knowledge of
+// the `type` discriminator.
+//
+// The two invariants JSON Schema provably cannot express live here:
+// `isRingClosed` and `ringWinding`. The official GeoJSON schema says so
+// outright, which is why every validator in the ecosystem bolts on code
+// of its own — and unclosed rings and reversed winding (which makes a
+// renderer fill the whole globe instead of the polygon) are among the
+// commonest defects in real data.
+
+import { orient2d } from './predicates.js';
+import { EARTH_RADIUS } from './distance.js';
+import { DEG } from './angle.js';
+
+/**
+ * Whether a ring is closed: its last position repeats its first.
+ *
+ * Compares longitude and latitude only. A position may legally carry a
+ * third element (altitude), and RFC 7946 does not require it to match
+ * for the ring to close.
+ *
+ * @param {Array<number[]>} ring - positions
+ * @returns {boolean}
+ * @example
+ * isRingClosed([[0,0],[1,0],[1,1],[0,0]]); // true
+ * isRingClosed([[0,0],[1,0],[1,1]]);       // false
+ */
+export function isRingClosed(ring) {
+  const n = ring.length;
+  if (n < 2)
+    return false;
+  const first = ring[0];
+  const last = ring[n - 1];
+  return first[0] === last[0] && first[1] === last[1];
+}
+
+/**
+ * Twice the signed planar area of a ring (the shoelace sum), in squared
+ * degrees. **Positive is counter-clockwise.**
+ *
+ * The sign is the useful part and is exact for the purpose: it is a sum
+ * of `orient2d` determinants about the ring's first vertex, so a ring
+ * whose vertices are near-collinear still winds the way this says. The
+ * magnitude is a planar quantity in degree-space and is NOT an area on
+ * the Earth — use `sphericalRingArea` for that.
+ *
+ * @param {Array<number[]>} ring - positions
+ * @returns {number} twice the signed area; positive = counter-clockwise
+ */
+export function ringSignedArea(ring) {
+  const n = ring.length;
+  if (n < 3)
+    return 0;
+  // fan the triangles from vertex 0 so each term is an orientation
+  // determinant rather than a bare cross product
+  const [ox, oy] = ring[0];
+  let sum = 0;
+  for (let i = 1; i < n - 1; i++) {
+    const a = ring[i];
+    const b = ring[i + 1];
+    sum += orient2d(ox, oy, a[0], a[1], b[0], b[1]);
+  }
+  return sum;
+}
+
+/**
+ * The winding direction of a ring: `1` counter-clockwise, `-1`
+ * clockwise, `0` degenerate (zero area).
+ *
+ * RFC 7946 section 3.1.6 requires exterior rings to be counter-clockwise
+ * and holes clockwise — the right-hand rule. Parsers are told to accept
+ * non-conforming data, so this reports rather than rejects.
+ *
+ * @param {Array<number[]>} ring - positions
+ * @returns {number} 1, -1 or 0
+ */
+export function ringWinding(ring) {
+  return Math.sign(ringSignedArea(ring));
+}
+
+/**
+ * Geodesic area of a ring on the sphere, in square metres, always
+ * non-negative.
+ *
+ * Uses the spherical excess of the polygon (the standard formula for a
+ * ring of great-circle edges), so unlike `ringSignedArea` this is a real
+ * measurement. Accurate to the sphere approximation — under half a
+ * percent, the same bound as `haversineDistance`.
+ *
+ * @param {Array<number[]>} ring - positions
+ * @param {number} [radius]
+ * @returns {number} square metres
+ */
+export function sphericalRingArea(ring, radius = EARTH_RADIUS) {
+  const n = ring.length;
+  if (n < 4)
+    return 0; // fewer than 3 distinct positions bounds no area
+  let total = 0;
+  // consecutive edges share a vertex, so its sine is carried forward
+  // rather than recomputed: one transcendental per vertex, not two
+  let sinA = Math.sin(ring[0][1] * DEG);
+  for (let i = 0; i < n - 1; i++) {
+    const a = ring[i];
+    const b = ring[i + 1];
+    const sinB = Math.sin(b[1] * DEG);
+    total += (b[0] - a[0]) * DEG * (2 + sinA + sinB);
+    sinA = sinB;
+  }
+  return Math.abs(total * radius * radius * 0.5);
+}
+
+/**
+ * Whether a position lies inside a ring, by the even-odd (crossing)
+ * rule. A position exactly on an edge or vertex counts as **inside**,
+ * which is the convention that makes adjacent polygons tile without
+ * gaps.
+ *
+ * The ray cast runs in the ring's own coordinate space, so this is a
+ * planar test on longitude/latitude. That is what GeoJSON consumers
+ * mean by containment, and it is correct for any ring that does not
+ * cross the antimeridian — which RFC 7946 tells producers to cut.
+ *
+ * @param {number} x - longitude
+ * @param {number} y - latitude
+ * @param {Array<number[]>} ring - positions
+ * @returns {boolean}
+ */
+export function pointInRing(x, y, ring) {
+  const n = ring.length;
+  if (n < 3)
+    return false;
+  let inside = false;
+  for (let i = 0, j = n - 1; i < n; j = i++) {
+    const xi = ring[i][0];
+    const yi = ring[i][1];
+    const xj = ring[j][0];
+    const yj = ring[j][1];
+    // Two cheap tests decide whether the exact predicate is needed at
+    // all. An edge that neither straddles the ray nor spans the point
+    // can affect neither answer, and on a large ring that is almost
+    // every edge - so the robust orientation runs a handful of times
+    // instead of twice per vertex.
+    const straddles = (yi > y) !== (yj > y);
+    const spans = (xi < x) === (x <= xj) && (yi < y) === (y <= yj);
+    if (!straddles && !spans)
+      continue;
+    const side = orient2d(xi, yi, xj, yj, x, y);
+    // exactly on this edge, and within its extent rather than its line
+    if (side === 0 && spans)
+      return true;
+    // the crossing test itself: is the edge to the right of the point
+    if (straddles && side !== 0 && (side > 0) === (yj > yi))
+      inside = !inside;
+  }
+  return inside;
+}
+
+/**
+ * Whether a position lies inside a polygon: inside its exterior ring and
+ * outside every hole.
+ * @param {number} x - longitude
+ * @param {number} y - latitude
+ * @param {Array<Array<number[]>>} rings - a GeoJSON Polygon's coordinates
+ * @returns {boolean}
+ */
+export function pointInPolygon(x, y, rings) {
+  if (rings.length === 0 || !pointInRing(x, y, rings[0]))
+    return false;
+  for (let i = 1; i < rings.length; i++) {
+    if (pointInRing(x, y, rings[i]))
+      return false; // in a hole
+  }
+  return true;
+}
+
+//#endregion

package/src/geo/simplify.js

@@ -0,0 +1,130 @@
+//@ts-check
+
+//#region Line simplification
+// Real geographic data is drawn at a resolution nobody is looking at. A
+// national boundary from OpenStreetMap carries tens of thousands of
+// vertices; rendered 400 pixels wide, the overwhelming majority land on
+// the same pixel as their neighbour. Emitting them anyway costs path
+// bytes, parse time and paint time for a picture that is byte-identical.
+//
+// Douglas-Peucker is the classic answer and the right one here: it keeps
+// the vertices that carry the shape (every corner, every peninsula) and
+// drops the ones that only fill in a straight run, so what survives is
+// what a reader would have drawn. The tolerance is a distance in the
+// input's own units — feed it projected unit-square coordinates and the
+// tolerance is a fraction of the frame, which is the only unit a
+// renderer can reason about.
+//
+// The implementation is iterative rather than recursive. A degenerate
+// input (a coastline digitized as one long near-straight run) recurses
+// once per vertex, and at OSM scale that overflows the stack — a real
+// failure, not a theoretical one.
+
+/**
+ * Squared distance from a point to a segment. Squared throughout: the
+ * comparison against a tolerance is monotonic in the square, so the
+ * square root would be one transcendental per vertex per level for an
+ * answer nobody reads.
+ */
+function segmentDistanceSq(px, py, ax, ay, bx, by) {
+  let dx = bx - ax;
+  let dy = by - ay;
+  if (dx !== 0 || dy !== 0) {
+    const t = ((px - ax) * dx + (py - ay) * dy) / (dx * dx + dy * dy);
+    if (t > 1) {
+      ax = bx;
+      ay = by;
+    }
+    else if (t > 0) {
+      ax += dx * t;
+      ay += dy * t;
+    }
+  }
+  dx = px - ax;
+  dy = py - ay;
+  return dx * dx + dy * dy;
+}
+
+/**
+ * Simplify a line with the Douglas-Peucker algorithm, keeping every
+ * vertex further than `tolerance` from the line its neighbours describe.
+ *
+ * The first and last positions always survive, so a **ring stays closed**
+ * — simplification can never turn a valid polygon into an invalid one.
+ * Positions are returned by reference, not copied, so any third element
+ * (altitude) rides along untouched.
+ *
+ * @param {Array<number[]>} line - positions
+ * @param {number} tolerance - in the input's own coordinate units
+ * @returns {Array<number[]>} a new array; the input is not modified
+ * @example
+ * simplifyLine([[0,0],[1,0.001],[2,0]], 0.01); // [[0,0],[2,0]]
+ * simplifyLine([[0,0],[1,1],[2,0]], 0.01);     // all three: the corner carries the shape
+ */
+export function simplifyLine(line, tolerance) {
+  const n = line.length;
+  if (n < 3 || !(tolerance > 0))
+    return line.slice();
+
+  const toleranceSq = tolerance * tolerance;
+  const keep = new Uint8Array(n);
+  keep[0] = 1;
+  keep[n - 1] = 1;
+
+  // an explicit stack of [first, last] spans still to examine
+  const stack = [0, n - 1];
+  while (stack.length > 0) {
+    const last = /** @type {number} */(stack.pop());
+    const first = /** @type {number} */(stack.pop());
+    if (last - first < 2)
+      continue;
+    const ax = line[first][0];
+    const ay = line[first][1];
+    const bx = line[last][0];
+    const by = line[last][1];
+    let furthest = -1;
+    let furthestSq = toleranceSq;
+    for (let i = first + 1; i < last; i++) {
+      const d = segmentDistanceSq(line[i][0], line[i][1], ax, ay, bx, by);
+      if (d > furthestSq) {
+        furthestSq = d;
+        furthest = i;
+      }
+    }
+    // nothing in this span strays far enough: the whole run collapses to
+    // its endpoints, and neither half needs looking at
+    if (furthest < 0)
+      continue;
+    keep[furthest] = 1;
+    stack.push(first, furthest, furthest, last);
+  }
+
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    if (keep[i] === 1)
+      out.push(line[i]);
+  }
+  return out;
+}
+
+/**
+ * Simplify a linear ring, refusing to destroy it.
+ *
+ * A ring needs four positions to bound a surface, so when the tolerance
+ * would leave fewer the ring is returned **unsimplified** rather than
+ * degenerate. Dropping a small island entirely is a defensible rendering
+ * choice, but silently emitting a two-vertex "polygon" is not — a caller
+ * wanting the island gone should filter by area first.
+ *
+ * @param {Array<number[]>} ring - positions, first === last
+ * @param {number} tolerance
+ * @returns {Array<number[]>}
+ */
+export function simplifyRing(ring, tolerance) {
+  if (ring.length < 5)
+    return ring.slice();
+  const simplified = simplifyLine(ring, tolerance);
+  return simplified.length >= 4 ? simplified : ring.slice();
+}
+
+//#endregion