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

package/src/discontinuous/regional-map.ts

@@ -0,0 +1,228 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import {CapMap} from './cap-map';
+import {sphericalRotation} from './rotated-map';
+import {createHammerRetroazimuthalMap} from './retroazimuthal-map';
+import {armadilloRaw} from './world-kernels/armadillo.js';
+import {createKernelMap} from './world-map';
+import {airyRaw} from './world-kernels/airy.js';
+import {craigRaw} from './world-kernels/craig.js';
+import {littrowRaw} from './world-kernels/littrow.js';
+import {satelliteRaw} from './world-kernels/satellite.js';
+import {modifiedStereographicRaw, coefficients} from './world-kernels/modifiedStereographic.js';
+import {chamberlinRaw} from './world-kernels/chamberlin.js';
+import {twoPointEquidistantRaw} from './world-kernels/twoPointEquidistant.js';
+import {wiechelRaw} from './world-kernels/wiechel.js';
+import {geographic, coordinates, add, unit, cross, dot, angle, RAD, type Vector} from './math';
+import type {WorldKernel} from './world-kernels';
+export const REGIONAL_PROJECTIONS = Object.freeze([
+  'hammer-retroazimuthal',
+  'armadillo',
+  'airy',
+  'craig',
+  'littrow',
+  'satellite',
+  'modified-stereographic-alaska',
+  'modified-stereographic-gs48',
+  'modified-stereographic-gs50',
+  'modified-stereographic-miller',
+  'modified-stereographic-lee',
+  'chamberlin-africa',
+  'two-point-azimuthal-usa',
+  'two-point-equidistant-usa',
+  'wiechel'
+] as const);
+export type RegionalProjection =
+  | (typeof REGIONAL_PROJECTIONS)[number]
+  | 'modified-stereographic'
+  | 'chamberlin'
+  | 'two-point-azimuthal'
+  | 'two-point-equidistant';
+export type RegionalMapOptions = {
+  projection: RegionalProjection;
+  /** Geographic cap center. Named control-point presets retain their own frame. */
+  center?: readonly [number, number];
+  radius?: number;
+  /** Airy beta in degrees (D3's radius accessor); unrelated to output radius. */
+  beta?: number;
+  parallel?: number;
+  distance?: number;
+  tilt?: number;
+  coefficients?: readonly (readonly [number, number])[];
+  controlPoints?: readonly (readonly [number, number])[];
+};
+/** Regional formulas with spherical visibility clipping. */
+export function createRegionalMap(options: RegionalMapOptions) {
+  const {projection, radius = 1} = options;
+  if (!Number.isFinite(radius) || radius <= 0) throw new Error('Expected positive finite radius');
+  if (projection === 'hammer-retroazimuthal') {
+    if (
+      Object.keys(options).some(key => !['projection', 'radius', 'type', 'parallel'].includes(key))
+    )
+      throw new Error('Unsupported Hammer retroazimuthal option');
+    return createHammerRetroazimuthalMap({radius, parallel: options.parallel});
+  }
+  if (projection === 'armadillo') {
+    if (
+      Object.keys(options).some(key => !['projection', 'radius', 'type', 'parallel'].includes(key))
+    )
+      throw new Error('Unsupported Armadillo option');
+    const parallel = options.parallel ?? 20;
+    if (!Number.isFinite(parallel) || parallel <= 0 || parallel >= 90)
+      throw new Error('Armadillo parallel must be between 0 and 90');
+    const rotation = sphericalRotation([0, -parallel]);
+    const base = createKernelMap({kernel: armadilloRaw(parallel * RAD), radius});
+    return new CapMap(
+      [...base.regions],
+      p => {
+        // Keep both signed seam edges: folding +180 onto -180 breaks clipping.
+        let longitude = p[0] % 360;
+        if (longitude > 180) longitude -= 360;
+        if (longitude < -180) longitude += 360;
+        return rotation.local([longitude / 2, p[1]]);
+      },
+      p => {
+        const q = rotation.source(p);
+        return Math.abs(q[0]) > 90 + 1e-7
+          ? [Math.sign(q[0]) * 180, 0]
+          : [Math.max(-90, Math.min(90, q[0])) * 2, q[1]];
+      },
+      Math.PI / 2,
+      radius,
+      true,
+      true
+    );
+  }
+  const allowed: Record<string, string[]> = {
+    airy: ['beta', 'center'],
+    craig: ['parallel', 'center'],
+    littrow: ['center'],
+    satellite: ['distance', 'tilt', 'center'],
+    'modified-stereographic': ['coefficients', 'center'],
+    chamberlin: ['controlPoints'],
+    'two-point-azimuthal': ['controlPoints'],
+    'two-point-equidistant': ['controlPoints']
+  };
+  for (const key of Object.keys(options))
+    if (!['projection', 'radius', 'type'].includes(key) && !allowed[projection]?.includes(key))
+      throw new Error(`Unsupported ${projection} option: ${key}`);
+  const value = (
+    key: 'beta' | 'parallel' | 'distance' | 'tilt',
+    fallback: number,
+    low: number,
+    high: number
+  ) => {
+    const n = options[key] ?? fallback;
+    if (!Number.isFinite(n) || n <= low || n >= high)
+      throw new Error(`Invalid ${projection} ${key}`);
+    return n;
+  };
+  let kernel: WorldKernel,
+    clipAngle = 90,
+    aspect: [number, number, number?] = [0, 0],
+    frame: [Vector, Vector, Vector] | undefined;
+  if (options.center) {
+    geographic(options.center);
+    aspect = [-options.center[0], -options.center[1]];
+  }
+  if (projection === 'airy') {
+    kernel = airyRaw(value('beta', 90, 0, 180) * RAD);
+    clipAngle = 147;
+  } else if (projection === 'craig') kernel = craigRaw(value('parallel', 0, -90, 90) * RAD);
+  else if (projection === 'littrow') {
+    kernel = littrowRaw;
+    clipAngle = 89.999;
+  } else if (projection === 'satellite') {
+    const distance = value('distance', 2, 1, Infinity),
+      tilt = value('tilt', 0, -90, 90) * RAD;
+    // A tilted perspective must not put the horizon on the camera plane.
+    const horizon = Math.acos(1 / distance);
+    if (Math.abs(tilt) >= Math.PI / 2 - horizon)
+      throw new Error('Satellite tilt crosses the horizon');
+    kernel = satelliteRaw(distance, tilt);
+    clipAngle = horizon / RAD - 1e-6;
+  } else if (projection.startsWith('modified-stereographic')) {
+    const key = projection.slice('modified-stereographic-'.length) as keyof typeof coefficients;
+    const presets = {
+      alaska: {center: [-152, 64], clip: 30},
+      gs48: {center: [-95, 38], clip: 55},
+      gs50: {center: [-120, 45], clip: 55},
+      miller: {center: [20, 18], clip: 82},
+      lee: {center: [-165, -10], clip: 130}
+    };
+    const preset = presets[key];
+    const c = projection === 'modified-stereographic' ? options.coefficients : coefficients[key];
+    if (!c?.length || c.length > 32 || !c.every(p => p.length === 2 && p.every(Number.isFinite)))
+      throw new Error('Expected finite complex coefficients');
+    if (preset) {
+      aspect = [-preset.center[0], -preset.center[1]];
+      clipAngle = preset.clip;
+    }
+    kernel = modifiedStereographicRaw(c.map(p => [...p]));
+  } else if (projection === 'chamberlin' || projection === 'chamberlin-africa') {
+    const points =
+      projection === 'chamberlin-africa'
+        ? [
+            [0, 22],
+            [45, 22],
+            [22.5, -22]
+          ]
+        : options.controlPoints;
+    if (points?.length !== 3) throw new Error('Chamberlin requires three control points');
+    const v = points.map(geographic),
+      c = unit(add(add(v[0], v[1]), v[2]));
+    const origin = coordinates(c),
+      east: Vector = [-Math.sin(origin[0] * RAD), Math.cos(origin[0] * RAD), 0];
+    frame = [c, east, cross(c, east)];
+    if (Math.abs(dot(cross(v[0], v[1]), v[2])) < 1e-8)
+      throw new Error('Degenerate Chamberlin control points');
+    const p = v.map(v =>
+      coordinates([dot(v, frame![0]), dot(v, frame![1]), dot(v, frame![2])]).map(n => n * RAD)
+    );
+    kernel = chamberlinRaw(p[0], p[1], p[2]);
+  } else if (projection.startsWith('two-point-')) {
+    if (
+      ![
+        'two-point-azimuthal',
+        'two-point-equidistant',
+        'two-point-azimuthal-usa',
+        'two-point-equidistant-usa'
+      ].includes(projection)
+    )
+      throw new Error('Unknown regional projection');
+    const usa = projection.endsWith('-usa'),
+      points = usa
+        ? [
+            [-158, 21.5],
+            [-77, 39]
+          ]
+        : options.controlPoints;
+    if (points?.length !== 2) throw new Error('Two-point projection requires two control points');
+    const [a, b] = points.map(geographic),
+      distance = angle(a, b);
+    if (distance < 1e-8 || Math.PI - distance < 1e-8)
+      throw new Error('Distinct non-antipodal control points required');
+    const c = unit(add(a, b)),
+      east = unit([b[0] - a[0], b[1] - a[1], b[2] - a[2]]);
+    frame = [c, east, cross(c, east)];
+    const azimuthal = projection.includes('azimuthal');
+    if (azimuthal) {
+      const factor = Math.cos(distance / 2);
+      kernel = (lambda, phi) => [Math.tan(lambda) * factor, Math.tan(phi) / Math.cos(lambda)];
+      kernel.invert = (x, y) => {
+        const lambda = Math.atan(x / factor);
+        return [lambda, Math.atan(y * Math.cos(lambda))];
+      };
+      clipAngle = usa ? 60 : 89.999;
+    } else {
+      kernel = twoPointEquidistantRaw(distance / 2);
+      clipAngle = usa ? 130 : 90;
+    }
+  } else if (projection === 'wiechel') {
+    kernel = wiechelRaw;
+    aspect = [0, -90, 45];
+    clipAngle = 179.999;
+  } else throw new Error('Unknown regional projection');
+  return createKernelMap({kernel, radius, aspect, frame, clipAngle});
+}

