@math.gl/geospatial 5.0.0-alpha.18 → 5.0.0-alpha.19

package/src/projection/temporal.ts

@@ -0,0 +1,133 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original source-sampled temporal component arithmetic; no upstream code or model data copied.
+import {inverseDisplacement} from './experimental/deformation-inverse';
+import {createSpatialDeformationModel} from './experimental/spatial-deformation';
+import type {DeformationModel, DeformationModelOptions} from './experimental/deformation';
+import type {ProjectionPoint} from './experimental/types';
+
+/** ENU amplitudes in the component's explicitly declared units. Lon/lat are radians. */
+export type DeformationField = {
+  sample(longitude: number, latitude: number, output: ProjectionPoint): boolean;
+};
+export type TemporalFunction =
+  | {readonly type: 'velocity'}
+  | {readonly type: 'acceleration'; readonly referenceEpoch: number}
+  | {readonly type: 'step'; readonly epoch: number}
+  | {readonly type: 'exponential'; readonly epoch: number; readonly timeConstantYears: number};
+export type TemporalDeformationComponent = {
+  readonly id: string;
+  readonly field: DeformationField;
+  readonly units: 'm/year' | 'm/year^2' | 'm';
+  readonly timeFunction: TemporalFunction;
+};
+export type TemporalDeformationOptions = Omit<DeformationModelOptions, 'grid'> & {
+  readonly components: readonly TemporalDeformationComponent[];
+};
+type Prepared = {sample: DeformationField['sample']; law: TemporalFunction};
+
+/** Difference of right-continuous displacement coefficients, not a trajectory integral. */
+function temporalDifference(law: TemporalFunction, source: number, target: number): number {
+  const dt = target - source;
+  switch (law.type) {
+    case 'velocity':
+      return dt;
+    case 'acceleration':
+      return dt * (source - law.referenceEpoch + dt / 2);
+    case 'step':
+      return Number(target >= law.epoch) - Number(source >= law.epoch);
+    case 'exponential': {
+      if (target < source) return -temporalDifference(law, target, source);
+      if (target <= law.epoch) return 0;
+      if (source <= law.epoch) {
+        const elapsed = target - law.epoch;
+        return Number.isFinite(elapsed) ? -Math.expm1(-elapsed / law.timeConstantYears) : NaN;
+      }
+      if (!Number.isFinite(source - law.epoch)) return NaN;
+      return (
+        Math.exp(-(source - law.epoch) / law.timeConstantYears) *
+        -Math.expm1(-dt / law.timeConstantYears)
+      );
+    }
+  }
+}
+function sampleComponents(
+  components: readonly Prepared[],
+  longitude: number,
+  latitude: number,
+  output: ProjectionPoint,
+  source: number,
+  target: number
+): boolean {
+  let east = 0,
+    north = 0,
+    up = 0;
+  for (let i = 0; i < components.length; i++) {
+    const component = components[i],
+      weight = temporalDifference(component.law, source, target);
+    // All fields must cover the source, even if their interval coefficient is zero.
+    if (!Number.isFinite(weight)) throw new Error('Non-finite temporal coefficient');
+    output.x = NaN;
+    output.y = NaN;
+    output.z = NaN;
+    const covered = component.sample(longitude, latitude, output);
+    if (covered !== true) {
+      if (covered !== false) throw new Error('Synchronous boolean temporal coverage required');
+      return false;
+    }
+    if (!Number.isFinite(output.x) || !Number.isFinite(output.y) || !Number.isFinite(output.z))
+      throw new Error('Finite temporal component required');
+    east += weight * output.x;
+    north += weight * output.y;
+    up += weight * output.z;
+  }
+  if (!Number.isFinite(east) || !Number.isFinite(north) || !Number.isFinite(up))
+    throw new Error('Non-finite temporal displacement');
+  output.x = east;
+  output.y = north;
+  output.z = up;
+  return true;
+}
+/** Sum time-varying source-position ENU components; inverse solves that same map. */
+export function createTemporalDeformationModel(
+  options: TemporalDeformationOptions
+): DeformationModel {
+  if (!Array.isArray(options.components) || !options.components.length)
+    throw new Error('Nonempty temporal components required');
+  const ids = new Set<string>();
+  const components = options.components.map(component => {
+    if (
+      typeof component.id !== 'string' ||
+      !component.id.trim() ||
+      ids.has(component.id) ||
+      typeof component.field?.sample !== 'function'
+    )
+      throw new Error('Unique temporal component id and prepared field required');
+    ids.add(component.id);
+    const law = {...component.timeFunction};
+    if (!law || !['velocity', 'acceleration', 'step', 'exponential'].includes(law.type))
+      throw new Error('Unsupported temporal function');
+    const units =
+      law.type === 'velocity' ? 'm/year' : law.type === 'acceleration' ? 'm/year^2' : 'm';
+    if (component.units !== units)
+      throw new Error('Temporal component units do not match time function');
+    if (law.type === 'acceleration' && !Number.isFinite(law.referenceEpoch))
+      throw new Error('Finite acceleration referenceEpoch required');
+    if ((law.type === 'step' || law.type === 'exponential') && !Number.isFinite(law.epoch))
+      throw new Error('Finite event epoch required');
+    if (
+      law.type === 'exponential' &&
+      (!Number.isFinite(law.timeConstantYears) || law.timeConstantYears <= 0)
+    )
+      throw new Error('Positive finite relaxation time required');
+    return {sample: component.field.sample.bind(component.field), law: Object.freeze(law)};
+  });
+  return createSpatialDeformationModel(
+    options,
+    (longitude, latitude, output, source, target) =>
+      sampleComponents(components, longitude, latitude, output, source, target),
+    false,
+    inverseDisplacement
+  );
+}

