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

package/src/discontinuous/map-transition.ts

@@ -0,0 +1,339 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import polygonClipping from 'polygon-clipping';
+import type {MapEngine, MapPosition3D} from './map-engine';
+import type {GeographicPosition, MapSamplingOptions, MapRegion} from './map-layout';
+import {geographic, type Position} from './math';
+import {rectangle} from './elastic/geometry';
+
+export type MapTransitionOptions = {strategy?: 'auto' | 'direct' | 'via-globe'};
+export type MapTransitionPart = Readonly<{
+  kind: 'line' | 'polygon';
+  sourceRegionId?: string;
+  targetRegionId?: string;
+  sourceCoordinates: readonly (readonly GeographicPosition[])[];
+  from: readonly (readonly GeographicPosition[])[];
+  to: readonly (readonly GeographicPosition[])[];
+}>;
+export type MapTransitionFrame = {
+  kind: 'line' | 'polygon';
+  sourceRegionId?: string;
+  targetRegionId?: string;
+  coordinates: MapPosition3D[][];
+  opacity: number;
+};
+
+/** Prepared geographic correspondence. Construct once, evaluate cheaply per frame.
+ * Direct morphs preserve cuts, but can overlap or fold at intermediate times. */
+export class MapTransitionGeometry {
+  readonly parts: readonly MapTransitionPart[];
+  constructor(
+    parts: MapTransitionPart[],
+    readonly strategy: 'direct' | 'via-globe',
+    private radius: number
+  ) {
+    this.parts = Object.freeze(
+      parts.map(p =>
+        Object.freeze({
+          ...p,
+          sourceCoordinates: freezeRings(p.sourceCoordinates),
+          from: freezeRings(p.from),
+          to: freezeRings(p.to)
+        })
+      )
+    );
+  }
+  evaluate(amount: number): MapTransitionFrame[] {
+    validateAmount(amount);
+    return this.parts.flatMap(part => {
+      const sourcePhase = part.sourceRegionId !== undefined;
+      const blend = Math.max(0, Math.min(1, (amount - 0.4) / 0.2));
+      const opacity = this.strategy === 'direct' ? 1 : sourcePhase ? 1 - blend : blend;
+      if (!opacity) return [];
+      const t =
+        this.strategy === 'direct'
+          ? amount
+          : sourcePhase
+            ? Math.min(1, amount / 0.4)
+            : Math.max(0, (amount - 0.6) / 0.4);
+      return [
+        {
+          kind: part.kind,
+          sourceRegionId: part.sourceRegionId,
+          targetRegionId: part.targetRegionId,
+          opacity,
+          coordinates: part.sourceCoordinates.map((ring, j) =>
+            ring.map((p, i) => {
+              const a = part.from[j][i],
+                b = part.to[j][i];
+              if (this.strategy === 'direct')
+                return [a[0] * (1 - t) + b[0] * t, a[1] * (1 - t) + b[1] * t, 0] as MapPosition3D;
+              const globe = geographic(p).map(v => v * this.radius);
+              const flat = sourcePhase ? a : b,
+                weight = sourcePhase ? 1 - t : t;
+              return [
+                flat[0] * weight + globe[0] * (1 - weight),
+                flat[1] * weight + globe[1] * (1 - weight),
+                globe[2] * (1 - weight)
+              ] as MapPosition3D;
+            })
+          )
+        }
+      ];
+    });
+  }
+}
+
+/** A renderer owns time, easing, camera fitting and picking during motion. */
+export class MapTransition {
+  readonly strategy: 'direct' | 'via-globe';
+  readonly reason: string;
+  constructor(
+    readonly source: MapEngine,
+    readonly target: MapEngine,
+    options: MapTransitionOptions = {}
+  ) {
+    const requested = options.strategy ?? 'auto';
+    if (!['auto', 'direct', 'via-globe'].includes(requested))
+      throw new Error('Unknown transition strategy');
+    const compatible = source === target || (fullCoverage(source) && fullCoverage(target));
+    if (requested === 'direct' && !compatible)
+      throw new Error(
+        'Direct morph requires complete supported geographic coverage; use auto or via-globe'
+      );
+    this.strategy = requested === 'via-globe' ? 'via-globe' : compatible ? 'direct' : 'via-globe';
+    this.reason =
+      this.strategy === 'direct'
+        ? 'Geometry is refined against both maps before interpolating corresponding geographic positions.'
+        : 'Coverage or surface topology requires separate source and destination geometry through the globe.';
+  }
+  projectPoint(position: GeographicPosition, amount: number): MapPosition3D | null {
+    validateAmount(amount);
+    const a = this.source.projectPoint(position),
+      b = this.target.projectPoint(position);
+    if (this.strategy === 'direct')
+      return a && b
+        ? [
+            a.position[0] * (1 - amount) + b.position[0] * amount,
+            a.position[1] * (1 - amount) + b.position[1] * amount,
+            0
+          ]
+        : null;
+    const hit = amount < 0.5 ? a : b;
+    if (!hit) return null;
+    const t = amount < 0.5 ? Math.max(0, 1 - amount / 0.4) : Math.max(0, (amount - 0.6) / 0.4);
+    const globe = geographic(position).map(v => v * this.globeRadius);
+    return [
+      hit.position[0] * t + globe[0] * (1 - t),
+      hit.position[1] * t + globe[1] * (1 - t),
+      globe[2] * (1 - t)
+    ];
+  }
+  private get globeRadius() {
+    return Math.max(this.source.description.radius ?? 1, this.target.description.radius ?? 1);
+  }
+  prepareLine(
+    line: readonly GeographicPosition[],
+    options?: MapSamplingOptions
+  ): MapTransitionGeometry {
+    const first = this.source.projectLine(line, options),
+      last = this.target.projectLine(line, options);
+    const parts: MapTransitionPart[] = [];
+    if (this.strategy === 'direct' && this.source === this.target) {
+      for (const p of first)
+        parts.push({
+          kind: 'line',
+          sourceRegionId: p.regionId,
+          targetRegionId: p.regionId,
+          sourceCoordinates: [p.sourceCoordinates],
+          from: [p.coordinates],
+          to: [p.coordinates]
+        });
+    } else if (this.strategy === 'direct') {
+      for (const a of first)
+        for (const b of this.target.projectLine(a.sourceCoordinates, options)) {
+          const source = this.source.regions.find(r => r.id === a.regionId)!;
+          parts.push({
+            kind: 'line',
+            sourceRegionId: a.regionId,
+            targetRegionId: b.regionId,
+            sourceCoordinates: [b.sourceCoordinates],
+            from: [b.sourceCoordinates.map(p => placed(source, p))],
+            to: [b.coordinates]
+          });
+        }
+    } else {
+      for (const p of first)
+        parts.push({
+          kind: 'line',
+          sourceRegionId: p.regionId,
+          sourceCoordinates: [p.sourceCoordinates],
+          from: [p.coordinates],
+          to: [p.coordinates]
+        });
+      for (const p of last)
+        parts.push({
+          kind: 'line',
+          targetRegionId: p.regionId,
+          sourceCoordinates: [p.sourceCoordinates],
+          from: [p.coordinates],
+          to: [p.coordinates]
+        });
+    }
+    return new MapTransitionGeometry(parts, this.strategy, this.globeRadius);
+  }
+  preparePolygon(
+    rings: readonly (readonly GeographicPosition[])[],
+    options?: MapSamplingOptions
+  ): MapTransitionGeometry {
+    const first = this.source.projectPolygon(rings, options),
+      last = this.target.projectPolygon(rings, options),
+      parts: MapTransitionPart[] = [];
+    if (this.strategy === 'direct' && this.source === this.target) {
+      for (const p of first)
+        parts.push({
+          kind: 'polygon',
+          sourceRegionId: p.regionId,
+          targetRegionId: p.regionId,
+          sourceCoordinates: p.sourceCoordinates,
+          from: p.coordinates,
+          to: p.coordinates
+        });
+    } else if (this.strategy === 'direct') {
+      // Intersect the already sampled geographic rings. Re-interpreting a
+      // clipped cut boundary as new great-circle input would bend that boundary
+      // and can create invalid slivers at a chart's pole or antimeridian.
+      for (const a of first) {
+        const source = this.source.regions.find(r => r.id === a.regionId)!;
+        const left = geographicRings(a.sourceCoordinates);
+        const center = left[0][0][0];
+        for (const b of last) {
+          const target = this.target.regions.find(r => r.id === b.regionId)!;
+          const right = geographicRings(b.sourceCoordinates, center);
+          for (const rings of polygonClipping.intersection(left, right)) {
+            const coordinates = rings as Position[][];
+            parts.push({
+              kind: 'polygon',
+              sourceRegionId: a.regionId,
+              targetRegionId: b.regionId,
+              sourceCoordinates: coordinates,
+              from: coordinates.map(r => r.map(p => placed(source, p))),
+              to: coordinates.map(r => r.map(p => placed(target, p)))
+            });
+          }
+        }
+      }
+    } else {
+      for (const p of first)
+        parts.push({
+          kind: 'polygon',
+          sourceRegionId: p.regionId,
+          sourceCoordinates: p.sourceCoordinates,
+          from: p.coordinates,
+          to: p.coordinates
+        });
+      for (const p of last)
+        parts.push({
+          kind: 'polygon',
+          targetRegionId: p.regionId,
+          sourceCoordinates: p.sourceCoordinates,
+          from: p.coordinates,
+          to: p.coordinates
+        });
+    }
+    return new MapTransitionGeometry(parts, this.strategy, this.globeRadius);
+  }
+}
+function placed(region: MapRegion, p: GeographicPosition): Position {
+  const q = region.project(p),
+    [a, b, c, d, x, y] = region.placement ?? [1, 0, 0, 1, 0, 0];
+  const result: Position = [a * q[0] + c * q[1] + x, b * q[0] + d * q[1] + y];
+  if (!result.every(Number.isFinite))
+    throw new Error('Undefined projection in common transition coverage');
+  return result;
+}
+function freezeRings(rings: readonly (readonly GeographicPosition[])[]) {
+  return Object.freeze(
+    rings.map(r => Object.freeze(r.map(p => Object.freeze([...p]) as GeographicPosition)))
+  );
+}
+function validateAmount(t: number) {
+  if (!Number.isFinite(t) || t < 0 || t > 1)
+    throw new Error('Transition amount must be within [0,1]');
+}
+const coverageCache = new WeakMap<MapEngine, boolean>();
+function fullCoverage(map: MapEngine): boolean {
+  const cached = coverageCache.get(map);
+  if (cached !== undefined) return cached;
+  const d = map.description.definition;
+  let covered = false;
+  if (d.type === 'elastic') {
+    const world = rectangle(-180, -90, 180, 90);
+    let completeSections = true;
+    const domains = d.data.sections.map(s => {
+      const domain = s.complement
+        ? polygonClipping.difference(world, [s.boundary as Position[]])
+        : polygonClipping.intersection(world, [s.boundary as Position[]]);
+      // Include only cells with four defined corners. Merge contiguous row runs
+      // before clipping to avoid treating interpolation holes as valid coverage.
+      const runs: Position[][][] = [];
+      for (let y = 0; y < s.rows - 1; y++) {
+        let start = -1;
+        for (let x = 0; x < s.columns; x++) {
+          const valid =
+            x < s.columns - 1 &&
+            [
+              y * s.columns + x,
+              y * s.columns + x + 1,
+              (y + 1) * s.columns + x,
+              (y + 1) * s.columns + x + 1
+            ].every(i => s.values[2 * i] !== null);
+          if (valid && start < 0) start = x;
+          if (!valid && start >= 0) {
+            runs.push(
+              rectangle(
+                -180 + (360 * start) / (s.columns - 1),
+                -90 + (180 * y) / (s.rows - 1),
+                -180 + (360 * x) / (s.columns - 1),
+                -90 + (180 * (y + 1)) / (s.rows - 1)
+              )
+            );
+            start = -1;
+          }
+        }
+      }
+      const valid = runs.length ? polygonClipping.union(runs[0], ...runs.slice(1)) : [];
+      if (!valid.length || polygonClipping.difference(domain, valid).length)
+        completeSections = false;
+      return valid.length ? polygonClipping.intersection(domain, valid) : [];
+    });
+    // Multiple placements of the same geography need a correspondence policy,
+    // not a Cartesian product of charts. Keep those maps on the globe route.
+    const overlaps = domains.some((domain, i) =>
+      domains.slice(i + 1).some(other => polygonClipping.intersection(domain, other).length > 0)
+    );
+    covered =
+      completeSections && !overlaps && polygonClipping.difference(world, ...domains).length === 0;
+  } else if (d.type === 'world') {
+    // Deliberately bounded to global formulas with finite poles. Other kernels,
+    // custom charts and regional maps retain the conservative globe route.
+    covered = ['sinusoidal', 'mollweide', 'robinson'].includes(d.projection);
+  }
+  coverageCache.set(map, covered);
+  return covered;
+}
+
+function geographicRings(
+  rings: readonly (readonly GeographicPosition[])[],
+  center?: number
+): Position[][] {
+  return rings.map(ring => {
+    let previous = center ?? ring[0][0];
+    return ring.map(([lon, lat]) => {
+      const x = lon + 360 * Math.round((previous - lon) / 360);
+      previous = x;
+      return [Math.round(x * 1e9) / 1e9, Math.round(lat * 1e9) / 1e9];
+    });
+  });
+}