package/src/discontinuous/retroazimuthal-map.ts

@@ -0,0 +1,52 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import {CapMap} from './cap-map';
+import {createKernelMap} from './world-map';
+import {sphericalRotation} from './rotated-map';
+import {hammerRetroazimuthalRaw} from './world-kernels/hammerRetroazimuthal.js';
+import {geographic, coordinates, RAD, type Position} from './math';
+import type {WorldKernel} from './world-kernels';
+export function createHammerRetroazimuthalMap({radius = 1, parallel = 45} = {}) {
+  if (!Number.isFinite(parallel) || Math.abs(parallel) >= 90)
+    throw new Error('Expected parallel strictly between -90 and 90');
+  const rotation = sphericalRotation([0, -parallel]),
+    raw = hammerRetroazimuthalRaw(parallel * RAD),
+    cap = 179.999 * RAD;
+  const kernel: WorldKernel = (lambda, phi) => {
+    let q = rotation.local([lambda / RAD, phi / RAD]);
+    const [x, y, z] = geographic(q),
+      theta = Math.acos(Math.max(-1, Math.min(1, x)));
+    let taper = 1;
+    if (theta > cap) {
+      const n = Math.hypot(y, z);
+      if (n < 1e-14) return [0, 0];
+      q = coordinates([Math.cos(cap), (Math.sin(cap) * y) / n, (Math.sin(cap) * z) / n]);
+      taper = (Math.PI - theta) / (Math.PI - cap);
+    }
+    const p = raw(q[0] * RAD, q[1] * RAD);
+    return [p[0] * taper, p[1] * taper];
+  };
+  kernel.invert = (x, y) => {
+    const q = raw.invert(x, y);
+    if (!q?.every(Number.isFinite)) return null;
+    const source = rotation.source([q[0] / RAD, q[1] / RAD]);
+    if (x) source[0] = Math.sign(x) * Math.abs(source[0]);
+    return source.map(v => v * RAD);
+  };
+  const base = createKernelMap({kernel, radius});
+  const regions = base.regions.map(r => ({
+    ...r,
+    project: (p: readonly number[]): Position => {
+      let lon = p[0];
+      if (Math.abs(Math.abs(lon) - 90) < 1e-9)
+        lon = Math.sign(lon) * (90 + (Math.abs(r.interior[0]) > 90 ? 1e-10 : -1e-10));
+      return kernel(lon * RAD, p[1] * RAD) as Position;
+    },
+    unproject: (p: readonly number[]): Position | null => {
+      const q = kernel.invert!(p[0], p[1]);
+      return q?.every(Number.isFinite) ? [q[0] / RAD, q[1] / RAD] : null;
+    }
+  }));
+  return new CapMap(regions, rotation.local, rotation.source, cap, radius);
+}