package/src/projection/transform-analysis.ts

@@ -0,0 +1,169 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {normalizeCRS} from './experimental/crs/normalize';
+import {ProjectionTransform} from './experimental/typescript-projection';
+import {ProjectionAnalysis} from './analysis';
+import type {ProjectionTransformCreateOptions} from './experimental/typescript-projection';
+import type {TypeScriptCRSInput} from './experimental/crs/spatial-reference';
+import type {NormalizedCRS} from './experimental/crs/types';
+import type {ProjectionContext, ProjectionPlugin, ProjectionPoint} from './experimental/types';
+import type {ProjectionDomain, ProjectionFactors, ProjectionJacobian} from './analysis';
+
+/** Full CRS pipeline analysis at a geographic anchor, with a separately selected ground metric. */
+export type ProjectionTransformAnalysisOptions = Omit<
+  ProjectionTransformCreateOptions,
+  'enforceAxis'
+> & {
+  /** Geographic reference defining the anchor longitude, latitude and height. Defaults to from
+   * only when from is geographic. Required for projected/geocentric source coordinates.
+   */
+  geographicFrom?: TypeScriptCRSInput;
+  /** Application-qualified geographic rectangle, in radians relative to geographicFrom's meridian. */
+  domain: ProjectionDomain;
+  /** Constant anchor height, in meters in geographicFrom's vertical reference. Default 0. */
+  height?: number;
+  /** Physical ground metric; defaults to the geographic anchor's ellipsoid. */
+  groundEllipsoid?: Pick<ProjectionContext, 'semiMajorAxis' | 'eccentricitySquared'>;
+  /** Central difference step in radians. Default 1e-4. */
+  step?: number;
+  /** Agreement tolerance for the two derivative stencils. Default 1e-6. */
+  derivativeTolerance?: number;
+};
+
+/** Derivatives of a prepared CRS pair, composed from a geographic anchor into the source CRS.
+ * Output axes are physical east/north in meters; input derivatives are per geographic radian.
+ * Horizontal derivatives hold anchor height fixed. This is not an inverse coordinate API.
+ */
+export interface ProjectionTransformAnalysis {
+  /** Captured geographic domain, in radians. */
+  readonly domain: ProjectionDomain;
+  /** Check finite anchor angles against the declared domain. */
+  contains(longitude: number, latitude: number): boolean;
+  /** Write the complete horizontal pipeline derivative; false leaves result untouched. */
+  jacobian(longitude: number, latitude: number, result: ProjectionJacobian): boolean;
+  /** Write cartographic factors against the selected ground metric; false leaves result untouched. */
+  factors(longitude: number, latitude: number, result: ProjectionFactors): boolean;
+}
+
+/** Prepare full CRS-pair analysis without loading algorithms during derivative evaluation.
+ * Imports no projection catalogue. Pass algorithms, parser plugins and grids explicitly, as
+ * for ProjectionTransform.create. All CRS stages execute through the prepared transforms.
+ * Lossy pipelines, nongeographic anchors and nonplanar targets reject at construction.
+ * Domain, singularity, derivative agreement and output ownership follow ProjectionAnalysis.
+ */
+export async function createProjectionTransformAnalysis(
+  options: ProjectionTransformAnalysisOptions
+): Promise<ProjectionTransformAnalysis> {
+  const from = options.from ?? 'WGS84';
+  const source = normalizeCRS(from, options);
+  const geographicFrom =
+    options.geographicFrom ?? (source.kind === 'geographic' ? from : undefined);
+  if (!geographicFrom) throw new Error('Projected source analysis requires geographicFrom');
+  const geographic = normalizeCRS(geographicFrom, options);
+  const target = normalizeCRS(options.to ?? 'WGS84', options);
+  const height = options.height ?? 0;
+  if (geographic.kind !== 'geographic' || target.kind !== 'projected' || !Number.isFinite(height)) {
+    throw new Error(
+      'Transform analysis requires a geographic anchor, planar target and finite height'
+    );
+  }
+  const anchorTransform = await ProjectionTransform.create({
+    ...options,
+    from: geographicFrom,
+    to: from,
+    enforceAxis: true
+  });
+  const transform = await ProjectionTransform.create({...options, enforceAxis: true});
+  if (anchorTransform.lossy || transform.lossy) {
+    throw new Error('Transform analysis requires lossless CRS pipelines');
+  }
+  const input: number[] = [0, 0, 0];
+  const anchored: number[] = [0, 0, 0];
+  const output: number[] = [0, 0, 0];
+  const projection: ProjectionPlugin = {
+    name: 'prepared-crs-analysis',
+    parameters: [],
+    create: () => ({
+      forward: () => {
+        throw new Error('Use the mutable analysis hook');
+      },
+      inverse: () => {
+        throw new Error('Transform analysis does not invert horizontal slices');
+      },
+      inverseInPlace: () => {
+        throw new Error('Transform analysis does not invert horizontal slices');
+      },
+      forwardInPlace(point) {
+        writeGeographicInput(point.x, point.y, height, geographic, input);
+        anchorTransform.projectToSync(input, anchored);
+        transform.projectToSync(anchored, output);
+        readProjectedOutput(output, target, point);
+      }
+    })
+  };
+  const analysis = new ProjectionAnalysis({
+    projection,
+    // The adapter already produces physical meters through prepared transforms. Its
+    // context supplies only the ground metric and numerical derivative scale.
+    context: {...(options.groundEllipsoid ?? geographic.ellipsoid), parameters: {}},
+    domain: options.domain,
+    step: options.step,
+    derivativeTolerance: options.derivativeTolerance
+  });
+  return {
+    domain: analysis.domain,
+    contains: analysis.contains.bind(analysis),
+    jacobian: analysis.jacobian.bind(analysis),
+    factors: analysis.factors.bind(analysis)
+  };
+}
+
+/** Match the enforced stored-axis convention of both prepared transforms. */
+function writeGeographicInput(
+  longitude: number,
+  latitude: number,
+  height: number,
+  crs: NormalizedCRS,
+  point: number[]
+): void {
+  const axis = crs.storedAxis ?? crs.axis;
+  for (let i = 0; i < 3; i++) {
+    const direction = axis[i];
+    const value =
+      direction === 'e' || direction === 'w'
+        ? longitude / crs.angularUnit
+        : direction === 'n' || direction === 's'
+          ? latitude / crs.angularUnit
+          : height / crs.verticalUnit;
+    const signed = direction === 'w' || direction === 's' || direction === 'd' ? -value : value;
+    point[i] = signed;
+  }
+}
+
+/** Normalize declared target axes/units to physical EN, including axes stored in the third slot. */
+function readProjectedOutput(
+  input: readonly number[],
+  crs: NormalizedCRS,
+  result: ProjectionPoint
+): void {
+  const axis = crs.storedAxis ?? crs.axis;
+  for (let i = 0; i < 3; i++) {
+    const value = input[i]! * crs.toMeter;
+    switch (axis[i]) {
+      case 'e':
+        result.x = value;
+        break;
+      case 'w':
+        result.x = -value;
+        break;
+      case 'n':
+        result.y = value;
+        break;
+      case 's':
+        result.y = -value;
+        break;
+    }
+  }
+}

