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

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/rhumb-path.ts

@@ -0,0 +1,128 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original distance-parameterized adapter over the attributed math.gl rhumb solver.
+
+import type {NumericArray} from '@math.gl/core/types';
+import {EllipsoidRhumb, type RhumbLine} from './ellipsoid-rhumb';
+import {validateGeographicPosition} from './geodesic-path';
+import {WGS84_RADIUS_X, WGS84_RADIUS_Z} from './constants';
+
+let wgs84: EllipsoidRhumb | undefined;
+function getDefaultRhumb(): EllipsoidRhumb {
+  if (!wgs84)
+    wgs84 = new EllipsoidRhumb({semiMajorAxis: WGS84_RADIUS_X, semiMinorAxis: WGS84_RADIUS_Z});
+  return wgs84;
+}
+
+export type RhumbPathOptions = {
+  rhumb?: EllipsoidRhumb;
+  /** Preserve the supplied endpoint interval, including complete turns. */
+  longitudeMode?: 'shortest' | 'unrolled';
+  /** Whole turns added to the shortest endpoint longitude difference. */
+  longitudeTurns?: number;
+};
+
+/** Constant-bearing endpoint path, in degrees and solver axis units. Height is
+ * linear in surface-distance fraction and does not contribute to length.
+ * Unlike geodesics, rhumbs reject exact poles. Endpoints/options are snapshots.
+ */
+export class RhumbPath {
+  readonly length: number;
+  readonly size: 2 | 3;
+  private readonly first: readonly number[];
+  private readonly last: readonly number[];
+  private readonly line: RhumbLine;
+
+  constructor(start: ArrayLike<number>, end: ArrayLike<number>, options: RhumbPathOptions = {}) {
+    validateGeographicPosition(start);
+    validateGeographicPosition(end);
+    if (start.length !== end.length) throw new RangeError('Rhumb endpoint dimensions must match');
+    const solver = options.rhumb || getDefaultRhumb();
+    if (
+      (options.longitudeMode !== undefined &&
+        !['shortest', 'unrolled'].includes(options.longitudeMode)) ||
+      (options.longitudeMode === 'unrolled' && options.longitudeTurns !== undefined)
+    )
+      throw new RangeError('Choose explicit turns or unrolled endpoint longitudes');
+    let inverse = solver.inverse(start[1], start[0], end[1], end[0], {
+      longitudeTurns: options.longitudeTurns,
+      unrollLongitude: true
+    });
+    if (options.longitudeMode === 'unrolled') {
+      const turns = Math.round((end[0] - inverse.lon2) / 360);
+      if (turns !== 0)
+        inverse = solver.inverse(start[1], start[0], end[1], end[0], {
+          longitudeTurns: turns,
+          unrollLongitude: true
+        });
+    }
+    if (![inverse.s12, inverse.azi12, inverse.lon2].every(Number.isFinite) || inverse.s12 < 0)
+      throw new RangeError('Unresolved rhumb path');
+    this.size = start.length as 2 | 3;
+    this.length = inverse.s12;
+    this.first = Object.freeze(Array.from(start));
+    const last = Array.from(end);
+    const turns = Math.round((inverse.lon2 - end[0]) / 360);
+    const endpoint = end[0] + 360 * turns;
+    const retainsPhase =
+      Number.isSafeInteger(turns) &&
+      Number.isFinite(endpoint) &&
+      Math.abs(endpoint - inverse.lon2) <=
+        4 * Number.EPSILON * Math.max(360, Math.abs(inverse.lon2));
+    last[0] = inverse.s12 === 0 ? start[0] : retainsPhase ? endpoint : inverse.lon2;
+    if (inverse.s12 === 0) last[1] = start[1];
+    this.last = Object.freeze(last);
+    this.line = solver.line(start[1], start[0], inverse.azi12, {unrollLongitude: true});
+  }
+
+  get start(): number[] {
+    return this.first.slice();
+  }
+  get end(): number[] {
+    return this.last.slice();
+  }
+
+  sample(fraction: number): number[];
+  sample<T extends NumericArray>(fraction: number, result: T): T;
+  sample(fraction: number, result: NumericArray = new Array(this.size)): NumericArray {
+    if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1)
+      throw new RangeError('Rhumb fraction must be in [0, 1]');
+    if (
+      result.length !== this.size ||
+      (ArrayBuffer.isView(result) &&
+        !(result instanceof Float32Array) &&
+        !(result instanceof Float64Array))
+    )
+      throw new RangeError('Expected a floating rhumb output with matching dimensions');
+    let longitude = this.first[0],
+      latitude = this.first[1];
+    if (fraction === 1) {
+      longitude = this.last[0];
+      latitude = this.last[1];
+    } else if (fraction !== 0 && this.length !== 0) {
+      const p = this.line.position(this.length * fraction);
+      longitude = p.lon2;
+      latitude = p.lat2;
+    }
+    const height = this.size === 3 ? this.first[2] * (1 - fraction) + this.last[2] * fraction : 0;
+    const values = [longitude, latitude, height];
+    if (
+      !values.every(Number.isFinite) ||
+      (result instanceof Float32Array && !values.every(x => Number.isFinite(Math.fround(x))))
+    )
+      throw new RangeError('Unrepresentable rhumb sample');
+    result[0] = longitude;
+    result[1] = latitude;
+    if (this.size === 3) result[2] = height;
+    return result;
+  }
+
+  sampleByDistance(distance: number): number[];
+  sampleByDistance<T extends NumericArray>(distance: number, result: T): T;
+  sampleByDistance(distance: number, result: NumericArray = new Array(this.size)): NumericArray {
+    if (!Number.isFinite(distance) || distance < 0 || distance > this.length)
+      throw new RangeError('Distance must be within the rhumb path');
+    return this.sample(this.length === 0 ? 0 : distance / this.length, result);
+  }
+}

package/src/rhumb-polygon.ts

@@ -0,0 +1,24 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original rhumb polygon facade over the original rhumb integrals and separately attributed shared GeographicLib polygon transit/reduction rules.
+import {EllipsoidRhumb, validateRhumbPoint} from './ellipsoid-rhumb';
+import type {GeodesicParameters} from './ellipsoid-geodesic';
+import {SurfacePolygon, type SurfacePointOptions} from './ellipsoid-helpers/surface-polygon';
+export type {
+  SurfacePolygonOptions as RhumbPolygonOptions,
+  SurfacePolygonResult as RhumbPolygonResult,
+  SurfacePointOptions as RhumbPointOptions
+} from './ellipsoid-helpers/surface-polygon';
+/** Streaming rhumb polygon/polyline. Extra inverse turns are explicit per point. */
+export class RhumbPolygon extends SurfacePolygon {
+  constructor(parameters: GeodesicParameters, options: {polyline?: boolean} = {}) {
+    super(new EllipsoidRhumb(parameters), options);
+  }
+  override addPoint(latitude: number, longitude: number, options: SurfacePointOptions = {}): this {
+    validateRhumbPoint(latitude, longitude);
+    if (!Number.isSafeInteger(options.longitudeTurns ?? 0))
+      throw new RangeError('Rhumb longitudeTurns must be a safe integer');
+    return super.addPoint(latitude, longitude, options);
+  }
+}