@math.gl/geospatial 5.0.0-alpha.2 → 5.0.0-alpha.20

package/src/discontinuous/quincuncial-kernel.ts

@@ -0,0 +1,173 @@
+// math.gl
+// SPDX-License-Identifier: ISC
+// SPDX-FileCopyrightText: Copyright 2013-2021 Mike Bostock
+// Adapted from d3-geo-projection src/{elliptic,guyou}.js.
+// See D3-LICENSE.txt. Kept internal; radians in and unit-radius coordinates out.
+const {abs, atan, atan2, cos, cosh, exp, log, pow, sign, sin, sinh, sqrt, tan, tanh} = Math;
+const asin = (x: number) => Math.asin(Math.max(-1, Math.min(1, x)));
+const pi = Math.PI,
+  halfPi = pi / 2,
+  quarterPi = pi / 4;
+const sqrt2 = Math.SQRT2,
+  epsilon = 1e-12;
+
+// Returns [sn, cn, dn](u + iv|m).
+export function ellipticJi(u: number, v: number, m: number) {
+  var a, b, c;
+  if (!u) {
+    b = ellipticJ(v, 1 - m);
+    return [
+      [0, b[0] / b[1]],
+      [1 / b[1], 0],
+      [b[2] / b[1], 0]
+    ];
+  }
+  a = ellipticJ(u, m);
+  if (!v)
+    return [
+      [a[0], 0],
+      [a[1], 0],
+      [a[2], 0]
+    ];
+  b = ellipticJ(v, 1 - m);
+  c = b[1] * b[1] + m * a[0] * a[0] * b[0] * b[0];
+  return [
+    [(a[0] * b[2]) / c, (a[1] * a[2] * b[0] * b[1]) / c],
+    [(a[1] * b[1]) / c, (-a[0] * a[2] * b[0] * b[2]) / c],
+    [(a[2] * b[1] * b[2]) / c, (-m * a[0] * a[1] * b[0]) / c]
+  ];
+}
+
+// Returns [sn, cn, dn, ph](u|m).
+export function ellipticJ(u: number, m: number) {
+  var ai, b, phi, t, twon;
+  if (m < epsilon) {
+    t = sin(u);
+    b = cos(u);
+    ai = (m * (u - t * b)) / 4;
+    return [t - ai * b, b + ai * t, 1 - (m * t * t) / 2, u - ai];
+  }
+  if (m >= 1 - epsilon) {
+    ai = (1 - m) / 4;
+    b = cosh(u);
+    t = tanh(u);
+    phi = 1 / b;
+    twon = b * sinh(u);
+    return [
+      t + (ai * (twon - u)) / (b * b),
+      phi - ai * t * phi * (twon - u),
+      phi + ai * t * phi * (twon + u),
+      2 * atan(exp(u)) - halfPi + (ai * (twon - u)) / b
+    ];
+  }
+
+  var a = [1, 0, 0, 0, 0, 0, 0, 0, 0],
+    c = [sqrt(m), 0, 0, 0, 0, 0, 0, 0, 0],
+    i = 0;
+  b = sqrt(1 - m);
+  twon = 1;
+
+  while (abs(c[i] / a[i]) > epsilon && i < 8) {
+    ai = a[i++];
+    c[i] = (ai - b) / 2;
+    a[i] = (ai + b) / 2;
+    b = sqrt(ai * b);
+    twon *= 2;
+  }
+
+  phi = twon * a[i] * u;
+  do {
+    b = phi;
+    t = (c[i] * sin(b)) / a[i];
+    phi = (asin(t) + phi) / 2;
+  } while (--i);
+
+  t = cos(phi);
+  return [sin(phi), t, t / cos(phi - b), phi];
+}
+
+// Calculate F(phi+iPsi|m).
+// See Abramowitz and Stegun, 17.4.11.
+export function ellipticFi(phi: number, psi: number, m: number) {
+  if (!psi) return [ellipticF(phi, m), 0];
+  var r = abs(phi),
+    i = abs(psi),
+    sinhPsi = sinh(i);
+  if (r) {
+    var cscPhi = 1 / sin(r),
+      cotPhi2 = 1 / (tan(r) * tan(r)),
+      k = m * sinhPsi * sinhPsi * cscPhi * cscPhi,
+      a = cotPhi2 + 1 - m - k,
+      discriminant = sqrt(a * a + 4 * k * cotPhi2),
+      // Solve directly for (cotLambda2 - cotPhi2) / cotPhi2.
+      // Subtracting cotLambda2 / cotPhi2 - 1 loses the imaginary
+      // component for nearly real arguments (the central meridian).
+      ratio = a >= 0 ? (2 * k) / (discriminant + a) : (discriminant - a) / (2 * cotPhi2),
+      cotLambda2 = cotPhi2 * (1 + ratio);
+    return [
+      ellipticF(atan(1 / sqrt(cotLambda2)), m) * sign(phi),
+      ellipticF(atan(sqrt(ratio / m)), 1 - m) * sign(psi)
+    ];
+  }
+  return [0, ellipticF(atan(sinhPsi), 1 - m) * sign(psi)];
+}
+
+// Calculate F(phi|m) where m = k² = sin²α.
+// See Abramowitz and Stegun, 17.6.7.
+export function ellipticF(phi: number, m: number) {
+  if (!m) return phi;
+  if (m === 1) return log(tan(phi / 2 + quarterPi));
+  var a = 1,
+    b = sqrt(1 - m),
+    c = sqrt(m);
+  for (var i = 0; abs(c) > epsilon; i++) {
+    if (phi % pi) {
+      var dPhi = atan((b * tan(phi)) / a);
+      if (dPhi < 0) dPhi += pi;
+      phi += dPhi + ~~(phi / pi) * pi;
+    } else phi += phi;
+    c = (a + b) / 2;
+    b = sqrt(a * b);
+    a = c;
+    c = (a - b) / 2;
+  }
+  return phi / (pow(2, i) * a);
+}
+
+export function guyouRaw(lambda: number, phi: number) {
+  var k_ = (sqrt2 - 1) / (sqrt2 + 1),
+    k = sqrt(1 - k_ * k_),
+    K = ellipticF(halfPi, k * k),
+    f = -1,
+    psi = log(tan(pi / 4 + abs(phi) / 2)),
+    r = exp(f * psi) / sqrt(k_),
+    at = guyouComplexAtan(r * cos(f * lambda), r * sin(f * lambda)),
+    t = ellipticFi(at[0], at[1], k * k);
+  return [-t[1], (phi >= 0 ? 1 : -1) * (0.5 * K - t[0])];
+}
+
+function guyouComplexAtan(x: number, y: number) {
+  var x2 = x * x,
+    y_1 = y + 1,
+    t = 1 - x2 - y * y;
+  return [
+    0.5 * ((x >= 0 ? halfPi : -halfPi) - atan2(t, 2 * x)),
+    -0.25 * log(t * t + 4 * x2) + 0.5 * log(y_1 * y_1 + x2)
+  ];
+}
+
+function guyouComplexDivide(a: number[], b: number[]) {
+  var denominator = b[0] * b[0] + b[1] * b[1];
+  return [(a[0] * b[0] + a[1] * b[1]) / denominator, (a[1] * b[0] - a[0] * b[1]) / denominator];
+}
+
+guyouRaw.invert = function (x: number, y: number) {
+  var k_ = (sqrt2 - 1) / (sqrt2 + 1),
+    k = sqrt(1 - k_ * k_),
+    K = ellipticF(halfPi, k * k),
+    f = -1,
+    j = ellipticJi(0.5 * K - y, -x, k * k),
+    tn = guyouComplexDivide(j[0], j[1]),
+    lambda = atan2(tn[1], tn[0]) / f;
+  return [lambda, 2 * atan(exp((0.5 / f) * log(k_ * tn[0] * tn[0] + k_ * tn[1] * tn[1]))) - halfPi];
+};