package/src/discontinuous/rotated-map.ts

@@ -0,0 +1,86 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import {DiscontinuousMap, type GeographicPosition, type MapSamplingOptions} from './map-layout';
+import {geographic, coordinates, RAD, type Position, type Vector} from './math';
+export function sphericalRotation([yaw, pitch, roll = 0]: readonly number[]) {
+  const rotate = (v: Vector, axis: number, a: number): Vector => {
+    const result = [...v] as Vector,
+      i = (axis + 1) % 3,
+      j = (axis + 2) % 3,
+      c = Math.cos(a),
+      s = Math.sin(a);
+    result[i] = c * v[i] - s * v[j];
+    result[j] = s * v[i] + c * v[j];
+    return result;
+  };
+  return {
+    local: (p: GeographicPosition): Position =>
+      coordinates(
+        rotate(rotate(rotate(geographic(p), 2, yaw * RAD), 1, -pitch * RAD), 0, roll * RAD)
+      ),
+    source: (p: GeographicPosition): Position =>
+      coordinates(
+        rotate(rotate(rotate(geographic(p), 0, -roll * RAD), 1, pitch * RAD), 2, -yaw * RAD)
+      )
+  };
+}
+/** Rotate a preset's geographic chart system without changing its planar net. */
+export class RotatedMap extends DiscontinuousMap {
+  private readonly rotation: ReturnType<typeof sphericalRotation>;
+  constructor(
+    private readonly base: DiscontinuousMap,
+    angles: readonly number[]
+  ) {
+    const rotation = sphericalRotation(angles);
+    super(
+      base.regions.map(r => ({
+        ...r,
+        boundary: r.boundary.map(rotation.source),
+        interior: rotation.source(r.interior),
+        project: p => r.project(rotation.local(p)),
+        unproject: p => {
+          const q = r.unproject(p);
+          return q ? rotation.source(q) : null;
+        }
+      }))
+    );
+    this.rotation = rotation;
+  }
+  override containsConvexPolygon(ring: readonly GeographicPosition[], id: string) {
+    return this.base.containsConvexPolygon(ring.map(this.rotation.local), id);
+  }
+  override findRegions(p: GeographicPosition) {
+    return this.base.findRegions(this.rotation.local(p));
+  }
+  override projectPoint(p: GeographicPosition, id?: string) {
+    return this.base.projectPoint(this.rotation.local(p), id);
+  }
+  override unprojectPoint(p: GeographicPosition, id?: string) {
+    return this.base
+      .unprojectPoint(p, id)
+      .map(q => ({...q, position: this.rotation.source(q.position)}));
+  }
+  override projectLine(line: readonly GeographicPosition[], options?: MapSamplingOptions) {
+    return this.base
+      .projectLine(line.map(this.rotation.local), options)
+      .map(p => ({...p, sourceCoordinates: p.sourceCoordinates.map(this.rotation.source)}));
+  }
+  override projectPolygon(
+    rings: readonly (readonly GeographicPosition[])[],
+    options?: MapSamplingOptions
+  ) {
+    return this.base
+      .projectPolygon(
+        rings.map(r => r.map(this.rotation.local)),
+        options
+      )
+      .map(p => ({
+        ...p,
+        sourceCoordinates: p.sourceCoordinates.map(r => r.map(this.rotation.source))
+      }));
+  }
+  override getRegionOutlines(id: string, options?: MapSamplingOptions) {
+    return this.base.getRegionOutlines(id, options);
+  }
+}