package/src/projection/types.ts

@@ -0,0 +1,79 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ProjectionTransformOptions} from './experimental/typescript-projection';
+import type {ProjectionPlugin} from './experimental/types';
+import type {ProjectionDescriptor} from './experimental/projection-descriptor';
+import type {ProjectionCoordinate, ProjectionOutput} from './experimental/scalar-output';
+import type {ProjectionArray} from './experimental/typescript-projection';
+
+type Registration = ProjectionPlugin | ProjectionDescriptor;
+
+/** Reusable projection algorithms, CRS readers, aliases and grids. */
+export type ProjectionEngineOptions<P extends Registration = ProjectionPlugin> = Omit<
+  ProjectionTransformOptions<P>,
+  'from' | 'to'
+>;
+
+/** CRS pair and behavior for an independent transform. */
+export type CreateProjectionOptions = Pick<
+  ProjectionTransformOptions,
+  'from' | 'to' | 'enforceAxis' | 'mode'
+>;
+
+/** Backend-independent factory; import from the runtime-free /types entry point. */
+export interface ProjectionEngine {
+  createProjection(options?: CreateProjectionOptions): Projection;
+  createProjectionAsync(options?: CreateProjectionOptions): Promise<PreparedProjection>;
+}
+
+/** A CRS-pair transform. Sync methods never load algorithms; preload deferred transforms first. */
+export interface Projection {
+  readonly lossy?: boolean;
+  preload(): Promise<unknown>;
+  project(coordinate: readonly number[]): number[] | Promise<number[]>;
+  unproject(coordinate: readonly number[]): number[] | Promise<number[]>;
+  projectTo<T extends ProjectionOutput>(
+    coordinate: ProjectionCoordinate,
+    output: T
+  ): T | Promise<T>;
+  unprojectTo<T extends ProjectionOutput>(
+    coordinate: ProjectionCoordinate,
+    output: T
+  ): T | Promise<T>;
+  projectFlat<T extends ProjectionArray>(coordinates: T, dimension?: number): T | Promise<T>;
+  unprojectFlat<T extends ProjectionArray>(coordinates: T, dimension?: number): T | Promise<T>;
+  projectSync(coordinate: readonly number[]): number[];
+  unprojectSync(coordinate: readonly number[]): number[];
+  projectToSync<T extends ProjectionOutput>(coordinate: ProjectionCoordinate, output: T): T;
+  unprojectToSync<T extends ProjectionOutput>(coordinate: ProjectionCoordinate, output: T): T;
+  projectFlatSync<T extends ProjectionArray>(coordinates: T, dimension?: number): T;
+  unprojectFlatSync<T extends ProjectionArray>(coordinates: T, dimension?: number): T;
+}
+
+/** A prepared transform whose ordinary coordinate methods are synchronous too. */
+export interface PreparedProjection extends Projection {
+  project(coordinate: readonly number[]): number[];
+  unproject(coordinate: readonly number[]): number[];
+  projectTo<T extends ProjectionOutput>(coordinate: ProjectionCoordinate, output: T): T;
+  unprojectTo<T extends ProjectionOutput>(coordinate: ProjectionCoordinate, output: T): T;
+  projectFlat<T extends ProjectionArray>(coordinates: T, dimension?: number): T;
+  unprojectFlat<T extends ProjectionArray>(coordinates: T, dimension?: number): T;
+}
+
+export type {ProjectionCoordinate, ProjectionOutput, ProjectionArray};
+export type {ProjectionTransformOptions};
+export type {ProjectionPlugin, ProjectionPoint} from './experimental/types';
+export type {ProjectionDescriptor} from './experimental/projection-descriptor';
+
+export type {
+  CRSEngine,
+  CRSDescriptor,
+  CRSConversion,
+  CRSConverter,
+  CRSBounds,
+  CRSRenderingScale,
+  CRSRenderingScaleCallback,
+  GetCRSOptions
+} from './experimental/types';

