@math.gl/geospatial 5.0.0-alpha.8 → 5.0.0-beta.1

package/src/discontinuous/global-polygons.ts

@@ -0,0 +1,273 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original octant atlas and provenance adapter around the existing ISC d3-geo spherical clipper; its license is retained in spherical-clip/D3-GEO-LICENSE.txt.
+import polygonClipping from 'polygon-clipping';
+import clipCircle from './spherical-clip/clip-circle.js';
+import {
+  basis,
+  coordinates,
+  cross,
+  dot,
+  geographic,
+  ringOrientation,
+  unit,
+  validateArc,
+  RAD,
+  type Position,
+  type Vector
+} from './math';
+import type {GeographicPosition, MapPolygon, MapSamplingOptions, MapSurface} from './map-layout';
+
+export type SphericalCutOptions = {
+  /** Filled side of every directed minor-great-circle boundary. Do not infer complements from winding magnitude. */
+  interior: 'left' | 'right';
+  /** Bound input and intermediate emitted vertices; default 65536. */
+  maxVertices?: number;
+  /** Bound adapter vertex visits and source-edge comparisons; default 1000000. */
+  maxWork?: number;
+};
+export type SphericalCutEdge =
+  | {
+      kind: 'source';
+      ringIndex: number;
+      edgeIndex: number;
+      startFraction: number;
+      endFraction: number;
+    }
+  | {kind: 'cut'; axis: 0 | 1 | 2};
+export type SphericalCutPolygon = {
+  /** Stable signed-axis octant identifier. Adjacent cells share their boundary. */
+  cellId: string;
+  /** Outer first, then holes; explicitly closed. All output storage belongs to the caller. */
+  rings: Position[][];
+  /** One record per ring edge; generated atlas edges never pretend to be input edges. */
+  edges: SphericalCutEdge[][];
+};
+const TOL = 2e-12;
+// For nearby unit directions, cross(a,b-a) avoids cancellation between
+// products of order one. Keep physical angular tolerances when forming fractions.
+const arcCross = (a: Vector, b: Vector) => cross(a, [b[0] - a[0], b[1] - a[1], b[2] - a[2]]);
+const angle = (a: Vector, b: Vector) => Math.atan2(Math.hypot(...arcCross(a, b)), dot(a, b));
+
+/** Partition global spherical polygons into an open-hemisphere atlas before map clipping.
+ * Input topology must be valid. This does not reinterpret edges as ellipsoid geodesics/rhumbs.
+ */
+export function cutSphericalPolygon(
+  rings: readonly (readonly GeographicPosition[])[],
+  options: SphericalCutOptions
+): SphericalCutPolygon[] {
+  const maxVertices = options.maxVertices ?? 65536,
+    maxWork = options.maxWork ?? 1000000;
+  if (
+    !['left', 'right'].includes(options.interior) ||
+    !Number.isSafeInteger(maxVertices) ||
+    maxVertices < 3 ||
+    maxVertices > 1000000 ||
+    !Number.isSafeInteger(maxWork) ||
+    maxWork < 1 ||
+    maxWork > 1e8
+  )
+    throw new RangeError('Invalid spherical cut side or limits');
+  let work = 0,
+    emitted = 0;
+  const tick = (n = 1) => {
+    work += n;
+    if (work > maxWork) throw new RangeError('Spherical cut work limit exceeded');
+  };
+  const count = () => {
+    tick();
+    if (++emitted > maxVertices) throw new RangeError('Spherical cut vertex limit exceeded');
+  };
+  const input = rings.map(ring => {
+    if (ring.length > maxVertices) throw new RangeError('Spherical cut vertex limit exceeded');
+    const points = ring.map(p => {
+      count();
+      return geographic(p);
+    });
+    if (points.length > 1 && angle(points[0], points[points.length - 1]) < TOL) points.pop();
+    if (points.length < 3) throw new RangeError('Spherical rings need at least three vertices');
+    points.forEach((p, i) => validateArc(p, points[(i + 1) % points.length]));
+    return points;
+  });
+  if (!input.length) return [];
+  const boundary = (output: Vector[][], normal: Vector): Vector[][] => {
+    const [x, y] = basis(normal),
+      result: Vector[][] = [];
+    let ring: Vector[] = [];
+    const sink = {
+      polygonStart() {},
+      polygonEnd() {},
+      lineStart() {
+        ring = [];
+      },
+      lineEnd() {
+        if (ring.length >= 3) result.push(ring);
+      },
+      point(lon: number, lat: number) {
+        count();
+        const v = geographic([lon / RAD, lat / RAD]);
+        const p: Vector = [0, 1, 2].map(
+          i => normal[i] * v[0] + x[i] * v[1] + y[i] * v[2]
+        ) as Vector;
+        ring.push(unit(p));
+      }
+    };
+    const stream = clipCircle(Math.PI / 3, Math.PI / 90)(sink);
+    stream.polygonStart();
+    for (const r of output) {
+      stream.lineStart();
+      for (const p of r) {
+        tick();
+        const q = coordinates([dot(normal, p), dot(x, p), dot(y, p)]);
+        stream.point(q[0] * RAD, q[1] * RAD);
+      }
+      stream.lineEnd();
+    }
+    stream.polygonEnd();
+    return result;
+  };
+  const source = (a: Vector, b: Vector): SphericalCutEdge => {
+    for (let ringIndex = 0; ringIndex < input.length; ringIndex++) {
+      const ring = input[ringIndex];
+      for (let edgeIndex = 0; edgeIndex < ring.length; edgeIndex++) {
+        tick();
+        const p = ring[edgeIndex],
+          q = ring[(edgeIndex + 1) % ring.length],
+          length = angle(p, q);
+        if (length < TOL) continue;
+        const n = unit(arcCross(p, q));
+        if (Math.abs(dot(n, a)) > TOL || Math.abs(dot(n, b)) > TOL) continue;
+        const at = (v: Vector) => Math.atan2(dot(arcCross(p, v), n), dot(p, v)) / length;
+        const startFraction = at(a),
+          endFraction = at(b);
+        if (
+          Math.min(startFraction, endFraction) >= -TOL / length &&
+          Math.max(startFraction, endFraction) <= 1 + TOL / length
+        )
+          return {
+            kind: 'source',
+            ringIndex,
+            edgeIndex,
+            startFraction: Math.max(0, Math.min(1, startFraction)),
+            endFraction: Math.max(0, Math.min(1, endFraction))
+          };
+      }
+    }
+    for (let axis = 0; axis < 3; axis++)
+      if (Math.abs(a[axis]) < TOL && Math.abs(b[axis]) < TOL)
+        return {kind: 'cut', axis: axis as 0 | 1 | 2};
+    throw new RangeError('Spherical cut edge lost its source or boundary');
+  };
+  const result: SphericalCutPolygon[] = [];
+  for (const sx of [-1, 1])
+    for (const sy of [-1, 1])
+      for (const sz of [-1, 1]) {
+        const center = unit([sx, sy, sz]),
+          [x, y] = basis(center);
+        let clipped = input.map(r =>
+          options.interior === 'left' ? r.slice().reverse() : r.slice()
+        );
+        // A 60-degree cap strictly contains the octant (54.736 degrees at
+        // its vertices). Its two-degree boundary chords remain outside the
+        // octant, so their approximation cannot become an output boundary.
+        clipped = boundary(clipped, center);
+        const outer: Position[][] = [],
+          holes: Position[][] = [];
+        for (const r of clipped) {
+          let planar = r.map(
+            p => [dot(x, p) / dot(center, p), dot(y, p) / dot(center, p)] as Position
+          );
+          // Drop duplicate/collinear clip-boundary vertices before Boolean reconstruction.
+          let changed = true;
+          while (changed && planar.length >= 3) {
+            changed = false;
+            for (let i = 0; i < planar.length; i++) {
+              tick();
+              const a = planar[(i + planar.length - 1) % planar.length],
+                b = planar[i],
+                c = planar[(i + 1) % planar.length];
+              const ab = Math.hypot(b[0] - a[0], b[1] - a[1]),
+                bc = Math.hypot(c[0] - b[0], c[1] - b[1]);
+              const turn = (b[0] - a[0]) * (c[1] - b[1]) - (b[1] - a[1]) * (c[0] - b[0]);
+              if (ab < TOL || bc < TOL || Math.abs(turn) < TOL * ab * bc) {
+                planar.splice(i, 1);
+                changed = true;
+                break;
+              }
+            }
+          }
+          if (planar.length < 3) continue;
+          const orientation = ringOrientation(planar);
+          if (!orientation) continue;
+          planar.reverse();
+          planar.push(planar[0]);
+          (orientation < 0 ? outer : holes).push(planar);
+        }
+        if (!outer.length) continue;
+        const merged =
+          outer.length === 1
+            ? [outer]
+            : polygonClipping.union([outer[0]], ...outer.slice(1).map(r => [r]));
+        const filled = holes.length
+          ? polygonClipping.difference(merged, ...holes.map(r => [r]))
+          : merged;
+        const mask = (
+          [
+            [sx, 0, 0],
+            [0, sy, 0],
+            [0, 0, sz]
+          ] as Vector[]
+        ).map(p => [dot(x, p) / dot(center, p), dot(y, p) / dot(center, p)] as Position);
+        const polygons = polygonClipping.intersection(filled, [mask]);
+        for (const polygon of polygons) {
+          let vectors = polygon.map(r =>
+            r.map(([a, b]) => unit([0, 1, 2].map(i => center[i] + a * x[i] + b * y[i]) as Vector))
+          );
+          // Boolean reconstruction may combine collinear source edges. Restore
+          // original vertices so every retained source interval has one owner.
+          vectors = vectors.map(r => {
+            const out: Vector[] = [r[0]];
+            for (let i = 1; i < r.length; i++) {
+              const a = r[i - 1],
+                b = r[i],
+                length = angle(a, b),
+                candidates: {t: number; p: Vector}[] = [];
+              if (length > TOL) {
+                const n = unit(arcCross(a, b));
+                for (const ring of input)
+                  for (const p of ring) {
+                    tick();
+                    if (Math.abs(dot(n, p)) > TOL) continue;
+                    const t = Math.atan2(dot(arcCross(a, p), n), dot(a, p)) / length;
+                    if (t > TOL && t < 1 - TOL) candidates.push({t, p});
+                  }
+              }
+              candidates.sort((a, b) => a.t - b.t);
+              for (const {p} of candidates) if (angle(out[out.length - 1], p) > TOL) out.push(p);
+              out.push(b);
+            }
+            return out;
+          });
+          for (const r of vectors) for (const _ of r) count();
+          result.push({
+            cellId: `${sx},${sy},${sz}`,
+            rings: vectors.map(r => r.map(coordinates)),
+            edges: vectors.map(r => r.slice(0, -1).map((p, i) => source(p, r[i + 1])))
+          });
+        }
+      }
+  return result;
+}
+
+/** Use existing map-specific lobe, face, cap and placement clipping after atlas partitioning. */
+export function projectSphericalPolygon(
+  map: Pick<MapSurface, 'projectPolygon'>,
+  rings: readonly (readonly GeographicPosition[])[],
+  options: SphericalCutOptions & MapSamplingOptions
+): MapPolygon[] {
+  const result: MapPolygon[] = [];
+  for (const part of cutSphericalPolygon(rings, options))
+    result.push(...map.projectPolygon(part.rings, options));
+  return result;
+}