package/src/discontinuous/snyder-mesh.ts

@@ -0,0 +1,88 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) PROJ contributors, Felix Palmer
+
+// Polyhedron coordinates and Snyder net tables follow PROJ (Felix Palmer).
+// PROJ revision 5fa31c29f0a806568ed7bc76c1a557604db4a804.
+// See PROJ-LICENSE.txt. Projection math is implemented independently.
+export const icosahedron = {
+  vertices: [
+    [0.0, 0.0, 1.0],
+    [-0.8944271909999159, 0.0, 0.4472135954999579],
+    [-0.27639320225002106, -0.8506508083520399, 0.4472135954999579],
+    [0.7236067977499789, -0.5257311121191336, 0.4472135954999579],
+    [0.7236067977499789, 0.5257311121191336, 0.4472135954999579],
+    [-0.27639320225002106, 0.8506508083520399, 0.4472135954999579],
+    [-0.7236067977499789, -0.5257311121191336, -0.4472135954999579],
+    [0.27639320225002106, -0.8506508083520399, -0.4472135954999579],
+    [0.8944271909999159, 0.0, -0.4472135954999579],
+    [0.27639320225002106, 0.8506508083520399, -0.4472135954999579],
+    [-0.7236067977499789, 0.5257311121191336, -0.4472135954999579],
+    [0.0, 0.0, -1.0]
+  ],
+  faces: [
+    [0, 1, 2],
+    [0, 2, 3],
+    [0, 3, 4],
+    [0, 4, 5],
+    [0, 5, 1],
+    [1, 6, 2],
+    [2, 7, 3],
+    [3, 8, 4],
+    [4, 9, 5],
+    [5, 10, 1],
+    [6, 7, 2],
+    [7, 8, 3],
+    [8, 9, 4],
+    [9, 10, 5],
+    [10, 6, 1],
+    [11, 7, 6],
+    [11, 8, 7],
+    [11, 9, 8],
+    [11, 10, 9],
+    [11, 6, 10]
+  ]
+};
+export const dodecahedron = {
+  vertices: [
+    [0.0, 0.0, 1.0],
+    [0.6666666666666666, 0.0, 0.7453559924999299],
+    [0.7453559924999299, 0.5773502691896258, 0.3333333333333333],
+    [0.12732200375003502, 0.9341723589627159, 0.3333333333333333],
+    [-0.3333333333333333, 0.5773502691896258, 0.7453559924999299],
+    [-0.3333333333333333, -0.5773502691896258, 0.7453559924999299],
+    [0.7453559924999299, -0.5773502691896258, 0.3333333333333333],
+    [0.872677996249965, 0.35682208977309, -0.3333333333333333],
+    [-0.12732200375003502, 0.9341723589627159, -0.3333333333333333],
+    [-0.872677996249965, 0.35682208977309, 0.3333333333333333],
+    [0.12732200375003502, -0.9341723589627159, 0.3333333333333333],
+    [0.872677996249965, -0.35682208977309, -0.3333333333333333],
+    [0.3333333333333333, 0.5773502691896258, -0.7453559924999299],
+    [-0.7453559924999299, 0.5773502691896258, -0.3333333333333333],
+    [-0.872677996249965, -0.35682208977309, 0.3333333333333333],
+    [-0.12732200375003502, -0.9341723589627159, -0.3333333333333333],
+    [0.3333333333333333, -0.5773502691896258, -0.7453559924999299],
+    [0.0, 0.0, -1.0],
+    [-0.6666666666666666, 0.0, -0.7453559924999299],
+    [-0.7453559924999299, -0.5773502691896258, -0.3333333333333333]
+  ],
+  faces: [
+    [0, 1, 2, 3, 4],
+    [3, 8, 13, 9, 4],
+    [0, 4, 9, 14, 5],
+    [0, 5, 10, 6, 1],
+    [1, 6, 11, 7, 2],
+    [2, 7, 12, 8, 3],
+    [9, 13, 18, 19, 14],
+    [5, 14, 19, 15, 10],
+    [6, 10, 15, 16, 11],
+    [7, 11, 16, 17, 12],
+    [8, 12, 17, 18, 13],
+    [15, 19, 18, 17, 16]
+  ]
+};
+export const iseaParents = [
+  6, 7, 8, 9, 10, 11, 12, 0, 13, 14, 7, 8, 8, 9, 10, 11, 12, 13, 14, 15
+].map(i => i - 1);
+export const dseaParents = [4, 7, 8, 0, 9, 10, 3, 4, 4, 5, 6, 9].map(i => i - 1);

