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

package/src/geographic-seams/subdivide-cut.ts

@@ -0,0 +1,203 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original source-interval and generated-boundary adapter over math.gl's existing adaptive subdivision engine; solver notices remain attached.
+import {
+  subdividePolyline,
+  type SubdividePolylineOptions,
+  type SubdividedPolyline,
+  type PolylineEdgeSampler
+} from '@math.gl/geometry';
+import {GeodesicPath} from '../geodesic-path';
+import {RhumbPath} from '../rhumb-path';
+import {EllipsoidGeodesic} from '../ellipsoid-geodesic';
+import {EllipsoidRhumb} from '../ellipsoid-rhumb';
+import {EllipsoidMetrics} from '../ellipsoid-metrics';
+import {Context, same, createEdges} from './edge';
+import {cutOptions, type GeographicClipOptions} from './cut-options';
+import {GeographicSeamError, type GeographicPolygonRing} from './types';
+import type {GeographicCutRing, GeographicCutEdge} from '../geographic-cuts';
+export type SubdivideGeographicCutRingOptions = GeographicClipOptions &
+  Omit<SubdividePolylineOptions, 'createEdgeSampler'>;
+export type SubdividedGeographicCutRing = SubdividedPolyline & {edges: GeographicCutEdge[]};
+/** Resample original curves after clipping; generated parallels remain parallels.
+ * Use the same model/axes/input rings as clipping. Sizes 2/3 and target sizes 2/3.
+ * maxSegmentLength is in solver axis units for curves, degrees for linear geometry.
+ */
+export function subdivideGeographicCutRing(
+  inputs: readonly GeographicPolygonRing[],
+  ring: GeographicCutRing,
+  options: SubdivideGeographicCutRingOptions
+): SubdividedGeographicCutRing {
+  const settings = {...options};
+  const turns = inputs.map(r => (r.longitudeTurns ? Array.from(r.longitudeTurns) : undefined));
+  const config = cutOptions(settings),
+    context = new Context(config.options),
+    size = settings.size ?? 2;
+  if (size !== 2 && size !== 3)
+    throw new GeographicSeamError('input', 'Cut subdivision supports coordinate sizes 2 or 3');
+  const points = inputs.map(r => {
+    const p = context.read(r.positions);
+    if (p.length > 1 && same(p[0], p[p.length - 1])) p.pop();
+    return p;
+  });
+  const positions = context.read(ring.positions);
+  if (
+    !positions.length ||
+    ring.edges.length !== positions.length - 1 ||
+    !same(positions[0], positions[positions.length - 1])
+  )
+    throw new GeographicSeamError(
+      'input',
+      'Expected a closed cut ring with one descriptor per edge'
+    );
+  const descriptors = ring.edges.map(e =>
+    e.kind === 'source' ? {kind: 'source' as const, source: {...e.source}} : {...e}
+  );
+  const sources = new Map<string, GeodesicPath | RhumbPath | PolylineEdgeSampler>();
+  let geodesic = config.options.geodesic;
+  const getGeodesic = () => (geodesic ??= new EllipsoidGeodesic(config.axes));
+  let rhumb = config.options.rhumb;
+  const getRhumb = () => (rhumb ??= new EllipsoidRhumb(config.axes));
+  const result = subdividePolyline(new Float64Array(positions.flat()), {
+    ...settings,
+    transform: p => {
+      context.tick();
+      return settings.transform(p);
+    },
+    size,
+    createEdgeSampler: (a, b, index) => {
+      const descriptor = descriptors[index];
+      const endpoint = (sample: (t: number) => ArrayLike<number>, t: number) =>
+        t === 0 ? a.slice() : t === 1 ? b.slice() : sample(t);
+      if (descriptor.kind === 'source') {
+        const s = descriptor.source,
+          p = points[s.ringIndex];
+        if (
+          !Number.isInteger(s.ringIndex) ||
+          !p ||
+          !Number.isInteger(s.edgeIndex) ||
+          s.edgeIndex < 0 ||
+          s.edgeIndex >= p.length ||
+          ![s.startFraction, s.endFraction, s.longitudeShift].every(Number.isFinite) ||
+          Math.min(s.startFraction, s.endFraction) < 0 ||
+          Math.max(s.startFraction, s.endFraction) > 1 ||
+          !Number.isSafeInteger(s.longitudeShift / 360)
+        )
+          throw new GeographicSeamError('input', 'Invalid cut source interval');
+        const key = s.ringIndex + ':' + s.edgeIndex;
+        let path = sources.get(key);
+        if (!path) {
+          const first = p[s.edgeIndex],
+            last = p[(s.edgeIndex + 1) % p.length],
+            edgeTurns = turns[s.ringIndex]?.[s.edgeIndex] ?? 0;
+          if (settings.edgeModel === 'geodesic')
+            path = new GeodesicPath(first, last, {geodesic: getGeodesic()});
+          else if (settings.edgeModel === 'rhumb')
+            path = new RhumbPath(first, last, {rhumb: getRhumb(), longitudeTurns: edgeTurns});
+          else {
+            const edge = createEdges(
+              first,
+              last,
+              first,
+              s.edgeIndex,
+              s.ringIndex,
+              edgeTurns,
+              context
+            )[0];
+            path = {
+              length: Math.hypot(...edge.b.map((v, i) => v - edge.a[i])),
+              sample: edge.sample
+            };
+          }
+          sources.set(key, path);
+        }
+        const curve = path;
+        return {
+          length: curve.length * Math.abs(s.endFraction - s.startFraction),
+          sample: t =>
+            endpoint(u => {
+              const f = s.startFraction + (s.endFraction - s.startFraction) * u,
+                p = Array.from(curve.sample(f));
+              p[0] += s.longitudeShift;
+              return p;
+            }, t)
+        };
+      }
+      if (descriptor.kind === 'pole') {
+        if (
+          Math.abs(descriptor.latitude) !== 90 ||
+          a[1] !== descriptor.latitude ||
+          b[1] !== descriptor.latitude
+        )
+          throw new GeographicSeamError('input', 'Invalid pole connector');
+        return {length: 0, sample: t => a.map((v, i) => v * (1 - t) + b[i] * t)};
+      }
+      if (
+        descriptor.kind === 'parallel'
+          ? a[1] !== descriptor.latitude || b[1] !== descriptor.latitude
+          : descriptor.kind !== 'meridian' ||
+            a[0] !== descriptor.longitude ||
+            b[0] !== descriptor.longitude
+      )
+        throw new GeographicSeamError('input', 'Boundary descriptor does not match its endpoints');
+      if (settings.edgeModel === 'linear')
+        return {
+          length: Math.hypot(...a.map((v, i) => v - b[i])),
+          sample: t => a.map((v, i) => v * (1 - t) + b[i] * t)
+        };
+      if (descriptor.kind === 'parallel') {
+        const path = new RhumbPath(a, b, {rhumb: getRhumb(), longitudeMode: 'unrolled'});
+        return {
+          length: path.length,
+          sample: t =>
+            endpoint(u => {
+              const p = path.sample(u);
+              p[1] = descriptor.latitude;
+              return p;
+            }, t)
+        };
+      }
+      const metrics = new EllipsoidMetrics(config.axes),
+        m0 = metrics.meridianDistance(a[1]),
+        m1 = metrics.meridianDistance(b[1]);
+      return {
+        length: Math.abs(m1 - m0),
+        sample: t =>
+          endpoint(u => {
+            const p = a.map((v, i) => v * (1 - u) + b[i] * u);
+            p[0] = descriptor.longitude;
+            p[1] = metrics.latitudeFromAuxiliary(
+              ((m0 * (1 - u) + m1 * u) / metrics.quarterMeridian) * 90,
+              'rectifying'
+            );
+            return p;
+          }, t)
+      };
+    }
+  });
+  const edges: GeographicCutEdge[] = [];
+  for (let i = 1; i < result.segmentIndices.length; i++) {
+    const index = result.segmentIndices[i],
+      edge = descriptors[index],
+      lo = result.segmentIndices[i - 1] === index ? result.segmentFractions[i - 1] : 0,
+      hi = result.segmentFractions[i];
+    edges.push(
+      edge.kind === 'source'
+        ? {
+            kind: 'source',
+            source: {
+              ...edge.source,
+              startFraction:
+                edge.source.startFraction +
+                (edge.source.endFraction - edge.source.startFraction) * lo,
+              endFraction:
+                edge.source.startFraction +
+                (edge.source.endFraction - edge.source.startFraction) * hi
+            }
+          }
+        : {...edge}
+    );
+  }
+  return {...result, edges};
+}

