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

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);
+}

package/src/discontinuous/layout.ts

@@ -0,0 +1,177 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import type {
+  MapSurface,
+  MapBounds,
+  MapPlacement,
+  MapRegionLayout,
+  MapSamplingOptions,
+  GeographicPosition
+} from './map-layout';
+
+type XY = [number, number];
+export type MapLayoutRegion = Readonly<{
+  id: string;
+  label: string;
+  kind: NonNullable<MapRegionLayout['kind']>;
+  parentId?: string;
+  relativeScale?: number;
+  drawOrder: number;
+  placement: MapPlacement;
+  bounds: MapBounds;
+  frame?: MapBounds;
+  /** Sampled geographic coverage boundary in placed map units. */
+  outlines: readonly (readonly GeographicPosition[])[];
+}>;
+export type MapLayout = Readonly<{
+  bounds: MapBounds;
+  /** Back-to-front, stable for equal drawOrder. */
+  regions: readonly MapLayoutRegion[];
+}>;
+export type MapViewportOptions = {
+  width: number;
+  height: number;
+  /** Pixels, uniformly or per side. No independent inset rescaling. */
+  padding?: number | {left?: number; right?: number; top?: number; bottom?: number};
+  /** Default true: screen origin at top left, Y down. False: bottom left, Y up. */
+  flipY?: boolean;
+};
+const boundsOf = (points: readonly GeographicPosition[]): MapBounds => {
+  let left = Infinity,
+    bottom = Infinity,
+    right = -Infinity,
+    top = -Infinity;
+  for (const [x, y] of points) {
+    left = Math.min(left, x);
+    right = Math.max(right, x);
+    bottom = Math.min(bottom, y);
+    top = Math.max(top, y);
+  }
+  return Object.freeze([left, bottom, right, top]) as MapBounds;
+};
+const corners = ([left, bottom, right, top]: MapBounds): XY[] => [
+  [left, bottom],
+  [right, top]
+];
+
+/** Sample actual projected edges, not just region corners. Bounds are approximate
+ * to the supplied angular/chord sampling criteria; callbacks must remain stable.
+ */
+export function getMapLayout(map: MapSurface, options: MapSamplingOptions = {}): MapLayout {
+  const regions = map.regions
+    .map((region): MapLayoutRegion => {
+      const outlines = map
+        .getRegionOutlines(region.id, options)
+        .map(p => Object.freeze(p.map(point => Object.freeze([...point]) as GeographicPosition)));
+      const points: GeographicPosition[] = outlines.flat();
+      const interior = map.projectPoint(region.interior, region.id);
+      if (interior) points.push(interior.position);
+      if (!points.length) throw new Error(`Cannot measure region ${region.id}`);
+      return Object.freeze({
+        id: region.id,
+        label: region.layout?.label ?? region.id,
+        kind: region.layout?.kind ?? 'panel',
+        parentId: region.layout?.parentId,
+        relativeScale: region.layout?.relativeScale,
+        drawOrder: region.layout?.drawOrder ?? 0,
+        placement: region.placement!,
+        bounds: boundsOf(points),
+        frame: region.layout?.frame,
+        outlines: Object.freeze(outlines)
+      });
+    })
+    .sort((a, b) => a.drawOrder - b.drawOrder);
+  return Object.freeze({
+    bounds: boundsOf(
+      regions.flatMap(r => [...corners(r.bounds), ...(r.frame ? corners(r.frame) : [])])
+    ),
+    regions: Object.freeze(regions)
+  });
+}
+
+/** Uniformly fit canonical placement to a viewport. Preserves inset spacing and
+ * scale ratios. Use project/unproject for screen picking and renderer conversion.
+ */
+export function fitMapLayout(layout: MapLayout, options: MapViewportOptions) {
+  const {width, height, padding = 0, flipY = true} = options;
+  const pad =
+    typeof padding === 'number'
+      ? {left: padding, right: padding, top: padding, bottom: padding}
+      : padding;
+  const {left = 0, right = 0, top = 0, bottom = 0} = pad;
+  if (
+    ![width, height].every(v => Number.isFinite(v) && v > 0) ||
+    ![left, right, top, bottom].every(v => Number.isFinite(v) && v >= 0) ||
+    left + right >= width ||
+    top + bottom >= height
+  )
+    throw new Error('Invalid viewport or padding');
+  const [minX, minY, maxX, maxY] = layout.bounds;
+  const spanX = maxX - minX,
+    spanY = maxY - minY;
+  if (
+    !layout.bounds.every(Number.isFinite) ||
+    !Number.isFinite(spanX) ||
+    !Number.isFinite(spanY) ||
+    spanX <= 0 ||
+    spanY <= 0
+  )
+    throw new Error('Layout bounds must have finite positive extents');
+  const scale = Math.min((width - left - right) / spanX, (height - top - bottom) / spanY);
+  const sx = scale,
+    sy = flipY ? -scale : scale;
+  const centerX = minX + spanX / 2,
+    centerY = minY + spanY / 2;
+  const targetX = left + (width - left - right) / 2;
+  const targetY = (flipY ? top : bottom) + (height - top - bottom) / 2;
+  if (!Number.isFinite(scale) || scale <= 0) throw new Error('Viewport scale is not representable');
+  const project = ([x, y]: GeographicPosition): XY => [
+    (x - centerX) * sx + targetX,
+    (y - centerY) * sy + targetY
+  ];
+  const unproject = ([x, y]: GeographicPosition): XY => [
+    (x - targetX) / sx + centerX,
+    (y - targetY) / sy + centerY
+  ];
+  const transformBounds = (b: MapBounds) => boundsOf(corners(b).map(project));
+  return Object.freeze({
+    width,
+    height,
+    scale,
+    flipY,
+    project,
+    unproject,
+    bounds: transformBounds(layout.bounds),
+    regions: Object.freeze(
+      layout.regions.map((r, index) =>
+        Object.freeze({
+          ...r,
+          layer: index,
+          bounds: transformBounds(r.bounds),
+          frame: r.frame ? transformBounds(r.frame) : undefined,
+          outlines: Object.freeze(
+            r.outlines.map(line => Object.freeze(line.map(p => Object.freeze(project(p)))))
+          )
+        })
+      )
+    )
+  });
+}
+
+/** Inverse candidates at a viewport pixel, ordered from the visible top layer.
+ * A renderer can still reject candidates hidden by its own geometry or styling.
+ */
+export function pickMapLayout(
+  map: MapSurface,
+  fitted: ReturnType<typeof fitMapLayout>,
+  pixel: GeographicPosition
+) {
+  const xy = fitted.unproject(pixel);
+  return fitted.regions
+    .slice()
+    .reverse()
+    .flatMap(region =>
+      map.unprojectPoint(xy, region.id).map(point => ({...point, layer: region.layer}))
+    );
+}