package/src/discontinuous/snyder.ts

@@ -0,0 +1,171 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+// Snyder (1992), An Equal-Area Map Projection for Polyhedral Globes.
+// Vector formulation: BRSR, https://brsr.github.io/2021/08/31/snyder-equal-area.html.
+// Original implementation of the published equations, with bounded inverse.
+import {DiscontinuousMap, type MapRegion, type MapPlacement} from './map-layout';
+import {
+  add,
+  cross,
+  dot,
+  scale,
+  unit,
+  coordinates,
+  geographic,
+  type Vector,
+  type Position
+} from './math';
+import {icosahedron, dodecahedron, iseaParents, dseaParents} from './snyder-mesh';
+
+export type SnyderMapOptions = {radius?: number};
+export function createIcosahedralSnyderMap(options: SnyderMapOptions = {}) {
+  return snyderMap(false, options);
+}
+export function createDodecahedralSnyderMap(options: SnyderMapOptions = {}) {
+  return snyderMap(true, options);
+}
+const difference = (a: Vector, b: Vector) => add(a, scale(b, -1));
+const area = (a: Vector, b: Vector, c: Vector) =>
+  2 * Math.atan2(Math.abs(dot(a, cross(b, c))), 1 + dot(a, b) + dot(b, c) + dot(c, a));
+const chord = (a: Vector, b: Vector) => Math.hypot(...difference(a, b));
+
+/** Area-preserving map from a spherical triangle to barycentric coordinates.
+ * The apex-to-point ray meets the opposite great-circle edge. Its area fraction
+ * sets the planar direction; its chord-distance fraction sets the radius.
+ */
+export function snyderTriangle(a: Vector, b: Vector, c: Vector, u: Position, v: Position) {
+  const total = area(a, b, c);
+  const edgeNormal = cross(b, c);
+  const det = u[0] * v[1] - u[1] * v[0];
+  return {
+    project(p: Vector): Position {
+      const distance = chord(a, p);
+      if (distance < 1e-14) return [0, 0];
+      let edge = unit(cross(cross(a, p), edgeNormal));
+      if (dot(edge, add(b, c)) < 0) edge = scale(edge, -1);
+      const h = distance / chord(a, edge);
+      const w = (h * area(a, b, edge)) / total;
+      return [(h - w) * u[0] + w * v[0], (h - w) * u[1] + w * v[1]];
+    },
+    unproject([x, y]: Position): Vector | null {
+      const beta = (x * v[1] - y * v[0]) / det;
+      const gamma = (u[0] * y - u[1] * x) / det;
+      const h = beta + gamma;
+      if (beta < -1e-9 || gamma < -1e-9 || h > 1 + 1e-9) return null;
+      if (h < 1e-14) return a;
+      // Area is monotone along the opposite edge. Normalized linear interpolation
+      // spans that minor arc; bisection avoids fragile inverse trig at vertices.
+      const target = Math.max(0, Math.min(1, gamma / h)) * total;
+      let low = 0,
+        high = 1;
+      for (let i = 0; i < 48; i++) {
+        const t = (low + high) / 2;
+        const q = unit(add(scale(b, 1 - t), scale(c, t)));
+        if (area(a, b, q) < target) low = t;
+        else high = t;
+      }
+      const t = (low + high) / 2;
+      const q = unit(add(scale(b, 1 - t), scale(c, t)));
+      const sinHalf = Math.min(1, Math.max(0, (h * chord(a, q)) / 2));
+      const theta = 2 * Math.asin(sinHalf);
+      const direction = unit(difference(q, scale(a, dot(a, q))));
+      return add(scale(a, Math.cos(theta)), scale(direction, Math.sin(theta)));
+    }
+  };
+}
+function snyderMap(dual: boolean, {radius = 1}: SnyderMapOptions) {
+  if (!Number.isFinite(radius) || radius <= 0)
+    throw new Error('Radius must be finite and positive');
+  const mesh = dual ? dodecahedron : icosahedron;
+  const parents = dual ? dseaParents : iseaParents;
+  const vertices = mesh.vertices as Vector[];
+  const faces = mesh.faces;
+  const frames = faces.map(face => {
+    const normal = unit(face.map(i => vertices[i]).reduce(add, [0, 0, 0]));
+    const x = unit(difference(vertices[face[0]], scale(normal, dot(normal, vertices[face[0]]))));
+    const y = cross(normal, x);
+    const plane = (v: Vector): Position => [dot(x, v), dot(y, v)];
+    return {normal, plane};
+  });
+  const placements: MapPlacement[] = [];
+  const root = parents.indexOf(-1);
+  // Normalize planar area to the unit sphere: total output area is 4πr².
+  const first = faces[0].map(i => frames[0].plane(vertices[i]));
+  let planarArea = 0;
+  for (let i = 0; i < first.length; i++) {
+    const a = first[i],
+      b = first[(i + 1) % first.length];
+    planarArea += a[0] * b[1] - a[1] * b[0];
+  }
+  const k = radius * Math.sqrt((4 * Math.PI) / ((faces.length * Math.abs(planarArea)) / 2));
+  placements[root] = [k, 0, 0, k, 0, 0];
+  const pending = faces.map((_, i) => i).filter(i => i !== root);
+  const place = (i: number, [x, y]: Position): Position => {
+    const [a, b, c, d, e, f] = placements[i];
+    return [a * x + c * y + e, b * x + d * y + f];
+  };
+  while (pending.length) {
+    const n = pending.findIndex(i => placements[parents[i]]);
+    if (n < 0) throw new Error('Invalid Snyder net');
+    const child = pending.splice(n, 1)[0],
+      parent = parents[child];
+    const shared = faces[child].filter(i => faces[parent].includes(i));
+    const [p, q] = shared.map(i => frames[child].plane(vertices[i]));
+    const [u, v] = shared.map(i => place(parent, frames[parent].plane(vertices[i])));
+    const dx = q[0] - p[0],
+      dy = q[1] - p[1],
+      length = dx * dx + dy * dy;
+    const a = ((v[0] - u[0]) * dx + (v[1] - u[1]) * dy) / length;
+    const b = ((v[1] - u[1]) * dx - (v[0] - u[0]) * dy) / length;
+    placements[child] = [a, b, -b, a, u[0] - a * p[0] + b * p[1], u[1] - b * p[0] - a * p[1]];
+  }
+  // Only the external face edges can be cut. Keep the continuous internal
+  // subdivision inside each kernel instead of multiplying clipping work by 6/10.
+  const charts: MapRegion[] = faces.map((face, i) => {
+    const {normal, plane} = frames[i];
+    const pieces = face.flatMap((index, j) => {
+      const b = vertices[index],
+        c = vertices[face[(j + 1) % face.length]];
+      const midpoint = unit(add(b, c));
+      const pb = plane(b),
+        pc = plane(c);
+      const pm: Position = [(pb[0] + pc[0]) / 2, (pb[1] + pc[1]) / 2];
+      return [
+        [b, midpoint],
+        [midpoint, c]
+      ].map((triangle, side) => ({
+        start: cross(normal, triangle[0]),
+        end: cross(triangle[1], normal),
+        kernel: snyderTriangle(
+          normal,
+          triangle[0],
+          triangle[1],
+          side === 0 ? pb : pm,
+          side === 0 ? pm : pc
+        )
+      }));
+    });
+    return {
+      id: `face-${i}`,
+      boundary: face.map(index => coordinates(vertices[index])),
+      interior: coordinates(normal),
+      placement: placements[i],
+      project: p => {
+        const v = geographic(p);
+        const piece = pieces.find(q => dot(q.start, v) >= -1e-12 && dot(q.end, v) >= -1e-12);
+        if (!piece) throw new Error('Point outside Snyder face');
+        return piece.kernel.project(v);
+      },
+      unproject: p => {
+        for (const piece of pieces) {
+          const q = piece.kernel.unproject([...p]);
+          if (q) return coordinates(q);
+        }
+        return null;
+      }
+    };
+  });
+  return new DiscontinuousMap(charts);
+}

