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

package/src/discontinuous/myriahedral/mesh.ts

@@ -0,0 +1,138 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export type Vec3 = [number, number, number];
+export type Polyhedron = {vertices: Vec3[]; faces: number[][]};
+export type Solid = 'tetrahedron' | 'cube' | 'octahedron' | 'dodecahedron' | 'icosahedron';
+export const subtract = (a: Vec3, b: Vec3): Vec3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+export const dot = (a: Vec3, b: Vec3): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+export const cross = (a: Vec3, b: Vec3): Vec3 => [
+  a[1] * b[2] - a[2] * b[1],
+  a[2] * b[0] - a[0] * b[2],
+  a[0] * b[1] - a[1] * b[0]
+];
+export const normalize = (v: Vec3): Vec3 => {
+  const n = Math.hypot(...v);
+  return v.map(x => x / n) as Vec3;
+};
+export const center = (points: Vec3[]): Vec3 =>
+  [0, 1, 2].map(i => points.reduce((s, p) => s + p[i], 0) / points.length) as Vec3;
+
+/** Independent construction from symmetric coordinates, with a small convex hull
+ * used only for the 4–20 vertices of the regular solids. No imported mesh tables.
+ */
+export function createSolid(solid: Solid, subdivisions = 0): Polyhedron {
+  if (!Number.isInteger(subdivisions) || subdivisions < 0 || subdivisions > 3)
+    throw new RangeError('Subdivision must be 0–3');
+  let vertices: Vec3[] = [];
+  switch (solid) {
+    case 'tetrahedron':
+      vertices = [
+        [1, 1, 1],
+        [1, -1, -1],
+        [-1, 1, -1],
+        [-1, -1, 1]
+      ];
+      break;
+    case 'cube':
+      for (const x of [-1, 1])
+        for (const y of [-1, 1]) for (const z of [-1, 1]) vertices.push([x, y, z]);
+      break;
+    case 'octahedron':
+      vertices = [
+        [1, 0, 0],
+        [-1, 0, 0],
+        [0, 1, 0],
+        [0, -1, 0],
+        [0, 0, 1],
+        [0, 0, -1]
+      ];
+      break;
+    case 'icosahedron': {
+      const phi = (1 + Math.sqrt(5)) / 2;
+      for (const a of [-1, 1])
+        for (const b of [-phi, phi]) vertices.push([0, a, b], [a, b, 0], [b, 0, a]);
+      break;
+    }
+    case 'dodecahedron': {
+      // The dual of the icosahedron: its face centers are dodecahedron vertices.
+      const ico = createSolid('icosahedron');
+      vertices = ico.faces.map(face => center(face.map(i => ico.vertices[i])));
+      break;
+    }
+    default:
+      throw new RangeError('Unknown solid');
+  }
+  vertices = vertices.map(normalize);
+  let faces = convexFaces(vertices);
+  // Triangulate polygonal faces around a shared spherical face center before
+  // recursive subdivision; triangle edges and all subsequent midpoints are shared.
+  if (subdivisions)
+    faces = faces.flatMap(face => {
+      if (face.length === 3) return [face];
+      const middle = vertices.push(normalize(center(face.map(i => vertices[i])))) - 1;
+      return face.map((v, i) => [v, face[(i + 1) % face.length], middle]);
+    });
+  for (let level = 0; level < subdivisions; level++) {
+    const midpoints = new Map<string, number>();
+    const midpoint = (a: number, b: number): number => {
+      const key = edgeKey(a, b);
+      if (!midpoints.has(key))
+        midpoints.set(key, vertices.push(normalize(center([vertices[a], vertices[b]]))) - 1);
+      return midpoints.get(key)!;
+    };
+    faces = faces.flatMap(([a, b, c]) => {
+      const ab = midpoint(a, b),
+        bc = midpoint(b, c),
+        ca = midpoint(c, a);
+      return [
+        [a, ab, ca],
+        [ab, b, bc],
+        [ca, bc, c],
+        [ab, bc, ca]
+      ];
+    });
+  }
+  return {vertices, faces};
+}
+export function edgeKey(a: number, b: number): string {
+  return a < b ? `${a}:${b}` : `${b}:${a}`;
+}
+export function faceNormal(mesh: Polyhedron, face: number[]): Vec3 {
+  return normalize(
+    cross(
+      subtract(mesh.vertices[face[1]], mesh.vertices[face[0]]),
+      subtract(mesh.vertices[face[2]], mesh.vertices[face[0]])
+    )
+  );
+}
+function convexFaces(vertices: Vec3[]): number[][] {
+  const found = new Map<string, number[]>();
+  for (let a = 0; a < vertices.length; a++)
+    for (let b = a + 1; b < vertices.length; b++)
+      for (let c = b + 1; c < vertices.length; c++) {
+        let n = cross(subtract(vertices[b], vertices[a]), subtract(vertices[c], vertices[a]));
+        if (Math.hypot(...n) < 1e-8) continue;
+        n = normalize(n);
+        let distances = vertices.map(v => dot(n, subtract(v, vertices[a])));
+        if (distances.some(d => d > 1e-8) && distances.some(d => d < -1e-8)) continue;
+        if (dot(n, vertices[a]) < 0) {
+          n = n.map(x => -x) as Vec3;
+          distances = distances.map(x => -x);
+        }
+        const ids = distances.flatMap((d, i) => (Math.abs(d) < 1e-8 ? [i] : []));
+        const key = ids.join(':');
+        if (found.has(key)) continue;
+        const origin = center(ids.map(i => vertices[i]));
+        const x = normalize(subtract(vertices[ids[0]], origin)),
+          y = cross(n, x);
+        ids.sort((i, j) => {
+          const p = subtract(vertices[i], origin),
+            q = subtract(vertices[j], origin);
+          return Math.atan2(dot(p, y), dot(p, x)) - Math.atan2(dot(q, y), dot(q, x));
+        });
+        found.set(key, ids);
+      }
+  return [...found.values()];
+}