package/src/discontinuous/gray-fuller.ts

@@ -0,0 +1,38 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+// Robert W. Gray (1995), Exact Transformation Equations for Fuller's World Map.
+// Forward equations also published by Philippe Rivière under CC0 in
+// d3-geo-polygon/src/grayfuller.js. Inverse solves the monotone angle sum.
+import {type Position} from './math';
+const root3 = Math.sqrt(3);
+const height = Math.sqrt((5 + 2 * Math.sqrt(5)) / 15);
+const edge = Math.sqrt(8 / (5 + Math.sqrt(5)));
+const distance = Math.sqrt((3 + Math.sqrt(5)) / (5 + Math.sqrt(5)));
+
+/** Input is gnomonic coordinates in a face frame with a vertex on +y. */
+export function grayFullerForward(x: number, y: number): Position {
+  x *= height;
+  y *= height;
+  const a = Math.atan(((2 * y) / root3 - edge / 6) / distance);
+  const b = Math.atan((x - y / root3 - edge / 6) / distance);
+  const c = Math.atan((-x - y / root3 - edge / 6) / distance);
+  return [root3 * (b - c), 2 * a - b - c];
+}
+export function grayFullerInverse(x: number, y: number): Position | null {
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+  const b = -y / 2 + x / (2 * root3),
+    c = -y / 2 - x / (2 * root3);
+  let low = -Math.PI / 2 - Math.min(0, b, c) + 1e-14;
+  let high = Math.PI / 2 - Math.max(0, b, c) - 1e-14;
+  if (low >= high) return null;
+  for (let i = 0; i < 55; i++) {
+    const t = (low + high) / 2;
+    if (Math.tan(t) + Math.tan(t + b) + Math.tan(t + c) > -edge / (2 * distance)) high = t;
+    else low = t;
+  }
+  const t = (low + high) / 2;
+  const py = ((distance * Math.tan(t) + edge / 6) * root3) / 2;
+  return [(distance * Math.tan(t + b) + py / root3 + edge / 6) / height, py / height];
+}