package/src/discontinuous/math.ts

@@ -0,0 +1,67 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export type Position = [number, number];
+export type Vector = [number, number, number];
+export const RAD = Math.PI / 180;
+export const dot = (a: Vector, b: Vector) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+export const cross = (a: Vector, b: Vector): Vector => [
+  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 add = (a: Vector, b: Vector): Vector => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const scale = (a: Vector, t: number): Vector => [a[0] * t, a[1] * t, a[2] * t];
+export function unit(a: Vector): Vector {
+  const length = Math.hypot(...a);
+  if (!(length > 1e-14)) throw new Error('Degenerate spherical direction');
+  return scale(a, 1 / length);
+}
+export function geographic(p: readonly number[]): Vector {
+  if (p.length !== 2 || !p.every(Number.isFinite) || Math.abs(p[1]) > 90)
+    throw new Error('Expected finite [longitude, latitude] in degrees, latitude within [-90, 90]');
+  const lon = (((((p[0] + 180) % 360) + 360) % 360) - 180) * RAD,
+    lat = p[1] * RAD;
+  return [Math.cos(lat) * Math.cos(lon), Math.cos(lat) * Math.sin(lon), Math.sin(lat)];
+}
+export function coordinates(p: Vector): Position {
+  return [Math.atan2(p[1], p[0]) / RAD, Math.atan2(p[2], Math.hypot(p[0], p[1])) / RAD];
+}
+export function angle(a: Vector, b: Vector): number {
+  return Math.atan2(Math.hypot(...cross(a, b)), dot(a, b));
+}
+export function validateArc(a: Vector, b: Vector) {
+  if (Math.PI - angle(a, b) < 1e-9)
+    throw new Error('Antipodal edges are ambiguous; insert an intermediate vertex');
+}
+export function basis(center: Vector): [Vector, Vector] {
+  const x = unit(cross(Math.abs(center[2]) < 0.9 ? [0, 0, 1] : [0, 1, 0], center));
+  return [x, cross(center, x)];
+}
+/** Orientation of a planar ring, normalized by its own extent. Translating
+ * before summation preserves tiny holes far from the chart origin; scaling
+ * avoids an absolute minimum area and overflow/underflow in cross products.
+ */
+export function ringOrientation(ring: Position[]): number {
+  const origin = ring[0];
+  let extent = 0;
+  for (const p of ring)
+    extent = Math.max(extent, Math.abs(p[0] - origin[0]), Math.abs(p[1] - origin[1]));
+  if (!extent) return 0;
+  if (!Number.isFinite(extent)) {
+    let coordinateScale = 0;
+    for (const p of ring)
+      coordinateScale = Math.max(coordinateScale, Math.abs(p[0]), Math.abs(p[1]));
+    return ringOrientation(ring.map(p => [p[0] / coordinateScale, p[1] / coordinateScale]));
+  }
+  let sum = 0;
+  for (let i = 0; i < ring.length; i++) {
+    const p = ring[i],
+      q = ring[(i + 1) % ring.length];
+    sum +=
+      ((p[0] - origin[0]) / extent) * ((q[1] - origin[1]) / extent) -
+      ((p[1] - origin[1]) / extent) * ((q[0] - origin[0]) / extent);
+  }
+  return Math.sign(sum);
+}

package/src/discontinuous/mercator-map.ts

@@ -0,0 +1,160 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import polygonClipping from 'polygon-clipping';
+import {
+  DiscontinuousMap,
+  type GeographicPosition,
+  type MapLine,
+  type MapRegion,
+  type MapSamplingOptions
+} from './map-layout';
+import {geographic, RAD, type Vector} from './math';
+
+/** Spherical Mercator, clipped to a finite latitude band after seam splitting. */
+export class MercatorMap extends DiscontinuousMap {
+  readonly limit: number;
+  private readonly ymax: number;
+  constructor(
+    readonly radius = 1,
+    readonly centralMeridian = 0,
+    maxLatitude = 85.0511287798066
+  ) {
+    if (
+      !Number.isFinite(radius) ||
+      radius <= 0 ||
+      !Number.isFinite(centralMeridian) ||
+      !Number.isFinite(maxLatitude) ||
+      maxLatitude <= 0 ||
+      maxLatitude >= 90
+    )
+      throw new Error('Invalid Mercator radius, central meridian or latitude limit');
+    const regions: MapRegion[] = [];
+    for (const sign of [1, -1])
+      for (let i = 0; i < 4; i++) {
+        const west = -180 + i * 90,
+          east = west + 90,
+          center = west + 45;
+        regions.push({
+          id: `${sign > 0 ? 'north' : 'south'}-${i}`,
+          layout: {kind: 'main'},
+          boundary: [
+            [west + centralMeridian, sign * 90],
+            [west + centralMeridian, 0],
+            [east + centralMeridian, 0]
+          ],
+          interior: [center + centralMeridian, sign * 45],
+          project: ([lon, lat]) => {
+            const delta = ((((lon - centralMeridian - center + 180) % 360) + 360) % 360) - 180;
+            // Keep longitude unchanged in the finite polar extension. Tapering
+            // X toward zero moves latitude-band intersections into other charts.
+            // Directional pole limits are supplied below; the extension is clipped.
+            const outside = Math.max(0, Math.abs(lat) - maxLatitude);
+
+            const phi = Math.min(Math.abs(lat), maxLatitude) * RAD;
+            return [
+              radius * (center + delta) * RAD,
+              radius * Math.sign(lat) * (Math.asinh(Math.tan(phi)) + outside * RAD)
+            ];
+          },
+          unproject: ([x, y]) => [
+            x / radius / RAD + centralMeridian,
+            Math.atan(Math.sinh(y / radius)) / RAD
+          ]
+        });
+      }
+    super(regions);
+    this.limit = maxLatitude;
+    this.ymax = radius * Math.asinh(Math.tan(maxLatitude * RAD));
+  }
+  protected override resolveSourceLimit(point: Vector, towards: Vector): Vector {
+    if (Math.hypot(point[0], point[1]) < 1e-14 && Math.hypot(towards[0], towards[1]) > 1e-14)
+      return geographic([Math.atan2(towards[1], towards[0]) / RAD, point[2] > 0 ? 90 : -90]);
+    return point;
+  }
+  override containsConvexPolygon(): boolean {
+    return false;
+  }
+  override findRegions(p: GeographicPosition) {
+    geographic(p);
+    return Math.abs(p[1]) <= this.limit + 1e-10 ? super.findRegions(p) : [];
+  }
+  override projectPoint(p: GeographicPosition, id?: string) {
+    geographic(p);
+    return Math.abs(p[1]) <= this.limit + 1e-10 ? super.projectPoint(p, id) : null;
+  }
+  override unprojectPoint(p: GeographicPosition, id?: string) {
+    return super
+      .unprojectPoint(p, id)
+      .filter(hit => Math.abs(hit.position[1]) <= this.limit + 1e-10);
+  }
+  private source([x, y]: GeographicPosition): [number, number] {
+    return [
+      x / this.radius / RAD + this.centralMeridian,
+      Math.atan(Math.sinh(y / this.radius)) / RAD
+    ];
+  }
+  override projectLine(
+    line: readonly GeographicPosition[],
+    options?: MapSamplingOptions
+  ): MapLine[] {
+    const result: MapLine[] = [];
+    for (const part of super.projectLine(line, options)) {
+      let current: MapLine | undefined;
+      for (let i = 1; i < part.coordinates.length; i++) {
+        const a = part.coordinates[i - 1],
+          b = part.coordinates[i];
+        const dy = b[1] - a[1];
+        const t0 = dy
+          ? Math.max(0, Math.min((-this.ymax - a[1]) / dy, (this.ymax - a[1]) / dy))
+          : 0;
+        const t1 = dy
+          ? Math.min(1, Math.max((-this.ymax - a[1]) / dy, (this.ymax - a[1]) / dy))
+          : 1;
+        if (t0 > t1 || (!dy && Math.abs(a[1]) > this.ymax)) {
+          current = undefined;
+          continue;
+        }
+        const at = (t: number): [number, number] => [a[0] + (b[0] - a[0]) * t, a[1] + dy * t];
+        const start = at(t0),
+          end = at(t1);
+        if (!current || t0 > 0) {
+          current = {
+            regionId: part.regionId,
+            coordinates: [start],
+            sourceCoordinates: [this.source(start)]
+          };
+          result.push(current);
+        }
+        current.coordinates.push(end);
+        current.sourceCoordinates.push(this.source(end));
+        if (t1 < 1) current = undefined;
+      }
+    }
+    return result;
+  }
+  override projectPolygon(
+    rings: readonly (readonly GeographicPosition[])[],
+    options?: MapSamplingOptions
+  ) {
+    const x = Math.PI * this.radius,
+      y = this.ymax;
+    const box: [number, number][][] = [
+      [
+        [-x, -y],
+        [x, -y],
+        [x, y],
+        [-x, y],
+        [-x, -y]
+      ]
+    ];
+    return super.projectPolygon(rings, options).flatMap(part =>
+      polygonClipping.intersection(part.coordinates, box).map(coordinates => ({
+        regionId: part.regionId,
+        coordinates,
+        sourceCoordinates: coordinates.map(ring => ring.map(p => this.source(p)))
+      }))
+    );
+  }
+}

package/src/discontinuous/myriahedral/graticule.ts

@@ -0,0 +1,40 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {Polyhedron, Vec3} from './mesh';
+
+/** Independent, closed graticule mesh. Equal-latitude trapezoids are planar.
+ * Pole cells are triangles; shared longitude seams use the same vertex IDs.
+ */
+export function createGraticule(columns: number): Polyhedron {
+  if (!Number.isInteger(columns) || columns < 12 || columns > 96 || columns % 4)
+    throw new RangeError('Use a multiple of four between 12 and 96 columns');
+  const rows = columns / 2;
+  const vertices: Vec3[] = [[0, 0, -1]];
+  for (let row = 1; row < rows; row++) {
+    const latitude = -Math.PI / 2 + (row * Math.PI) / rows;
+    for (let col = 0; col < columns; col++) {
+      const longitude = -Math.PI + (col * 2 * Math.PI) / columns;
+      vertices.push([
+        Math.cos(latitude) * Math.cos(longitude),
+        Math.cos(latitude) * Math.sin(longitude),
+        Math.sin(latitude)
+      ]);
+    }
+  }
+  const north = vertices.push([0, 0, 1]) - 1;
+  const at = (row: number, col: number) =>
+    row === 0 ? 0 : row === rows ? north : 1 + (row - 1) * columns + (col % columns);
+  const faces: number[][] = [];
+  for (let row = 0; row < rows; row++)
+    for (let col = 0; col < columns; col++) {
+      const cell = [at(row, col), at(row, col + 1), at(row + 1, col + 1), at(row + 1, col)];
+      faces.push([...new Set(cell)]);
+    }
+  // Root just north of the equator in Africa. Its southern edge points east,
+  // establishing an east-right, north-up flat frame without a camera spin.
+  const root = (rows / 2) * columns + Math.floor((columns * 200) / 360);
+  [faces[0], faces[root]] = [faces[root], faces[0]];
+  return {vertices, faces};
+}