package/src/discontinuous/myriahedral/unfold.ts

@@ -0,0 +1,208 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {Matrix4} from '@math.gl/core';
+import {HingeTree, type HingePanel} from '@math.gl/geometry';
+import {
+  center,
+  cross,
+  dot,
+  edgeKey,
+  faceNormal,
+  normalize,
+  subtract,
+  type Polyhedron,
+  type Vec3
+} from './mesh';
+
+export type MeshEdge = {a: number; b: number; faces: number[]; weight: number; hinge: boolean};
+/** Kruskal maximum spanning tree, with stable input-index tie breaking. */
+export function maximumSpanningTree(
+  count: number,
+  edges: {faces: number[]; weight: number}[]
+): number[] {
+  const roots = Array.from({length: count}, (_, i) => i),
+    ranks = new Uint32Array(count);
+  const find = (i: number): number => {
+    while (roots[i] !== i) {
+      roots[i] = roots[roots[i]];
+      i = roots[i];
+    }
+    return i;
+  };
+  const order = edges
+    .map((edge, i) => {
+      if (
+        edge.faces.length !== 2 ||
+        edge.faces.some(f => !Number.isInteger(f) || f < 0 || f >= count) ||
+        !Number.isFinite(edge.weight)
+      )
+        throw new Error('Invalid dual edge');
+      return i;
+    })
+    .sort((a, b) => edges[b].weight - edges[a].weight || a - b);
+  const selected: number[] = [];
+  for (const i of order) {
+    let a = find(edges[i].faces[0]),
+      b = find(edges[i].faces[1]);
+    if (a === b) continue;
+    if (ranks[a] < ranks[b]) [a, b] = [b, a];
+    roots[b] = a;
+    if (ranks[a] === ranks[b]) ranks[a]++;
+    selected.push(i);
+    if (selected.length === count - 1) break;
+  }
+  if (selected.length !== count - 1) throw new Error('Disconnected face graph');
+  return selected;
+}
+
+/** Internal layout builder for closed, consistently wound convex meshes.
+ * Each panel uses the original solid coordinate frame, so rest transforms are identity.
+ */
+export function createLayout(
+  mesh: Polyhedron,
+  seed = 1,
+  options: {
+    weight?: (edge: MeshEdge, legacyWeight: number) => number;
+    joins?: number[][];
+  } = {}
+) {
+  const normals = mesh.faces.map(f => faceNormal(mesh, f));
+  const map = new Map<string, MeshEdge>();
+  mesh.faces.forEach((face, i) =>
+    face.forEach((a, j) => {
+      const b = face[(j + 1) % face.length],
+        key = edgeKey(a, b);
+      if (!map.has(key))
+        map.set(key, {a: Math.min(a, b), b: Math.max(a, b), faces: [], weight: 0, hinge: false});
+      map.get(key)!.faces.push(i);
+    })
+  );
+  const edges = [...map.values()];
+  for (const edge of edges) {
+    if (edge.faces.length !== 2) throw new Error('Expected a closed two-manifold mesh');
+    // Favor shorter joins, with seeded variation to explore different unfoldings.
+    // This is a layout heuristic, not an overlap-minimizing objective.
+    let hash =
+      Math.imul(edge.a + 1, 73856093) ^ Math.imul(edge.b + 1, 19349663) ^ Math.imul(seed, 83492791);
+    hash = Math.imul(hash ^ (hash >>> 16), 0x45d9f3b);
+    hash ^= hash >>> 16;
+    edge.weight =
+      -Math.hypot(...subtract(mesh.vertices[edge.a], mesh.vertices[edge.b])) +
+      (0.25 * (hash >>> 0)) / 4294967296;
+  }
+  for (const edge of edges) if (options.weight) edge.weight = options.weight(edge, edge.weight);
+  const allowed = options.joins && new Set(options.joins.map(([a, b]) => edgeKey(a, b)));
+  const candidates = allowed
+    ? edges.filter(e => allowed.has(edgeKey(e.faces[0], e.faces[1])))
+    : edges;
+  if (allowed && candidates.length !== allowed.size)
+    throw new Error('Preset contains a non-adjacent join');
+  const selected = maximumSpanningTree(mesh.faces.length, candidates);
+  const adjacency: {face: number; edge: MeshEdge}[][] = mesh.faces.map(() => []);
+  for (const i of selected) {
+    const edge = candidates[i];
+    edge.hinge = true;
+    const [a, b] = edge.faces;
+    adjacency[a].push({face: b, edge});
+    adjacency[b].push({face: a, edge});
+  }
+  const panels: HingePanel[] = mesh.faces.map(() => ({parent: -1}));
+  const targetAngles = new Float64Array(panels.length);
+  const order = [0],
+    seen = new Set([0]);
+  for (let i = 0; i < order.length; i++) {
+    const parent = order[i];
+    for (const {face, edge} of adjacency[parent]) {
+      if (seen.has(face)) continue;
+      seen.add(face);
+      order.push(face);
+      const axis = normalize(subtract(mesh.vertices[edge.b], mesh.vertices[edge.a]));
+      panels[face] = {parent, pivot: mesh.vertices[edge.a], axis};
+      targetAngles[face] = Math.atan2(
+        dot(axis, cross(normals[face], normals[parent])),
+        dot(normals[face], normals[parent])
+      );
+    }
+  }
+  const tree = new HingeTree(panels);
+  const origin = center(mesh.faces[0].map(i => mesh.vertices[i]));
+  const x = normalize(subtract(mesh.vertices[mesh.faces[0][1]], mesh.vertices[mesh.faces[0][0]]));
+  const z = normals[0],
+    y = cross(z, x);
+  const rootTransform = new Matrix4([
+    x[0],
+    y[0],
+    z[0],
+    0,
+    x[1],
+    y[1],
+    z[1],
+    0,
+    x[2],
+    y[2],
+    z[2],
+    0,
+    -dot(x, origin),
+    -dot(y, origin),
+    -dot(z, origin),
+    1
+  ]);
+  const poses = new Float64Array(panels.length * 16),
+    angles = new Float64Array(panels.length);
+  const evaluate = (amount: number): Vec3[][] => {
+    if (!Number.isFinite(amount) || amount < 0 || amount > 1)
+      throw new RangeError('Unfold amount must be within [0, 1]');
+    for (let i = 0; i < angles.length; i++) angles[i] = targetAngles[i] * amount;
+    tree.evaluate(angles, poses, rootTransform);
+    const matrix = new Matrix4();
+    return mesh.faces.map((face, i) => {
+      matrix.copy(poses.subarray(i * 16, i * 16 + 16));
+      return face.map(v => Array.from(matrix.transformAsPoint(mesh.vertices[v])) as Vec3);
+    });
+  };
+  const flat = evaluate(1);
+  const overlaps = countOverlaps(flat);
+  return {mesh, edges, panels, targetAngles, tree, rootTransform, evaluate, overlaps};
+}
+
+/** Count positive-area overlaps of convex faces in the final XY net.
+ * Sweep by X bounds, then separating axes; mere shared edges do not overlap.
+ */
+export function countOverlaps(faces: Vec3[][]): number {
+  const bounds = faces
+    .map((points, i) => ({
+      i,
+      minX: Math.min(...points.map(p => p[0])),
+      maxX: Math.max(...points.map(p => p[0])),
+      minY: Math.min(...points.map(p => p[1])),
+      maxY: Math.max(...points.map(p => p[1]))
+    }))
+    .sort((a, b) => a.minX - b.minX);
+  let count = 0;
+  for (let i = 0; i < bounds.length; i++)
+    for (let j = i + 1; j < bounds.length && bounds[j].minX < bounds[i].maxX - 1e-8; j++) {
+      const a = bounds[i],
+        b = bounds[j];
+      if (b.minY >= a.maxY - 1e-8 || a.minY >= b.maxY - 1e-8) continue;
+      const p = faces[a.i],
+        q = faces[b.i];
+      const separate = [p, q].some(poly =>
+        poly.some((v, k) => {
+          const next = poly[(k + 1) % poly.length],
+            dx = next[0] - v[0],
+            dy = next[1] - v[1],
+            length = Math.hypot(dx, dy);
+          const project = (point: Vec3) => (point[0] * dy - point[1] * dx) / length;
+          const pp = p.map(project),
+            qq = q.map(project);
+          return (
+            Math.max(...pp) <= Math.min(...qq) + 1e-8 || Math.max(...qq) <= Math.min(...pp) + 1e-8
+          );
+        })
+      );
+      if (!separate) count++;
+    }
+  return count;
+}