package/src/geographic-seams/types.ts

@@ -0,0 +1,67 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import type {EllipsoidGeodesic} from '../ellipsoid-geodesic';
+import type {EllipsoidRhumb} from '../ellipsoid-rhumb';
+
+export type GeographicSeamOptions = {
+  /** Explicit edge semantics; no guessing from whether an array is closed. */
+  edgeModel: 'linear' | 'geodesic' | 'rhumb';
+  /** Linear edges only. Default supplied; shortest chooses the short longitude interval. */
+  linearLongitude?: 'supplied' | 'shortest';
+  /** Right edge of the 360-degree output chart. Default 180. */
+  seamLongitude?: number;
+  /** Coordinate stride, including linearly interpolated scalar attributes. Default 2. */
+  size?: number;
+  geodesic?: EllipsoidGeodesic;
+  rhumb?: EllipsoidRhumb;
+  /** Bound both working and output vertices. Default 65536. */
+  maxVertices?: number;
+  /** Bound edge visits and solver/root evaluations. Default 1000000. */
+  maxWork?: number;
+  /** Maximum bisections per root. Default 64, maximum 128. */
+  maxIterations?: number;
+};
+export type GeographicEdgeSource = {
+  ringIndex: number;
+  edgeIndex: number;
+  startFraction: number;
+  endFraction: number;
+  /** Add to the independently unrolled original edge longitude when resampling. */
+  longitudeShift: number;
+};
+export type GeographicSeamRing = {
+  /** Packed coordinates; polygon rings are explicitly closed. Caller-owned storage. */
+  positions: Float64Array;
+  /** One per output edge; null denotes a generated seam/pole connector. */
+  edges: (GeographicEdgeSource | null)[];
+};
+export type GeographicSeamPolyline = {
+  positions: Float64Array;
+  /** Line edges always retain an original source interval. */
+  edges: GeographicEdgeSource[];
+  /** Original unrolled world index; polyline positions are not necessarily closed. */
+  world: number;
+};
+export type GeographicPolygonRing = {
+  positions: ArrayLike<number>;
+  /** Rhumb turns per original edge, including the closing edge. */
+  longitudeTurns?: readonly number[];
+  /** Required for a once-winding polar ring. Other complements are not inferred. */
+  pole?: 'north' | 'south';
+  /** Explicit values for generated pole vertices when size > 2. */
+  poleAttributes?: readonly number[];
+};
+export type GeographicSeamPolygon = {
+  /** Outer first, then holes. Outer winding follows the input; holes are opposite. */
+  rings: GeographicSeamRing[];
+};
+export class GeographicSeamError extends RangeError {
+  constructor(
+    readonly reason: 'input' | 'precision' | 'topology' | 'limit',
+    message: string
+  ) {
+    super(message);
+    this.name = 'GeographicSeamError';
+  }
+}