package/src/discontinuous/quincuncial-star.ts

@@ -0,0 +1,328 @@
+// math.gl
+// SPDX-License-Identifier: MIT AND ISC
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright 2013-2021 Mike Bostock
+// SPDX-FileComment: Quincuncial arrangement and Berghaus formula adapted from d3-geo-projection 4.0.0; see D3-LICENSE.txt. Original math.gl chart and boundary handling.
+
+import {DiscontinuousMap, type MapRegion} from './map-layout';
+import {coordinates, geographic, RAD, type Position, type Vector} from './math';
+import {guyouRaw} from './quincuncial-kernel';
+import {gringortenRaw} from './gringorten-kernel';
+
+const PI = Math.PI;
+const HALF_PI = PI / 2;
+const clamp = (x: number) => Math.max(-1, Math.min(1, x));
+const wrap = (x: number) => ((((x + PI) % (2 * PI)) + 2 * PI) % (2 * PI)) - PI;
+
+export type QuincuncialMapOptions = {
+  radius?: number;
+  centralMeridian?: number;
+};
+export type BerghausMapOptions = QuincuncialMapOptions & {lobes?: number};
+export type GingeryMapOptions = BerghausMapOptions & {coreAngle?: number};
+
+/** Charts around the front/back axes. Each triangle is within an open hemisphere;
+ * its projection owns the one-sided limit at cuts and the antipodal vertex.
+ */
+function fan(
+  count: number,
+  start: number,
+  options: QuincuncialMapOptions,
+  projection: (back: boolean, theta: number) => Pick<MapRegion, 'project' | 'unproject'>,
+  seamStart?: number
+) {
+  const radius = options.radius ?? 1;
+  const longitude = options.centralMeridian ?? 0;
+  if (!Number.isFinite(radius) || radius <= 0 || !Number.isFinite(longitude))
+    throw new Error('Expected a positive finite radius and finite centralMeridian');
+  const offset = wrap(longitude * RAD);
+  const rotate = ([lon, lat]: Position, direction: number): Position => [
+    wrap(lon * RAD + offset * direction) / RAD,
+    lat
+  ];
+  const regions: MapRegion[] = [];
+  for (const back of [false, true]) {
+    for (let i = 0; i < count; i++) {
+      const a = start + (i * 2 * PI) / count;
+      const b = start + ((i + 1) * 2 * PI) / count;
+      const theta = (a + b) / 2;
+      const axis: Vector = [back ? -1 : 1, 0, 0];
+      const kernel = projection(back, theta);
+      const boundary: Vector[] = [
+        axis,
+        [0, Math.cos(a), Math.sin(a)],
+        [0, Math.cos(b), Math.sin(b)]
+      ];
+      if (!back && seamStart !== undefined) {
+        const point = (angle: number): Vector => [
+          Math.cos(seamStart),
+          Math.sin(seamStart) * Math.cos(angle),
+          Math.sin(seamStart) * Math.sin(angle)
+        ];
+        boundary.splice(1, 0, point(a));
+        boundary.push(point(b));
+      }
+      regions.push({
+        id: `${back ? 'back' : 'front'}-${i}`,
+        boundary: boundary.map(p => rotate(coordinates(p), 1)),
+        interior: rotate(coordinates([axis[0], Math.cos(theta), Math.sin(theta)]), 1),
+        placement: [radius, 0, 0, radius, 0, 0],
+        project: p => kernel.project(rotate([...p], -1)),
+        unproject: p => {
+          const source = kernel.unproject(p);
+          return source && source.every(Number.isFinite) ? rotate(source, 1) : null;
+        }
+      });
+    }
+  }
+  return new DiscontinuousMap(regions);
+}
+
+/** Peirce quincuncial: central hemisphere and four corner half-squares.
+ * Equatorial aspect centered on centralMeridian, latitude zero; not D3's default rotation.
+ */
+export function createPeirceQuincuncialMap(options: QuincuncialMapOptions = {}) {
+  return squareMap(options, guyouRaw);
+}
+
+/** Equal-area Gringorten quincuncial, in equatorial aspect. */
+export function createGringortenQuincuncialMap(options: QuincuncialMapOptions = {}) {
+  return squareMap(options, gringortenRaw);
+}
+
+/** Conformal Guyou: two joined hemisphere squares centered at ±90° longitude. */
+export function createGuyouMap(options: QuincuncialMapOptions = {}) {
+  return squareMap(
+    {...options, centralMeridian: (options.centralMeridian ?? 0) + 90},
+    guyouRaw,
+    true
+  );
+}
+
+type SquareKernel = ((lambda: number, phi: number) => number[]) & {
+  invert: (x: number, y: number) => number[];
+};
+function squareMap(options: QuincuncialMapOptions, raw: SquareKernel, rectangular = false) {
+  const halfSide = raw(HALF_PI, 0)[0];
+  const distance = 2 * halfSide * Math.SQRT1_2;
+  return fan(4, PI / 4, options, (back, theta) => {
+    const sx = Math.sign(Math.cos(theta) - Math.sin(theta));
+    const sy = Math.sign(Math.cos(theta) + Math.sin(theta));
+    const s = sx === sy ? 1 : -1;
+    return {
+      project: ([lon, lat]) => {
+        let lambda = lon * RAD;
+        if (back) lambda = wrap(lambda - PI);
+        // Region clipping owns this hemisphere. Rotation roundoff must not
+        // select the other complex branch just beyond its ±90° boundary.
+        lambda = Math.max(-HALF_PI, Math.min(HALF_PI, lambda));
+        // The four branch points lie at hemisphere corners. Their finite limit
+        // is known exactly; the elliptic formula otherwise encounters 0 * Infinity.
+        const phi = lat * RAD;
+        const p =
+          Math.abs(Math.abs(lambda) - HALF_PI) < 1e-12 && Math.abs(Math.abs(phi) - PI / 4) < 1e-12
+            ? [Math.sign(lambda) * halfSide, Math.sign(phi) * halfSide]
+            : Math.abs(Math.abs(phi) - HALF_PI) < 1e-12
+              ? [0, Math.sign(phi) * halfSide]
+              : Math.abs(Math.abs(lambda) - HALF_PI) < 1e-12 && Math.abs(phi) < 1e-12
+                ? [Math.sign(lambda) * halfSide, 0]
+                : raw(lambda, phi);
+        if (rectangular) return [p[0] + (back ? -halfSide : halfSide), p[1]];
+        const x = (p[0] - p[1]) * Math.SQRT1_2;
+        const y = (p[0] + p[1]) * Math.SQRT1_2;
+        // Back longitude reverses the local horizontal axis. This chart owns
+        // one corner even when the geographic input is exactly on its cut.
+        return back ? [s * x + sx * distance, s * y + sy * distance] : [x, y];
+      },
+      unproject: ([x0, y0]) => {
+        let x = x0,
+          y = y0;
+        if (back && !rectangular) {
+          x = (x - sx * distance) / s;
+          y = (y - sy * distance) / s;
+        }
+        const u = rectangular ? x - (back ? -halfSide : halfSide) : (x + y) * Math.SQRT1_2,
+          v = rectangular ? y : (y - x) * Math.SQRT1_2;
+        if (Math.abs(u) > halfSide + 1e-9 || Math.abs(v) > halfSide + 1e-9) return null;
+        if (Math.abs(Math.abs(u) - halfSide) < 1e-12 && Math.abs(Math.abs(v) - halfSide) < 1e-12)
+          return [wrap(Math.sign(u) * HALF_PI + (back ? PI : 0)) / RAD, Math.sign(v) * 45];
+        // The square perimeter is the hemisphere boundary. The complex
+        // elliptic inverse is ill-conditioned there; solve its monotone
+        // one-dimensional forward limit instead of choosing a complex branch.
+        const vertical = Math.abs(Math.abs(u) - halfSide) < 1e-12;
+        const horizontal = Math.abs(Math.abs(v) - halfSide) < 1e-12;
+        if (vertical || horizontal) {
+          let low = vertical ? 0 : PI / 4;
+          let high = vertical ? PI / 4 : HALF_PI;
+          for (let i = 0; i < 55; i++) {
+            const phi = (low + high) / 2;
+            const q = raw(HALF_PI, phi);
+            if (vertical ? q[1] < Math.abs(v) : q[0] > Math.abs(u)) low = phi;
+            else high = phi;
+          }
+          return [
+            wrap(Math.sign(u) * HALF_PI + (back ? PI : 0)) / RAD,
+            (Math.sign(v) * (low + high)) / (2 * RAD)
+          ];
+        }
+        // Forward Guyou is odd in each coordinate. Invert the first quadrant
+        // and reflect explicitly: the elliptic inverse can select another
+        // boundary branch when its complex cosine approaches zero.
+        const p = raw.invert(Math.abs(u), Math.abs(v));
+        return [wrap(Math.sign(u) * p[0] + (back ? PI : 0)) / RAD, (Math.sign(v) * p[1]) / RAD];
+      }
+    };
+  });
+}
+
+/** Berghaus star: azimuthal-equidistant front hemisphere and interrupted back lobes.
+ * Formula follows Berghaus as documented by d3-geo-projection (ISC).
+ */
+export function createBerghausMap(options: BerghausMapOptions = {}) {
+  const lobes = options.lobes ?? 5;
+  if (!Number.isInteger(lobes) || lobes < 3 || lobes > 24)
+    throw new Error('Berghaus lobes must be an integer from 3 to 24');
+  const half = PI / lobes;
+  const bend = (r: number, delta: number) => {
+    const alpha = Math.atan2(Math.sin(delta), 2 - Math.cos(delta));
+    return Math.asin(clamp((PI / r) * Math.sin(alpha))) - alpha;
+  };
+  return fan(lobes, HALF_PI - half, options, (back, theta) => ({
+    project: position => {
+      const [x, y, z] = geographic(position);
+      const r = Math.acos(clamp(x));
+      let angle = Math.atan2(z, y);
+      if (back) angle = theta + bend(r, wrap(angle - theta));
+      if (r > PI - 1e-12) angle = theta;
+      return [r * Math.cos(angle), r * Math.sin(angle)];
+    },
+    unproject: ([x, y]) => {
+      const r = Math.hypot(x, y);
+      if (r > PI + 1e-10 || (back ? r < HALF_PI - 1e-10 : r > HALF_PI + 1e-10)) return null;
+      let angle = Math.atan2(y, x);
+      if (back) {
+        if (r > PI - 1e-10) return [180, 0];
+        const beta = wrap(angle - theta);
+        if (Math.abs(beta) > bend(r, half) + 1e-10) return null;
+        let low = -half,
+          high = half;
+        for (let i = 0; i < 55; i++) {
+          const delta = (low + high) / 2;
+          if (bend(r, delta) < beta) low = delta;
+          else high = delta;
+        }
+        angle = theta + (low + high) / 2;
+      }
+      return coordinates([
+        Math.cos(r),
+        Math.sin(r) * Math.cos(angle),
+        Math.sin(r) * Math.sin(angle)
+      ]);
+    }
+  }));
+}
+
+/** Gingery star, equatorial aspect. coreAngle is the uncut central cap in degrees.
+ * Arc-length construction adapted from d3-geo-projection 4.0.0 gingery.js (ISC).
+ * Chart-owned lobe selection and bracketed inverses are math.gl additions.
+ */
+export function createGingeryMap(options: GingeryMapOptions = {}) {
+  const lobes = options.lobes ?? 6;
+  const coreAngle = options.coreAngle ?? 30;
+  if (!Number.isInteger(lobes) || lobes < 3 || lobes > 24)
+    throw new Error('Gingery lobes must be an integer from 3 to 24');
+  if (!Number.isFinite(coreAngle) || coreAngle <= 0 || coreAngle >= 90)
+    throw new Error('Gingery coreAngle must be greater than 0 and less than 90 degrees');
+  const rho = coreAngle * RAD;
+  const half = PI / lobes;
+  // Gauss-Legendre integration on each smooth side of the curve's kink. A
+  // trapezoidal grid spanning the kink jumps when a node crosses it, preventing
+  // forward/inverse convergence for large central caps. All solves are bounded.
+  const nodes = [
+    0.09501250983763744, 0.2816035507792589, 0.4580167776572274, 0.6178762444026438,
+    0.755404408355003, 0.8656312023878318, 0.9445750230732326, 0.9894009349916499
+  ];
+  const weights = [
+    0.1894506104550685, 0.1826034150449236, 0.16915651939500254, 0.14959598881657673,
+    0.12462897125553387, 0.09515851168249278, 0.06225352393864789, 0.027152459411754095
+  ];
+  const shape = (alpha: number) => {
+    const start = rho * Math.cos(alpha);
+    const k = (rho * Math.sin(alpha) - alpha * Math.sin(start)) / (HALF_PI - start);
+    const height = (x: number) => alpha * Math.sin(x) - (x < HALF_PI ? k * (x - HALF_PI) : 0);
+    const speed = (x: number) => Math.hypot(1, alpha * Math.cos(x) - (x < HALF_PI ? k : 0));
+    const segment = (a: number, b: number) => {
+      const middle = (a + b) / 2,
+        half = (b - a) / 2;
+      let sum = 0;
+      for (let i = 0; i < nodes.length; i++)
+        sum += weights[i] * (speed(middle - half * nodes[i]) + speed(middle + half * nodes[i]));
+      return sum * half;
+    };
+    const integral = (end: number) =>
+      end <= HALF_PI ? segment(start, end) : segment(start, HALF_PI) + segment(HALF_PI, end);
+    return {start, height, speed, integral};
+  };
+  return fan(
+    lobes,
+    -half,
+    options,
+    (_back, theta) => ({
+      project: position => {
+        const [vx, vy, vz] = geographic(position);
+        const r = Math.acos(clamp(vx));
+        const angle = Math.atan2(vz, vy);
+        if (r <= rho) return [r * Math.cos(angle), r * Math.sin(angle)];
+        if (r >= PI - 1e-12) return [PI * Math.cos(theta), PI * Math.sin(theta)];
+        const alpha = Math.max(-half, Math.min(half, wrap(angle - theta)));
+        const curve = shape(alpha);
+        const factor = (PI - rho) / curve.integral(PI);
+        let low = curve.start,
+          high = PI,
+          x = r;
+        for (let i = 0; i < 30; i++) {
+          const error = rho + curve.integral(x) * factor - r;
+          if (Math.abs(error) < 1e-12) break;
+          if (error < 0) low = x;
+          else high = x;
+          const next = x - error / (curve.speed(x) * factor);
+          x = next > low && next < high ? next : (low + high) / 2;
+        }
+        const y = curve.height(x);
+        return [
+          x * Math.cos(theta) - y * Math.sin(theta),
+          x * Math.sin(theta) + y * Math.cos(theta)
+        ];
+      },
+      unproject: ([px, py]) => {
+        let r = Math.hypot(px, py),
+          angle = Math.atan2(py, px);
+        if (r > rho + 1e-12) {
+          const x = px * Math.cos(theta) + py * Math.sin(theta);
+          const y = -px * Math.sin(theta) + py * Math.cos(theta);
+          if (x > PI + 1e-10 || x < rho * Math.cos(half) - 1e-10) return null;
+          if (x >= PI - 1e-12) return Math.abs(y) < 1e-10 ? [180, 0] : null;
+          if (Math.abs(y) > shape(half).height(x) + 1e-10) return null;
+          let low = -half,
+            high = half;
+          for (let i = 0; i < 45; i++) {
+            const alpha = (low + high) / 2;
+            if (shape(alpha).height(x) < y) low = alpha;
+            else high = alpha;
+          }
+          const alpha = (low + high) / 2;
+          const curve = shape(alpha);
+          r = rho + (curve.integral(x) * (PI - rho)) / curve.integral(PI);
+          if (r < rho - 1e-9 || r > PI + 1e-9) return null;
+          angle = theta + alpha;
+        }
+        return coordinates([
+          Math.cos(r),
+          Math.sin(r) * Math.cos(angle),
+          Math.sin(r) * Math.sin(angle)
+        ]);
+      }
+    }),
+    rho
+  );
+}