package/src/discontinuous/gringorten-kernel.ts

@@ -0,0 +1,160 @@
+// math.gl
+// SPDX-License-Identifier: ISC
+// SPDX-FileCopyrightText: Copyright (c) 2013-2021 Mike Bostock
+// Adapted from d3-geo-projection 4.0.0. See D3-LICENSE.txt.
+// math.gl changes: typed boundaries, clamped roundoff, tighter convergence,
+// a bounded relative-precision inverse, and the isotropic face-center limit.
+const {abs, atan2, cos, sin, sign} = Math;
+const sqrt = (x: number) => Math.sqrt(Math.max(0, x));
+const asin = (x: number) => Math.asin(Math.max(-1, Math.min(1, x)));
+const pi = Math.PI,
+  halfPi = pi / 2,
+  epsilon = 1e-12,
+  epsilon2 = 1e-14;
+export function gringortenRaw(lambda: number, phi: number): number[] {
+  // At the face center, asin(cos(lambda) * cos(phi)) loses the angular
+  // distance to rounding. The isotropic equal-area limit has cubic error.
+  const centerScale = Math.sqrt(2 / Math.PI);
+  if (Math.hypot(lambda, phi) < 1e-5) return [centerScale * lambda, centerScale * phi];
+  var sLambda = sign(lambda),
+    sPhi = sign(phi),
+    cosPhi = cos(phi),
+    x = cos(lambda) * cosPhi,
+    y = sin(lambda) * cosPhi,
+    z = sin(sPhi * phi);
+  lambda = abs(atan2(y, z));
+  phi = asin(x);
+  if (abs(lambda - halfPi) > epsilon) lambda %= halfPi;
+  var point = gringortenHexadecant(lambda > pi / 4 ? halfPi - lambda : lambda, phi);
+  if (lambda > pi / 4) (z = point[0]), (point[0] = -point[1]), (point[1] = -z);
+  point[0] *= sLambda;
+  point[1] *= -sPhi;
+  return point;
+}
+
+gringortenRaw.invert = function (x: number, y: number): number[] {
+  const centerScale = Math.sqrt(2 / Math.PI);
+  if (Math.hypot(x, y) < centerScale * 1e-5) return [x / centerScale, y / centerScale];
+  if (abs(x) > 1) x = sign(x) * 2 - x;
+  if (abs(y) > 1) y = sign(y) * 2 - y;
+  var sx = sign(x),
+    sy = sign(y),
+    x0 = -sx * x,
+    y0 = -sy * y,
+    t = y0 / x0 < 1,
+    p = gringortenHexadecantInvert(t ? y0 : x0, t ? x0 : y0),
+    lambda = p[0],
+    phi = p[1],
+    cosPhi = cos(phi);
+  if (t) lambda = -halfPi - lambda;
+  return [sx * (atan2(sin(lambda) * cosPhi, -sin(phi)) + pi), sy * asin(cos(lambda) * cosPhi)];
+};
+
+function gringortenHexadecant(lambda: number, phi: number): number[] {
+  if (phi === halfPi) return [0, 0];
+
+  var sinPhi = sin(phi),
+    r = sinPhi * sinPhi,
+    r2 = r * r,
+    j = 1 + r2,
+    k = 1 + 3 * r2,
+    q = 1 - r2,
+    z = asin(1 / sqrt(j)),
+    v = q + r * j * z,
+    p2 = (1 - sinPhi) / v,
+    p = sqrt(p2),
+    a2 = p2 * j,
+    a = sqrt(a2),
+    h = p * q,
+    x,
+    i;
+
+  if (lambda === 0) return [0, -(h + r * a)];
+
+  var cosPhi = cos(phi),
+    secPhi = 1 / cosPhi,
+    drdPhi = 2 * sinPhi * cosPhi,
+    dvdPhi = (-3 * r + z * k) * drdPhi,
+    dp2dPhi = (-v * cosPhi - (1 - sinPhi) * dvdPhi) / (v * v),
+    dpdPhi = (0.5 * dp2dPhi) / p,
+    dhdPhi = q * dpdPhi - 2 * r * p * drdPhi,
+    dra2dPhi = r * j * dp2dPhi + p2 * k * drdPhi,
+    mu = -secPhi * drdPhi,
+    nu = -secPhi * dra2dPhi,
+    zeta = -2 * secPhi * dhdPhi,
+    lambda1 = (4 * lambda) / pi,
+    delta;
+
+  // Slower but accurate bisection method.
+  if (lambda > 0.222 * pi || (phi < pi / 4 && lambda > 0.175 * pi)) {
+    x = (h + r * sqrt(a2 * (1 + r2) - h * h)) / (1 + r2);
+    if (lambda > pi / 4) return [x, x];
+    var x1 = x,
+      x0 = 0.5 * x;
+    (x = 0.5 * (x0 + x1)), (i = 50);
+    do {
+      var g = sqrt(a2 - x * x),
+        f = x * (zeta + mu * g) + nu * asin(x / a) - lambda1;
+      if (!f) break;
+      if (f < 0) x0 = x;
+      else x1 = x;
+      x = 0.5 * (x0 + x1);
+    } while (abs(x1 - x0) > epsilon && --i > 0);
+  }
+
+  // Newton-Raphson.
+  else {
+    (x = epsilon), (i = 25);
+    do {
+      var x2 = x * x,
+        g2 = sqrt(a2 - x2),
+        zetaMug = zeta + mu * g2,
+        f2 = x * zetaMug + nu * asin(x / a) - lambda1,
+        df = zetaMug + (nu - mu * x2) / g2;
+      x -= delta = g2 ? f2 / df : 0;
+    } while (abs(delta) > epsilon && --i > 0);
+  }
+
+  return [x, -h - r * sqrt(a2 - x * x)];
+}
+
+function gringortenHexadecantInvert(x: number, y: number): number[] {
+  var x0 = 0,
+    x1 = 1,
+    r = 0.5,
+    i = 128;
+
+  while (true) {
+    var r2 = r * r,
+      sinPhi = sqrt(r),
+      z = asin(1 / sqrt(1 + r2)),
+      v = 1 - r2 + r * (1 + r2) * z,
+      p2 = (1 - sinPhi) / v,
+      p = sqrt(p2),
+      a2 = p2 * (1 + r2),
+      h = p * (1 - r2),
+      g2 = a2 - x * x,
+      g = sqrt(g2),
+      y0 = y + h + r * g;
+    if (abs(x1 - x0) < epsilon2 * Math.max(r, 1e-16) || --i === 0 || y0 === 0) break;
+    if (y0 > 0) x0 = r;
+    else x1 = r;
+    r = 0.5 * (x0 + x1);
+  }
+
+  if (!i) return [NaN, NaN];
+
+  var phi = asin(sinPhi),
+    cosPhi = cos(phi),
+    secPhi = 1 / cosPhi,
+    drdPhi = 2 * sinPhi * cosPhi,
+    dvdPhi = (-3 * r + z * (1 + 3 * r2)) * drdPhi,
+    dp2dPhi = (-v * cosPhi - (1 - sinPhi) * dvdPhi) / (v * v),
+    dpdPhi = (0.5 * dp2dPhi) / p,
+    dhdPhi = (1 - r2) * dpdPhi - 2 * r * p * drdPhi,
+    zeta = -2 * secPhi * dhdPhi,
+    mu = -secPhi * drdPhi,
+    nu = -secPhi * (r * (1 + r2) * dp2dPhi + p2 * (1 + 3 * r2) * drdPhi);
+
+  return [(pi / 4) * (x * (zeta + mu * g) + nu * asin(x / sqrt(a2))), phi];
+}