package/src/geographic-seams.ts

@@ -0,0 +1,81 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original geographic edge-model seam adapters; existing solver attributions are retained.
+import {Context, createEdges, cut, same, worldAt, chartPoint} from './geographic-seams/edge';
+import type {
+  GeographicSeamOptions,
+  GeographicSeamPolyline,
+  GeographicEdgeSource
+} from './geographic-seams/types';
+import {GeographicSeamError} from './geographic-seams/types';
+export {splitGeographicPolygon} from './geographic-seams/polygon';
+export {GeographicSeamError} from './geographic-seams/types';
+export type {
+  GeographicSeamOptions,
+  GeographicEdgeSource,
+  GeographicSeamRing,
+  GeographicSeamPolyline,
+  GeographicPolygonRing,
+  GeographicSeamPolygon
+} from './geographic-seams/types';
+
+/** Split declared linear/geodesic/rhumb edges at a configurable longitude seam.
+ * Attributes interpolate by source-edge fraction. Each part retains its original
+ * world index and original-edge source intervals. Pole passages split the line.
+ */
+export function splitGeographicPolyline(
+  input: ArrayLike<number>,
+  options: GeographicSeamOptions & {
+    longitudeTurns?: readonly number[];
+  }
+): GeographicSeamPolyline[] {
+  const context = new Context(options),
+    points = context.read(input);
+  const turns = options.longitudeTurns
+    ? Array.from(options.longitudeTurns)
+    : new Array(Math.max(0, points.length - 1)).fill(0);
+  if (turns.length !== Math.max(0, points.length - 1))
+    throw new GeographicSeamError('input', 'Expected one turn count per line edge');
+  if (!points.length) return [];
+  if (points.length === 1) {
+    context.addVertices(1);
+    const world = worldAt(points[0][0], context),
+      p = chartPoint(points[0], world, context);
+    return [{positions: new Float64Array(p), edges: [], world}];
+  }
+  const parts: {points: number[][]; edges: GeographicEdgeSource[]; world: number}[] = [];
+  let cursor = points[0];
+  for (let i = 1; i < points.length; i++) {
+    const edges = createEdges(
+      cursor,
+      points[i],
+      points[i - 1],
+      i - 1,
+      0,
+      turns[i - 1],
+      context,
+      false
+    );
+    for (const original of edges) {
+      if (!original.source) continue; // Pole aliases are separate line endpoints.
+      for (const {edge, world} of cut(original, context)) {
+        const previous = parts[parts.length - 1];
+        if (
+          previous &&
+          previous.world === world &&
+          same(previous.points[previous.points.length - 1], edge.a)
+        ) {
+          previous.points.push(edge.b);
+          previous.edges.push(edge.source);
+        } else parts.push({points: [edge.a, edge.b], edges: [edge.source], world});
+      }
+    }
+    cursor = edges[edges.length - 1].b;
+  }
+  return parts.map(part => ({
+    positions: new Float64Array(part.points.flat()),
+    edges: part.edges,
+    world: part.world
+  }));
+}