package/src/projection/web-mercator.ts

@@ -0,0 +1,148 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original minimal spherical Web Mercator implementation.
+import type {
+  ProjectionEngine,
+  PreparedProjection,
+  CreateProjectionOptions,
+  ProjectionCoordinate,
+  ProjectionOutput,
+  ProjectionArray
+} from './types';
+import {validateScalarOutput, writeScalarOutput} from './experimental/scalar-output';
+
+const RADIUS = 6378137;
+const RADIANS = Math.PI / 180;
+const FLOAT32_MAX = 3.4028234663852886e38;
+
+function wrap(longitude: number): number {
+  if (Math.abs(longitude) <= Math.PI) return longitude;
+  const circle = 2 * Math.PI;
+  return ((((longitude + Math.PI) % circle) + circle) % circle) - Math.PI;
+}
+
+type CRS = 'WGS84' | 'EPSG:4326' | 'EPSG:3857';
+function crs(input: CreateProjectionOptions['from']): CRS {
+  if (input === undefined) return 'WGS84';
+  if (input === 'WGS84' || input === 'EPSG:4326' || input === 'EPSG:3857') return input;
+  throw new Error('WebMercatorProjectionEngine supports only WGS84, EPSG:4326 and EPSG:3857');
+}
+
+/** Minimal WGS84 / EPSG:3857 factory, without CRS readers, grids or datum transforms. */
+export class WebMercatorProjectionEngine implements ProjectionEngine {
+  createProjection(options: CreateProjectionOptions = {}): PreparedProjection {
+    if (options.mode !== undefined && options.mode !== 'strict' && options.mode !== 'horizontal')
+      throw new Error('Invalid projection mode');
+    return new WebMercatorTransform(crs(options.from), crs(options.to));
+  }
+  async createProjectionAsync(options: CreateProjectionOptions = {}): Promise<PreparedProjection> {
+    return this.createProjection(options);
+  }
+}
+
+class WebMercatorTransform implements PreparedProjection {
+  readonly lossy = false;
+  private readonly point = {x: 0, y: 0, z: 0};
+  constructor(
+    private readonly from: CRS,
+    private readonly to: CRS
+  ) {
+    this.project = this.project.bind(this);
+    this.unproject = this.unproject.bind(this);
+    this.projectTo = this.projectTo.bind(this);
+    this.unprojectTo = this.unprojectTo.bind(this);
+    this.projectFlat = this.projectFlat.bind(this);
+    this.unprojectFlat = this.unprojectFlat.bind(this);
+    this.projectSync = this.project;
+    this.unprojectSync = this.unproject;
+    this.projectToSync = this.projectTo;
+    this.unprojectToSync = this.unprojectTo;
+    this.projectFlatSync = this.projectFlat;
+    this.unprojectFlatSync = this.unprojectFlat;
+  }
+  async preload(): Promise<void> {}
+  project(coordinate: readonly number[]): number[] {
+    return this.projectTo(coordinate, new Array<number>(coordinate.length));
+  }
+  unproject(coordinate: readonly number[]): number[] {
+    return this.unprojectTo(coordinate, new Array<number>(coordinate.length));
+  }
+  projectTo<T extends ProjectionOutput>(coordinate: ProjectionCoordinate, output: T): T {
+    return this.scalar(coordinate, output, this.from, this.to);
+  }
+  unprojectTo<T extends ProjectionOutput>(coordinate: ProjectionCoordinate, output: T): T {
+    return this.scalar(coordinate, output, this.to, this.from);
+  }
+  projectFlat<T extends ProjectionArray>(coordinates: T, dimension = 2): T {
+    return this.flat(coordinates, dimension, this.from, this.to);
+  }
+  unprojectFlat<T extends ProjectionArray>(coordinates: T, dimension = 2): T {
+    return this.flat(coordinates, dimension, this.to, this.from);
+  }
+  projectSync: PreparedProjection['project'];
+  unprojectSync: PreparedProjection['unproject'];
+  projectToSync: PreparedProjection['projectTo'];
+  unprojectToSync: PreparedProjection['unprojectTo'];
+  projectFlatSync: PreparedProjection['projectFlat'];
+  unprojectFlatSync: PreparedProjection['unprojectFlat'];
+
+  private run(x: number, y: number, z: number, from: CRS, to: CRS): void {
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+      throw new Error('Projection requires finite XYZ coordinates');
+    if (from !== 'EPSG:3857' && Math.abs(y) > 90)
+      throw new Error('Coordinate outside geographic domain');
+    if (from !== to && !(from !== 'EPSG:3857' && to !== 'EPSG:3857')) {
+      if (from === 'EPSG:3857') {
+        x = wrap(x / RADIUS) / RADIANS;
+        y = Math.atan(Math.sinh(y / RADIUS)) / RADIANS;
+      } else {
+        if (Math.abs(y) >= 90) throw new Error('Coordinate outside Web Mercator projection domain');
+        x = wrap(x * RADIANS) * RADIUS;
+        y = (Math.asinh(Math.tan(y * RADIANS)) + 0) * RADIUS;
+      }
+    }
+    if (!Number.isFinite(x) || !Number.isFinite(y))
+      throw new Error('Projected coordinate is not finite');
+    this.point.x = x;
+    this.point.y = y;
+    this.point.z = z;
+  }
+  private scalar<T extends ProjectionOutput>(
+    coordinate: ProjectionCoordinate,
+    output: T,
+    from: CRS,
+    to: CRS
+  ): T {
+    validateScalarOutput(coordinate, output, coordinate.length);
+    if (coordinate.length < 2) throw new Error('Projection requires at least two ordinates');
+    this.run(coordinate[0], coordinate[1], coordinate.length >= 3 ? coordinate[2] : 0, from, to);
+    return writeScalarOutput(coordinate, output, this.point, coordinate.length);
+  }
+  private flat<T extends ProjectionArray>(
+    coordinates: T,
+    dimension: number,
+    from: CRS,
+    to: CRS
+  ): T {
+    if (!(coordinates instanceof Float32Array || coordinates instanceof Float64Array))
+      throw new Error('Flat coordinates require Float32Array or Float64Array');
+    if (!Number.isSafeInteger(dimension) || dimension < 2 || coordinates.length % dimension)
+      throw new Error('Invalid flat coordinate dimension');
+    const float32 = coordinates instanceof Float32Array;
+    for (let offset = 0; offset < coordinates.length; offset += dimension) {
+      this.run(
+        coordinates[offset],
+        coordinates[offset + 1],
+        dimension >= 3 ? coordinates[offset + 2] : 0,
+        from,
+        to
+      );
+      if (float32 && (Math.abs(this.point.x) > FLOAT32_MAX || Math.abs(this.point.y) > FLOAT32_MAX))
+        throw new Error('Projected coordinate exceeds Float32 range');
+      coordinates[offset] = this.point.x;
+      coordinates[offset + 1] = this.point.y;
+    }
+    return coordinates;
+  }
+}