package/src/discontinuous/myriahedral.ts

@@ -0,0 +1,285 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {DiscontinuousMap, type GeographicPosition, type MapRegion} from './map-layout';
+import {coordinates, geographic, angle, RAD} from './math';
+import {createGraticule} from './myriahedral/graticule';
+import {createLayout, type MeshEdge} from './myriahedral/unfold';
+import {
+  createSolid,
+  center,
+  cross,
+  dot,
+  faceNormal,
+  normalize,
+  subtract,
+  type Polyhedron,
+  type Solid,
+  type Vec3
+} from './myriahedral/mesh';
+
+export type MyriahedralMesh = Polyhedron;
+export type MyriahedralSolid = Solid;
+export type MyriahedralPreset =
+  | 'polyconic'
+  | 'cylindric'
+  | 'azimuthal'
+  | 'hemispheres'
+  | 'sealine'
+  | 'coastline'
+  | 'polyhedral';
+export type MyriahedralOptions = {
+  /** Independent cut strategy, not an implementation of an analytic namesake. Default cylindric. */
+  preset?: MyriahedralPreset;
+  /** Multiple of four, 12–96. Default 48. Graticule presets only. */
+  columns?: number;
+  /** Polyhedral preset only. Default icosahedron. */
+  solid?: MyriahedralSolid;
+  /** Polyhedral preset only, 0–3. Default 1. Zero keeps the original polygonal faces. */
+  subdivisions?: number;
+  /** Optional closed, outward-wound, convex planar panels on the unit sphere. */
+  mesh?: MyriahedralMesh;
+  /** Longitude in degrees for the backbone/secondary join preference. Default 20. */
+  centralMeridian?: number;
+  /** Positive output scale; default 1. Input and texture coordinates remain spherical. */
+  radius?: number;
+  /** Required for sealine/coastline. Called with degrees; no bundled geography or network access. */
+  isLand?: (position: GeographicPosition) => boolean;
+  /** Maximum angular interval for land sampling in degrees; default .25, range [.05, 10]. */
+  landSampleStep?: number;
+  /** Final retained-join weight override. Higher values are less likely to be cut. */
+  edgeWeight?: (edge: Readonly<MyriahedralEdge>, presetWeight: number) => number;
+};
+export type MyriahedralEdge = {
+  vertices: readonly [number, number];
+  panels: readonly [number, number];
+  midpoint: GeographicPosition;
+  arcLength: number;
+  landFraction?: number;
+};
+
+export const MYRIAHEDRAL_PRESETS: readonly MyriahedralPreset[] = Object.freeze([
+  'polyconic',
+  'cylindric',
+  'azimuthal',
+  'hemispheres',
+  'sealine',
+  'coastline',
+  'polyhedral'
+]);
+
+/** Build an independent spherical panel net and its rigid unfolding animation.
+ * Each call owns its mesh. Geographical costs are sampled once per edge.
+ */
+export function createMyriahedralLayout(options: MyriahedralOptions = {}): MyriahedralLayout {
+  const preset = options.preset ?? 'cylindric';
+  if (!MYRIAHEDRAL_PRESETS.includes(preset)) throw new RangeError('Unknown myriahedral preset');
+  const radius = options.radius ?? 1;
+  const longitude = options.centralMeridian ?? 20;
+  const step = options.landSampleStep ?? 0.25;
+  if (!Number.isFinite(radius) || radius <= 0)
+    throw new RangeError('Radius must be finite and positive');
+  if (!Number.isFinite(longitude)) throw new RangeError('Central meridian must be finite');
+  if (!Number.isFinite(step) || step < 0.05 || step > 10)
+    throw new RangeError('Land sample step must be within [.05, 10]');
+  if ((preset === 'sealine' || preset === 'coastline') && !options.isLand)
+    throw new Error('Sealine and coastline require an isLand callback');
+  const central = (((((longitude + 180) % 360) + 360) % 360) - 180) * RAD;
+  const mesh = options.mesh
+    ? snapshotMesh(options.mesh)
+    : preset === 'polyhedral'
+      ? createSolid(options.solid ?? 'icosahedron', options.subdivisions ?? 1)
+      : createGraticule(options.columns ?? 48);
+  // Select a stable root near the requested center (north pole for radial nets).
+  const target = geographic([
+    longitude,
+    preset === 'azimuthal' || preset === 'hemispheres' ? 90 : 0
+  ]);
+  let root = 0;
+  for (let i = 1; i < mesh.faces.length; i++)
+    if (
+      dot(normalize(center(mesh.faces[i].map(v => mesh.vertices[v]))), target) >
+      dot(normalize(center(mesh.faces[root].map(v => mesh.vertices[v]))), target) + 1e-12
+    )
+      root = i;
+  [mesh.faces[0], mesh.faces[root]] = [mesh.faces[root], mesh.faces[0]];
+  const samples = new Map<string, MyriahedralEdge>();
+  const data = (edge: MeshEdge): MyriahedralEdge => {
+    const key = `${edge.a}:${edge.b}`;
+    let value = samples.get(key);
+    if (value) return value;
+    const a = mesh.vertices[edge.a],
+      b = mesh.vertices[edge.b];
+    const arcLength = angle(a, b);
+    let landFraction: number | undefined;
+    if (options.isLand) {
+      const count = Math.max(1, Math.ceil(arcLength / (step * RAD)));
+      let hits = 0;
+      for (let i = 0; i < count; i++) {
+        const t = (i + 0.5) / count;
+        const p = a.map(
+          (x, k) => x * Math.sin((1 - t) * arcLength) + b[k] * Math.sin(t * arcLength)
+        ) as Vec3;
+        if (options.isLand(coordinates(p))) hits++;
+      }
+      landFraction = hits / count;
+    }
+    value = Object.freeze({
+      vertices: Object.freeze([edge.a, edge.b]) as readonly [number, number],
+      panels: Object.freeze([...edge.faces]) as readonly [number, number],
+      midpoint: Object.freeze(coordinates(normalize(center([a, b])))),
+      arcLength,
+      landFraction
+    });
+    samples.set(key, value);
+    return value;
+  };
+  const weight = (edge: MeshEdge) => {
+    const a = mesh.vertices[edge.a],
+      b = mesh.vertices[edge.b];
+    const d = data(edge);
+    const lat = d.midpoint[1] * RAD;
+    const lon = d.midpoint[0] * RAD;
+    const delta = Math.abs(Math.atan2(Math.sin(lon - central), Math.cos(lon - central)));
+    const parallel = Math.abs(a[2] - b[2]) < 1e-10;
+    const seam = !parallel && Math.abs(Math.abs(lon) - Math.PI) < 1e-8;
+    let result: number;
+    if (preset === 'polyhedral') {
+      // Geographic continuity, then short local joins. Stable input order resolves ties.
+      result = (d.landFraction ?? 0) * 10000 - d.arcLength;
+    } else if (preset === 'polyconic') {
+      // Latitude strips connected along a central meridian.
+      result = (parallel ? 0 : 100) - delta - Math.abs(lat) * 0.01;
+    } else {
+      // Longitude strips connected at the equator, north cap, or both polar caps.
+      const anchor =
+        preset === 'azimuthal'
+          ? Math.PI / 2
+          : preset === 'hemispheres'
+            ? (Math.sign(lat) * Math.PI) / 2
+            : 0;
+      result = (parallel ? 100 : 0) - Math.abs(lat - anchor) - delta * 0.01;
+      if (preset === 'hemispheres' && parallel && Math.abs(a[2]) < 1e-10) result = -100 - delta;
+      if (preset === 'sealine') result += d.landFraction! * 10000;
+      if (preset === 'coastline') result += (1 - d.landFraction!) * 10000;
+      if (
+        (preset === 'cylindric' || preset === 'sealine' || preset === 'coastline') &&
+        !parallel &&
+        Math.abs(Math.min(a[2], b[2])) < 1e-10
+      )
+        result = 1e6;
+    }
+    if (seam && preset !== 'polyhedral') result = -1e9;
+    return options.edgeWeight ? options.edgeWeight(d, result) : result;
+  };
+  const layout = createLayout(mesh, 1, {weight});
+  const unscaled = layout.evaluate;
+  const evaluate = (amount: number) =>
+    unscaled(amount).map(face => face.map(p => p.map(v => v * radius) as Vec3));
+  const cutLandRadians = options.isLand
+    ? layout.edges.reduce(
+        (sum, edge) => sum + (edge.hinge ? 0 : data(edge).arcLength * data(edge).landFraction!),
+        0
+      )
+    : undefined;
+  return {...layout, evaluate, preset, radius, cutLandRadians};
+}
+export type MyriahedralLayout = ReturnType<typeof createLayout> & {
+  preset: MyriahedralPreset;
+  radius: number;
+  /** Undefined without an isLand callback. */
+  cutLandRadians?: number;
+};
+
+/** A static seam-aware projection with the same panel IDs and layout as its animation.
+ * Radial/gnomonic mapping is locally approximate, not equal-area or conformal.
+ */
+export class MyriahedralMap extends DiscontinuousMap {
+  readonly layout: MyriahedralLayout;
+  constructor(options: MyriahedralOptions = {}) {
+    const layout = createMyriahedralLayout(options);
+    super(regions(layout));
+    this.layout = layout;
+  }
+}
+
+/** Create a reusable static projection; use map.layout.evaluate(t) for unfolding. */
+export function createMyriahedralMap(options: MyriahedralOptions = {}): MyriahedralMap {
+  return new MyriahedralMap(options);
+}
+
+function regions(layout: MyriahedralLayout): MapRegion[] {
+  const flat = layout.evaluate(1);
+  return layout.mesh.faces.map((face, i) => {
+    const origin = [...layout.mesh.vertices[face[0]]] as Vec3;
+    const x = normalize(subtract(layout.mesh.vertices[face[1]], origin));
+    const normal = faceNormal(layout.mesh, face),
+      y = cross(normal, x);
+    const height = dot(normal, origin);
+    const fx = normalize(subtract(flat[i][1], flat[i][0]));
+    const radius = layout.radius;
+    return {
+      id: `panel-${i}`,
+      boundary: face.map(v => coordinates(layout.mesh.vertices[v])),
+      interior: coordinates(normalize(center(face.map(v => layout.mesh.vertices[v])))),
+      placement: [
+        radius * fx[0],
+        radius * fx[1],
+        -radius * fx[1],
+        radius * fx[0],
+        flat[i][0][0],
+        flat[i][0][1]
+      ],
+      project: p => {
+        const direction = geographic(p);
+        const point = direction.map(v => (v * height) / dot(normal, direction)) as Vec3;
+        return [dot(subtract(point, origin), x), dot(subtract(point, origin), y)];
+      },
+      unproject: ([u, v]) =>
+        coordinates(normalize(origin.map((c, k) => c + u * x[k] + v * y[k]) as Vec3))
+    };
+  });
+}
+
+function snapshotMesh(input: MyriahedralMesh): MyriahedralMesh {
+  if (!input.vertices?.length || !input.faces?.length || input.faces.length > 20000)
+    throw new Error('Expected a nonempty mesh with at most 20000 panels');
+  const mesh = {
+    vertices: input.vertices.map(v => [...v] as Vec3),
+    faces: input.faces.map(f => [...f])
+  };
+  if (
+    mesh.vertices.some(
+      v => v.length !== 3 || !v.every(Number.isFinite) || Math.abs(Math.hypot(...v) - 1) > 1e-8
+    )
+  )
+    throw new Error('Mesh vertices must lie on the unit sphere');
+  for (const face of mesh.faces) {
+    if (
+      face.length < 3 ||
+      new Set(face).size !== face.length ||
+      face.some(v => !Number.isInteger(v) || v < 0 || v >= mesh.vertices.length)
+    )
+      throw new Error('Invalid panel indices');
+    const normal = faceNormal(mesh, face),
+      origin = mesh.vertices[face[0]];
+    if (
+      !normal.every(Number.isFinite) ||
+      dot(normal, origin) <= 1e-8 ||
+      face.some(v => Math.abs(dot(normal, subtract(mesh.vertices[v], origin))) > 1e-8)
+    )
+      throw new Error('Panels must be planar and outward-wound');
+    for (let i = 0; i < face.length; i++) {
+      const a = mesh.vertices[face[i]],
+        b = mesh.vertices[face[(i + 1) % face.length]];
+      if (
+        angle(a, b) < 1e-10 ||
+        angle(a, b) >= Math.PI - 1e-8 ||
+        face.some(v => dot(cross(a, b), mesh.vertices[v]) < -1e-8)
+      )
+        throw new Error('Panels must be convex with nondegenerate minor-arc edges');
+    }
+  }
+  return mesh;
+}