package/src/geographic-tiles.ts

@@ -0,0 +1,87 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import {splitGlobeBounds, type GlobeBounds} from './globe-horizon-bounds';
+
+/** Equal-angle longitude/latitude grid: one world tile at level zero, north-origin Y. */
+export type GeographicTile = {x: number; y: number; level: number};
+/** Inclusive integer tile ranges. Ranges are disjoint and ordered by minX. */
+export type GeographicTileRange = {minX: number; maxX: number; minY: number; maxY: number};
+
+/** Geographic degree bounds of an equal-angle tile, not Web Mercator XYZ. */
+export function getGeographicTileBounds(tile: GeographicTile): GlobeBounds {
+  const size = gridSize(tile.level);
+  if (![tile.x, tile.y].every(v => Number.isInteger(v) && v >= 0 && v < size))
+    throw new RangeError('Tile coordinates must be integers inside the level grid');
+  return [
+    -180 + (360 * tile.x) / size,
+    90 - (180 * (tile.y + 1)) / size,
+    -180 + (360 * (tile.x + 1)) / size,
+    90 - (180 * tile.y) / size
+  ];
+}
+
+/** Address a point in degrees. Interior edges belong to the east/south tile. */
+export function getGeographicTile(
+  longitude: number,
+  latitude: number,
+  level: number
+): GeographicTile {
+  const size = gridSize(level);
+  if (
+    !Number.isFinite(longitude) ||
+    longitude < -180 ||
+    longitude > 180 ||
+    !Number.isFinite(latitude) ||
+    latitude < -90 ||
+    latitude > 90
+  )
+    throw new RangeError('Expected longitude in [-180, 180] and latitude in [-90, 90]');
+  return {
+    x: Math.min(size - 1, Math.floor(((longitude + 180) / 360) * size)),
+    y: Math.min(size - 1, Math.floor(((90 - latitude) / 180) * size)),
+    level
+  };
+}
+
+/** Cover a degree rectangle without enumerating tiles, including wrapped longitude.
+ * Positive-area queries exclude edge-only neighbors; zero-width/height queries use
+ * point-address edge ownership. Both +/-180 spellings of the seam stay explicit.
+ */
+export function getGeographicTileRanges(bounds: GlobeBounds, level: number): GeographicTileRange[] {
+  const size = gridSize(level);
+  const split = splitGlobeBounds(bounds);
+  const positiveWidth = split.filter(([west, , east]) => east > west);
+  const rectangles = positiveWidth.length ? positiveWidth : split;
+  const intervals = rectangles
+    .map(([west, south, east, north]) => {
+      const start = getGeographicTile(west, north, level);
+      return {
+        minX: start.x,
+        maxX:
+          west === east
+            ? start.x
+            : Math.max(start.x, Math.min(size - 1, Math.ceil(((east + 180) / 360) * size) - 1)),
+        minY: start.y,
+        maxY:
+          south === north
+            ? start.y
+            : Math.max(start.y, Math.min(size - 1, Math.ceil(((90 - south) / 180) * size) - 1))
+      };
+    })
+    .sort((a, b) => a.minX - b.minX);
+  const result: GeographicTileRange[] = [];
+  for (const range of intervals) {
+    const previous = result[result.length - 1];
+    if (previous && range.minX <= previous.maxX + 1)
+      previous.maxX = Math.max(previous.maxX, range.maxX);
+    else result.push(range);
+  }
+  return result;
+}
+
+function gridSize(level: number): number {
+  if (!Number.isInteger(level) || level < 0 || level > 30)
+    throw new RangeError('Level must be an integer from 0 through 30');
+  return 2 ** level;
+}

package/src/globe-horizon-bounds.ts

