@math.gl/geospatial 5.0.0-alpha.12 → 5.0.0-alpha.13

package/src/ellipsoid-helpers/ellipsoid-transform.ts

@@ -6,12 +6,18 @@
 
 import {NumericArray} from '@math.gl/types';
 import {Vector3, assert, equals as equalsEpsilon} from '@math.gl/core';
+import {
+  createLocalFrameBasis,
+  eastNorthUpBasisFromDirections,
+  localFrameToMatrix
+} from '@math.gl/core/local-frame';
 
 import type {Ellipsoid} from '../ellipsoid';
 
 const EPSILON14 = 1e-14;
 
 const scratchOrigin = new Vector3();
+const scratchBasis = createLocalFrameBasis();
 
 export type AxisDirection = 'up' | 'down' | 'north' | 'east' | 'south' | 'west';
 
@@ -105,6 +111,32 @@ export function localFrameToFixedFrame(
   // If x and y are zero, assume origin is at a pole, which is a special case.
   const atPole = equalsEpsilon(origin.x, 0.0, EPSILON14) && equalsEpsilon(origin.y, 0.0, EPSILON14);
 
+  // Only the qualified sphere/oblate basis is shared. Three-radius and center
+  // conventions keep the retained Cesium path, without changing its normal choice.
+  const radii = ellipsoid.radii;
+  if (
+    radii.x === radii.y &&
+    radii.x > 0 &&
+    radii.z > 0 &&
+    radii.z <= radii.x &&
+    (!atPole || origin.z !== 0)
+  ) {
+    const {east, up} = scratchAxisVectors;
+    if (atPole) {
+      east.set(0, 1, 0);
+      up.set(0, 0, Math.sign(origin.z));
+    } else {
+      east.set(-origin.y, origin.x, 0).normalize();
+      ellipsoid.geodeticSurfaceNormal(origin, up);
+    }
+    if (
+      !eastNorthUpBasisFromDirections(east, up, scratchBasis) ||
+      !localFrameToMatrix(scratchBasis, origin, firstAxis, secondAxis, thirdAxis, result)
+    )
+      throw new Error('Unsupported local frame');
+    return result;
+  }
+
   if (atPole) {
     // Look up axis value and adjust
     const sign = Math.sign(origin.z);
@@ -143,22 +175,35 @@ export function localFrameToFixedFrame(
     thirdAxisVector = scratchAxisVectors[thirdAxis];
   }
 
-  // TODO - assuming the result is column-major
-  result[0] = firstAxisVector.x;
-  result[1] = firstAxisVector.y;
-  result[2] = firstAxisVector.z;
+  // Snapshot the retained three-radius/center path too: application result setters
+  // can recursively invoke either path and overwrite all module scratch vectors.
+  const ax = firstAxisVector.x,
+    ay = firstAxisVector.y,
+    az = firstAxisVector.z;
+  const bx = secondAxisVector.x,
+    by = secondAxisVector.y,
+    bz = secondAxisVector.z;
+  const cx = thirdAxisVector.x,
+    cy = thirdAxisVector.y,
+    cz = thirdAxisVector.z;
+  const x = origin.x,
+    y = origin.y,
+    z = origin.z;
+  result[0] = ax;
+  result[1] = ay;
+  result[2] = az;
   result[3] = 0.0;
-  result[4] = secondAxisVector.x;
-  result[5] = secondAxisVector.y;
-  result[6] = secondAxisVector.z;
+  result[4] = bx;
+  result[5] = by;
+  result[6] = bz;
   result[7] = 0.0;
-  result[8] = thirdAxisVector.x;
-  result[9] = thirdAxisVector.y;
-  result[10] = thirdAxisVector.z;
+  result[8] = cx;
+  result[9] = cy;
+  result[10] = cz;
   result[11] = 0.0;
-  result[12] = origin.x;
-  result[13] = origin.y;
-  result[14] = origin.z;
+  result[12] = x;
+  result[13] = y;
+  result[14] = z;
   result[15] = 1.0;
   return result;
 }

package/src/ellipsoid-occluder.ts

@@ -0,0 +1,135 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original scaled-space analytic geometry. Consumer requirements: https://github.com/keplergl/kepler.gl/pull/3557 and https://github.com/keplergl/kepler.gl/pull/3593. No implementation code copied.
+
+/** The limb is center + axis1*cos(t) + axis2*sin(t), in input Cartesian units. */
+export type EllipsoidHorizon = {
+  center: number[];
+  axis1: number[];
+  axis2: number[];
+};
+
+/** Axis-aligned ellipsoid queries, independent of viewport and vector classes. */
+export class EllipsoidOccluder {
+  readonly radii: readonly number[];
+  readonly center: readonly number[];
+
+  constructor(radii: Readonly<ArrayLike<number>>, center: Readonly<ArrayLike<number>> = [0, 0, 0]) {
+    validateVector(radii);
+    validateVector(center);
+    if (Array.from(radii).some(value => value <= 0)) throw new RangeError('Radii must be positive');
+    this.radii = Object.freeze(Array.from(radii));
+    this.center = Object.freeze(Array.from(center));
+  }
+
+  /** Nonnegative ray parameter interval, including tangency and inside-origin rays.
+   * Direction need not be normalized. Undefined is a true miss; never clamps a miss
+   * to the limb. Result is untouched on miss. Distances equal parameters only for
+   * unit directions. Zero direction is a miss.
+   */
+  intersectRay(
+    origin: Readonly<ArrayLike<number>>,
+    direction: Readonly<ArrayLike<number>>,
+    result: number[] = [0, 0]
+  ): number[] | undefined {
+    validateVector(origin);
+    validateVector(direction);
+    const [x, y, z] = this.scalePoint(origin);
+    const dx = direction[0] / this.radii[0];
+    const dy = direction[1] / this.radii[1];
+    const dz = direction[2] / this.radii[2];
+    // Normalize in scaled space: avoid a tiny quadratic coefficient for ECEF rays.
+    const length = Math.hypot(dx, dy, dz);
+    if (length === 0 || !Number.isFinite(length)) return undefined;
+    const ux = dx / length,
+      uy = dy / length,
+      uz = dz / length;
+    const along = -(x * ux + y * uy + z * uz);
+    const perpendicular = Math.hypot(y * uz - z * uy, z * ux - x * uz, x * uy - y * ux);
+    if (perpendicular > 1) return undefined;
+    const half = Math.sqrt((1 - perpendicular) * (1 + perpendicular));
+    let near = along - half;
+    let far = along + half;
+    // Recover the small root by the root product rather than subtracting large terms.
+    const radius = Math.hypot(x, y, z);
+    if (!Number.isFinite(radius)) throw new RangeError('Scaled origin magnitude must be finite');
+    if (half > 0 && along > 0 && far !== 0) near = ((radius - 1) / far) * (radius + 1);
+    if (half > 0 && along < 0 && near !== 0) far = ((radius - 1) / near) * (radius + 1);
+    if (far < 0) return undefined;
+    result[0] = Math.max(0, Math.min(near, far)) / length;
+    result[1] = Math.max(0, far) / length;
+    return result;
+  }
+
+  /** True if the finite camera-to-point segment enters the solid interior.
+   * Surface contact/tangency alone is not occlusion. Works for elevated points;
+   * unlike a facing-normal test it does not discard visible points beyond the
+   * surface horizon. tolerance is a nonnegative scaled-space squared-radius margin.
+   */
+  isPointOccluded(
+    camera: Readonly<ArrayLike<number>>,
+    point: Readonly<ArrayLike<number>>,
+    tolerance = 1e-12
+  ): boolean {
+    validateVector(camera);
+    validateVector(point);
+    if (!Number.isFinite(tolerance) || tolerance < 0 || tolerance >= 1)
+      throw new RangeError('Tolerance must be in [0, 1)');
+    const a = this.scalePoint(camera);
+    const b = this.scalePoint(point);
+    const dx = b[0] - a[0],
+      dy = b[1] - a[1],
+      dz = b[2] - a[2];
+    const length = Math.hypot(dx, dy, dz);
+    if (!Number.isFinite(length)) throw new RangeError('Segment magnitude must be finite');
+    if (length === 0) return Math.hypot(...a) ** 2 < 1 - tolerance;
+    const ux = dx / length,
+      uy = dy / length,
+      uz = dz / length;
+    const distance = Math.max(0, Math.min(length, -(a[0] * ux + a[1] * uy + a[2] * uz)));
+    return (
+      Math.hypot(a[0] + distance * ux, a[1] + distance * uy, a[2] + distance * uz) ** 2 <
+      1 - tolerance
+    );
+  }
+
+  /** Exact apparent limb ellipse for an exterior camera; undefined on/inside surface. */
+  getHorizon(camera: Readonly<ArrayLike<number>>): EllipsoidHorizon | undefined {
+    validateVector(camera);
+    const scaled = this.scalePoint(camera);
+    const distance = Math.hypot(...scaled);
+    if (!Number.isFinite(distance)) throw new RangeError('Camera magnitude must be finite');
+    if (distance <= 1) return undefined;
+    const normal = scaled.map(value => value / distance);
+    // Choose a basis away from parallel to the normal, including polar views.
+    const reference = Math.abs(normal[2]) < 0.9 ? [0, 0, 1] : [0, 1, 0];
+    const u = cross(normal, reference);
+    const uLength = Math.hypot(...u);
+    const v = cross(
+      normal,
+      u.map(value => value / uLength)
+    );
+    const radius = Math.sqrt((1 - 1 / distance) * (1 + 1 / distance));
+    return {
+      center: normal.map((value, i) => this.center[i] + (this.radii[i] * value) / distance),
+      axis1: u.map((value, i) => (this.radii[i] * radius * value) / uLength),
+      axis2: v.map((value, i) => this.radii[i] * radius * value)
+    };
+  }
+
+  private scalePoint(point: Readonly<ArrayLike<number>>): number[] {
+    const result = this.radii.map((radius, i) => (point[i] - this.center[i]) / radius);
+    if (!result.every(Number.isFinite)) throw new RangeError('Scaled coordinates must be finite');
+    return result;
+  }
+}
+
+function validateVector(vector: Readonly<ArrayLike<number>>): void {
+  if (vector.length !== 3 || !Array.from(vector).every(Number.isFinite))
+    throw new RangeError('Expected three finite Cartesian components');
+}
+
+function cross(a: number[], b: number[]): number[] {
+  return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}

package/src/ellipsoid.ts

@@ -179,16 +179,13 @@ export class Ellipsoid {
     const y = 'x' in cartesian ? object.y : cartesian[1];
     const z = 'x' in cartesian ? object.z : cartesian[2];
     if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) return undefined;
-    // Shared inverse is qualified for the unambiguous surface/exterior domain.
-    // Interior/radial-fallback and non-spheroid behavior retain the Cesium kernel.
-    const a = this.radii.x,
-      b = this.radii.z;
-    const normSquared = (x / a) ** 2 + (y / a) ** 2 + (z / b) ** 2;
+    // Sphere/oblate conversion chooses the unique nearest normal, including interiors.
+    // Preserve legacy geometry magnitude limits; prolate/triaxial keep their own kernel.
     if (
       this.spheroidGeometry &&
-      Number.isFinite(normSquared) &&
-      normSquared >= 1 - 16 * Number.EPSILON &&
-      Number.isFinite(x * x + y * y + z * z)
+      Number.isFinite(x * x + y * y + z * z) &&
+      Number.isFinite(this.oneOverRadiiSquared.x) &&
+      Number.isFinite(this.oneOverRadiiSquared.z)
     ) {
       spheroidScratch.x = x;
       spheroidScratch.y = y;

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/index.ts

@@ -10,3 +10,15 @@ export type {GeodeticRegion, MakeOBBFromRegionOptions} from './make-obb-from-reg
 export {isWGS84} from './type-utils';
 
 export type {SpheroidParameters} from '@math.gl/types';
+
+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 {
+  getGeographicTile,
+  getGeographicTileBounds,
+  getGeographicTileRanges
+} from './geographic-tiles';
+export type {GeographicTile, GeographicTileRange} from './geographic-tiles';