package/src/discontinuous/spherical-clip/D3-GEO-LICENSE.txt

@@ -0,0 +1,34 @@
+Copyright 2010-2024 Mike Bostock
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+
+This license applies to GeographicLib, versions 1.12 and later.
+
+Copyright 2008-2012 Charles Karney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/src/discontinuous/spherical-clip/README.md

@@ -0,0 +1,16 @@
+# Spherical cap clipping
+
+Adapted from [d3-geo 3.1.1](https://github.com/d3/d3-geo/tree/v3.1.1/src),
+Copyright 2010–2024 Mike Bostock, under the retained [ISC license](./D3-GEO-LICENSE.txt).
+Flattened filenames preserve the source path (`clip/circle.js` → `clip-circle.js`).
+
+Changes: only circle clipping and its dependencies retained; unused display circle
+factory removed; precision and interpolation callbacks added; epsilon tightened to
+1e-12 for chart-local geometry; latitude recovered with atan2 rather than asin
+near polar limits. `helpers.js` independently supplies array flattening
+and Neumaier compensated summation, replacing the d3-array dependency. math.gl's
+`cap-map.ts` adds bounded adaptive projected-curve sampling, source-coordinate
+retention, chart trimming, hole grouping and regional coverage outlines.
+
+The numeric projection kernels and their separate provenance are in
+[world-kernels](../world-kernels/README.md). No D3 package is needed at runtime.