@@ -0,0 +1,68 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original spherical-cap extrema; requirements from https://github.com/keplergl/kepler.gl/pull/3557. No sampled viewport or upstream implementation copied.
+
+/** Degrees [west, south, east, north]; west > east means a dateline crossing. */
+export type GlobeBounds = readonly [number, number, number, number];
+
+/** Conservative geographic extent of every visible surface point on a sphere.
+ * Cartesian X points to longitude 0, Y to longitude 90, Z north. Covers the
+ * entire horizon cap, not just the screen: safe overfetch, not viewport-tight.
+ * Returns undefined on/inside the sphere. Radius and camera use matching units.
+ */
+export function getGlobeHorizonBounds(
+  camera: Readonly<ArrayLike<number>>,
+  radius: number
+): GlobeBounds | undefined {
+  if (
+    camera.length !== 3 ||
+    !Array.from(camera).every(Number.isFinite) ||
+    !Number.isFinite(radius) ||
+    radius <= 0
+  )
+    throw new RangeError('Expected a finite camera and positive sphere radius');
+  const distance = Math.hypot(camera[0], camera[1], camera[2]);
+  if (!Number.isFinite(distance)) throw new RangeError('Camera magnitude must be finite');
+  if (distance <= radius) return undefined;
+  const latitude = Math.atan2(camera[2], Math.hypot(camera[0], camera[1]));
+  const longitude = Math.atan2(camera[1], camera[0]);
+  const angle = Math.acos(radius / distance);
+  const degrees = 180 / Math.PI;
+  // Outward padding protects tangent and near-pole limits from floating rounding.
+  const padding = 1e-10;
+  const south = Math.max(-90, (latitude - angle) * degrees - padding);
+  const north = Math.min(90, (latitude + angle) * degrees + padding);
+  if (Math.abs(latitude) + angle >= Math.PI / 2 - 1e-12) return [-180, south, 180, north];
+  const extent = Math.asin(Math.min(1, Math.sin(angle) / Math.cos(latitude))) * degrees + padding;
+  return [wrap(longitude * degrees - extent), south, wrap(longitude * degrees + extent), north];
+}
+
+/** Split wrapped bounds into protocol-safe rectangles (e.g. EPSG:4326 WMS).
+ * No screen sampling, image caching or request policy is implied.
+ */
+export function splitGlobeBounds(bounds: GlobeBounds): GlobeBounds[] {
+  const [west, south, east, north] = bounds;
+  if (
+    bounds.length !== 4 ||
+    !bounds.every(Number.isFinite) ||
+    west < -180 ||
+    west > 180 ||
+    east < -180 ||
+    east > 180 ||
+    south < -90 ||
+    north > 90 ||
+    south > north
+  )
+    throw new RangeError('Invalid degree bounds');
+  return west <= east
+    ? [[west, south, east, north]]
+    : [
+        [west, south, 180, north],
+        [-180, south, east, north]
+      ];
+}
+
+function wrap(longitude: number): number {
+  return ((((longitude + 180) % 360) + 360) % 360) - 180;
+}

package/src/globe.ts

@@ -0,0 +1,31 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {LngLatRectangle} from './lng-lat-rectangle';
+export {makeOBBFromRegion} from './make-obb-from-region';
+export type {GeodeticRegion, MakeOBBFromRegionOptions} from './make-obb-from-region';
+export {EllipsoidOccluder} from './ellipsoid-occluder';
+export type {EllipsoidHorizon} from './ellipsoid-occluder';
+export {getGlobeHorizonBounds, splitGlobeBounds} from './globe-horizon-bounds';
+export type {GlobeBounds} from './globe-horizon-bounds';
+
+export {subdivideGlobeMesh} from './subdivide-globe-mesh';
+export type {SubdivideGlobeMeshOptions} from './subdivide-globe-mesh';
+export {subdivideGeodesicPolyline} from './subdivide-geodesic-polyline';
+export type {SubdivideGeodesicPolylineOptions} from './subdivide-geodesic-polyline';
+export {subdivideRhumbPolyline} from './subdivide-rhumb-polyline';
+export type {SubdivideRhumbPolylineOptions} from './subdivide-rhumb-polyline';
+export {
+  splitGeographicPolyline,
+  splitGeographicPolygon,
+  GeographicSeamError
+} from './geographic-seams';
+export type {
+  GeographicSeamOptions,
+  GeographicEdgeSource,
+  GeographicSeamRing,
+  GeographicSeamPolyline,
+  GeographicPolygonRing,
+  GeographicSeamPolygon
+} from './geographic-seams';