package/src/discontinuous/healpix.ts

@@ -0,0 +1,61 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {DiscontinuousMap, type MapRegion} from './map-layout';
+import {RAD} from './math';
+
+export type HealpixMapOptions = {radius?: number; centralMeridian?: number};
+
+/** Spherical HEALPix (H=4, K=3), in unit-sphere radians times radius.
+ * Independent implementation of the published HEALPix equations:
+ * M. R. Calabretta (2004), https://arxiv.org/abs/astro-ph/0412607.
+ * The latitude-dependent formula lives inside each octant; all clipping
+ * boundaries remain great-circle arcs. This is not the rHEALPix rearrangement.
+ */
+export function createHealpixMap({radius = 1, centralMeridian = 0}: HealpixMapOptions = {}) {
+  if (!Number.isFinite(radius) || radius <= 0 || !Number.isFinite(centralMeridian))
+    throw new Error('Expected a positive finite radius and finite centralMeridian');
+  const quarter = Math.PI / 4;
+  const wrap = (x: number) => ((((x + 180) % 360) + 360) % 360) - 180;
+  centralMeridian = wrap(centralMeridian);
+  const regions: MapRegion[] = [];
+  for (const sign of [1, -1]) {
+    for (let i = 0; i < 4; i++) {
+      const west = -180 + i * 90;
+      const center = west + 45;
+      regions.push({
+        id: `${sign > 0 ? 'north' : 'south'}-${i}`,
+        boundary: [
+          [west, 0],
+          [west + 90, 0],
+          [west + 90, (sign * Math.asin(2 / 3)) / RAD],
+          [center, sign * 90],
+          [west, (sign * Math.asin(2 / 3)) / RAD]
+        ].map(([lon, lat]) => [lon + centralMeridian, lat]),
+        interior: [center + centralMeridian, sign * 45],
+        placement: [radius, 0, 0, radius, 0, 0],
+        project: ([lon, lat]) => {
+          const delta = wrap(lon - centralMeridian - center) * RAD;
+          const sine = Math.sin(lat * RAD);
+          if (Math.abs(sine) <= 2 / 3) return [center * RAD + delta, ((3 * Math.PI) / 8) * sine];
+          const sigma = Math.sqrt(3 * (1 - Math.abs(sine)));
+          return [center * RAD + delta * sigma, Math.sign(lat) * quarter * (2 - sigma)];
+        },
+        unproject: ([x, y]) => {
+          if (Math.abs(y) > 2 * quarter + 1e-10) return null;
+          const relative = x - center * RAD;
+          if (Math.abs(y) <= quarter)
+            return [x / RAD + centralMeridian, Math.asin((y * 8) / (3 * Math.PI)) / RAD];
+          const sigma = Math.max(0, 2 - Math.abs(y) / quarter);
+          if (Math.abs(relative) > quarter * sigma + 1e-10) return null;
+          return [
+            center + centralMeridian + (sigma > 1e-12 ? relative / (sigma * RAD) : 0),
+            (Math.sign(y) * Math.asin(1 - (sigma * sigma) / 3)) / RAD
+          ];
+        }
+      });
+    }
+  }
+  return new DiscontinuousMap(regions);
+}