package/src/subdivide-globe-mesh.ts

@@ -0,0 +1,75 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original adapter over math.gl subdivision and spheroid kernels. Motivation only: https://github.com/keplergl/kepler.gl/pull/3548 (closed, unmerged). No implementation copied.
+
+import {spheroidToCartesian} from '@math.gl/core/spheroid';
+import {
+  subdivideTriangleMesh,
+  type TriangleMesh,
+  type SubdivideTriangleMeshOptions,
+  type SubdividedTriangleMesh
+} from '@math.gl/geometry/polygon';
+
+/** Preserve the refinement discriminant when removing the globe adapter's fixed transform. */
+type GlobeSubdivisionOptions<Options> = Options extends unknown
+  ? Omit<Options, 'transform' | 'targetSize'>
+  : never;
+
+/** Globe axes and either sampled-error or source-edge refinement options. */
+export type SubdivideGlobeMeshOptions = GlobeSubdivisionOptions<SubdivideTriangleMeshOptions> & {
+  /** Equatorial radius; default 6371000. */
+  semiMajorAxis?: number;
+  /** Polar radius; default semiMajorAxis. Positive and at most semiMajorAxis. */
+  semiMinorAxis?: number;
+};
+
+/** Refine an already triangulated longitude/latitude(/height) mesh onto a globe.
+ * Source angles are degrees, height and tolerance are in axis units. Output is
+ * ECEF Cartesian (X longitude 0, Y longitude 90, Z north), not deck common space.
+ * Unwrap longitudes/split seams first: each triangle must span at most 180 degrees.
+ * Refinement preserves existing holes, winding, seam vertices and attribute
+ * provenance; it does not triangulate or clip polygons. Error is sampled, not certified.
+ */
+export function subdivideGlobeMesh(
+  mesh: TriangleMesh,
+  options: SubdivideGlobeMeshOptions
+): SubdividedTriangleMesh {
+  const {semiMajorAxis = 6371000, semiMinorAxis = semiMajorAxis, size = 2, ...limits} = options;
+  if (size !== 2 && size !== 3) throw new RangeError('Source size must be 2 or 3');
+  if (
+    !Number.isFinite(semiMajorAxis) ||
+    !Number.isFinite(semiMinorAxis) ||
+    semiMajorAxis <= 0 ||
+    semiMinorAxis <= 0 ||
+    semiMinorAxis > semiMajorAxis
+  )
+    throw new RangeError('Expected positive sphere/oblate axes');
+  // Validate latitude and reject unsplit long edges rather than silently crossing the globe.
+  for (let i = 1; i < mesh.positions.length; i += size)
+    if (Math.abs(mesh.positions[i]) > 90) throw new RangeError('Latitude outside [-90, 90]');
+  for (let i = 0; i < mesh.indices.length; i += 3) {
+    const longitudes = [0, 1, 2].map(j => mesh.positions[mesh.indices[i + j] * size]);
+    if (Math.max(...longitudes) - Math.min(...longitudes) > 180)
+      throw new RangeError('Unwrap longitude seams before globe subdivision');
+  }
+  const geometry = {
+    semiMajorAxis,
+    semiMinorAxis,
+    eccentricitySquared: 1 - (semiMinorAxis / semiMajorAxis) ** 2
+  };
+  return subdivideTriangleMesh(mesh, {
+    ...limits,
+    size,
+    targetSize: 3,
+    transform(position) {
+      const point = {
+        x: (position[0] * Math.PI) / 180,
+        y: (position[1] * Math.PI) / 180,
+        z: size === 3 ? position[2] : 0
+      };
+      if (!spheroidToCartesian(point, geometry)) return null;
+      return [point.x, point.y, point.z];
+    }
+  });
+}