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

package/src/coordinates/mgrs.ts

@@ -0,0 +1,157 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) Charles Karney (2008-2022)
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: MGRS alphabets, micrometre digit extraction and UTM row/band compatibility adapted from GeographicLib 2.7 MGRS.cpp (MIT). Original precision-bounded codec; see ../../GEOGRAPHICLIB-LICENSE.txt.
+import {projectGrid, unprojectGrid, type GridCoordinate} from './grid';
+const COLUMNS = ['ABCDEFGH', 'JKLMNPQR', 'STUVWXYZ'],
+  ROWS = 'ABCDEFGHJKLMNPQRSTUV',
+  BANDS = 'CDEFGHJKLMNPQRSTUVWX';
+const UPS_COLUMNS = ['JKLPQRSTUXYZ', 'ABCFGHJKLPQR', 'RSTUXYZ', 'ABCFGHJ'],
+  UPS_ROWS = ['ABCDEFGHJKLMNPQRSTUVWXYZ', 'ABCDEFGHJKLMNP'],
+  UPS_BANDS = 'ABYZ',
+  TILE = 100000;
+function utmRow(band: number, column: number, row: number): number {
+  const c = (100 * (8 * band + 4)) / 90,
+    north = band >= 0;
+  const min = band > -10 ? Math.floor(c - 4.3 - (north ? 0.1 : 0)) : -90,
+    max = band < 9 ? Math.floor(c + 4.4 - (north ? 0.1 : 0)) : 94;
+  const base = Math.trunc((min + max) / 2) - 10;
+  row = ((((row - base + 100) % 20) + 20) % 20) + base;
+  if (row < min || row > max) {
+    const b = band >= 0 ? band : -band - 1,
+      r = row >= 0 ? row : -row - 1,
+      col = column < 4 ? column : 7 - column;
+    if (
+      !(
+        (r === 70 && b === 8 && col >= 2) ||
+        (r === 71 && b === 7 && col <= 2) ||
+        (r === 79 && b === 9 && col >= 1) ||
+        (r === 80 && b === 8 && col <= 1)
+      )
+    )
+      throw new RangeError('MGRS square does not intersect its latitude band');
+  }
+  return row;
+}
+/** WGS84 MGRS through micrometre precision; extra digits do not imply survey accuracy. */
+export function formatMGRS(
+  latitude: number,
+  longitude: number,
+  precision = 5,
+  options: {zone?: number} = {}
+): string {
+  if (!Number.isInteger(precision) || precision < 0 || precision > 11)
+    throw new RangeError('MGRS precision must be in [0,11]');
+  const grid = projectGrid(latitude, longitude, options),
+    {zone, north, easting: x} = grid;
+  let y = grid.northing;
+  if (zone && !north && y === 1e7) y -= 2 ** -28;
+  const column = Math.floor(x / TILE),
+    row = Math.floor(y / TILE);
+  let prefix: string;
+  if (zone) {
+    const band =
+      Math.abs(latitude) < 2 ** -46
+        ? north
+          ? 0
+          : -1
+        : Math.max(-10, Math.min(9, Math.floor((Math.floor(latitude) + 80) / 8) - 10));
+    if (column < 1 || column > 8 || utmRow(band, column - 1, row % 20) !== row - (north ? 0 : 100))
+      throw new RangeError('Grid outside MGRS domain');
+    prefix =
+      String(zone).padStart(2, '0') +
+      BANDS[band + 10] +
+      COLUMNS[(zone - 1) % 3][column - 1] +
+      ROWS[(row + ((zone - 1) % 2 ? 5 : 0)) % 20];
+  } else {
+    const band = (north ? 2 : 0) + (column >= 20 ? 1 : 0),
+      origin = north ? 13 : 8;
+    const col = column - (column >= 20 ? 20 : origin),
+      r = row - origin;
+    if (col < 0 || col >= UPS_COLUMNS[band].length || r < 0 || r >= UPS_ROWS[Number(north)].length)
+      throw new RangeError('Grid outside MGRS domain');
+    prefix = UPS_BANDS[band] + UPS_COLUMNS[band][col] + UPS_ROWS[Number(north)][r];
+  }
+  const unit = 10 ** (11 - precision);
+  // Integer micrometres stay below 2^53 throughout the supported envelopes.
+  const digits = (value: number, tile: number) =>
+    String(Math.floor((Math.floor(value * 1e6) - tile * 1e11) / unit)).padStart(precision, '0');
+  return prefix + (precision ? digits(x, column) + digits(y, row) : '');
+}
+export type MGRSCoordinate = GridCoordinate & {
+  latitude: number;
+  longitude: number;
+  precision: number;
+  resolution: number;
+};
+export function parseMGRS(text: string, options: {center?: boolean} = {}): MGRSCoordinate {
+  if (typeof text !== 'string' || text.length > 128) throw new RangeError('Invalid MGRS text');
+  const match = /^(\d{1,2})?([C-HJ-NP-XABYZ])([A-HJ-NP-Z])([A-HJ-NP-Z])(\d*)$/.exec(
+    text.replace(/\s/g, '').toUpperCase()
+  );
+  if (!match || match[5].length % 2 || match[5].length > 22)
+    throw new RangeError('Expected a complete MGRS cell with 0–11 digit pairs');
+  const zone = match[1] ? Number(match[1]) : 0,
+    bandText = match[2],
+    precision = match[5].length / 2;
+  let north: boolean, column: number, row: number;
+  if (match[1]) {
+    if (zone < 1 || zone > 60) throw new RangeError('Invalid MGRS zone');
+    const band = BANDS.indexOf(bandText) - 10;
+    if (band < -10) throw new RangeError('Invalid UTM band');
+    north = band >= 0;
+    column = COLUMNS[(zone - 1) % 3].indexOf(match[3]);
+    row = ROWS.indexOf(match[4]);
+    if (column < 0 || row < 0) throw new RangeError('Invalid MGRS square');
+    row = utmRow(band, column, (row + ((zone - 1) % 2 ? 15 : 0)) % 20) + (north ? 0 : 100);
+    column++;
+  } else {
+    const band = UPS_BANDS.indexOf(bandText);
+    if (band < 0) throw new RangeError('Invalid UPS band');
+    north = band >= 2;
+    column = UPS_COLUMNS[band].indexOf(match[3]);
+    row = UPS_ROWS[Number(north)].indexOf(match[4]);
+    if (column < 0 || row < 0) throw new RangeError('Invalid UPS square');
+    column += band % 2 ? 20 : north ? 13 : 8;
+    row += north ? 13 : 8;
+  }
+  const resolution = 10 ** (5 - precision),
+    center = options.center === false ? 0 : 0.5;
+  const grid = {
+    zone,
+    north,
+    easting:
+      ((column * 10 ** precision + Number(match[5].slice(0, precision) || 0) + center) * TILE) /
+      10 ** precision,
+    northing:
+      ((row * 10 ** precision + Number(match[5].slice(precision) || 0) + center) * TILE) /
+      10 ** precision
+  };
+  return {...grid, ...unprojectGrid(grid), precision, resolution};
+}
+
+/** A grid-zone designation is a region, never a fabricated cell centre. */
+export type MGRSZone = {zone: number; north: boolean; band: string};
+export function parseMGRSZone(text: string): MGRSZone {
+  if (typeof text !== 'string' || text.length > 128) throw new RangeError('Invalid MGRS zone');
+  const m = /^(\d{1,2})?([C-HJ-NP-XABYZ])$/.exec(text.replace(/\s/g, '').toUpperCase());
+  if (!m) throw new RangeError('Expected an MGRS grid-zone designation');
+  const zone = m[1] ? Number(m[1]) : 0,
+    band = m[2];
+  if (m[1] ? zone < 1 || zone > 60 || !BANDS.includes(band) : !UPS_BANDS.includes(band))
+    throw new RangeError('Invalid MGRS zone or band');
+  return {
+    zone,
+    north: zone ? BANDS.indexOf(band) >= 10 : UPS_BANDS.indexOf(band) >= 2,
+    band
+  };
+}
+export function formatMGRSZone(
+  latitude: number,
+  longitude: number,
+  options: {zone?: number} = {}
+): string {
+  const cell = formatMGRS(latitude, longitude, 0, options);
+  return cell.slice(0, cell.length - 2);
+}

package/src/coordinates.ts

@@ -0,0 +1,24 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+export {
+  parseAngle,
+  formatAngle,
+  parseGeographicCoordinates,
+  formatGeographicCoordinates
+} from './coordinates/angles';
+export type {AngleAxis} from './coordinates/angles';
+export {
+  standardGridZone,
+  projectGrid,
+  unprojectGrid,
+  transferGrid
+} from './coordinates/grid';
+export type {GridCoordinate, GridOptions} from './coordinates/grid';
+export {
+  formatMGRS,
+  parseMGRS,
+  formatMGRSZone,
+  parseMGRSZone
+} from './coordinates/mgrs';
+export type {MGRSCoordinate, MGRSZone} from './coordinates/mgrs';

package/src/crs/crs-descriptor-types.ts

@@ -0,0 +1,81 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {CRSExecutionIdentity} from './execution-identity';
+import type {CRSProjectionDomain} from './projection-domain';
+import type {CRSMetadata} from './crs-metadata';
+
+/** Supported coordinate input storage. */
+export type CRSCoordinate = readonly number[] | Float32Array | Float64Array;
+/** Caller-owned conversion output storage. */
+export type CRSOutput = number[] | Float32Array | Float64Array;
+
+/** Finite target-coordinate XYZ envelope describing an appropriate rendering target.
+ * This is not the projection algorithm's validity domain or a coordinate validity test.
+ */
+export type CRSBounds = readonly [
+  minimum: readonly [number, number, number],
+  maximum: readonly [number, number, number]
+];
+
+/** Rendering factors in effective target-axis order. Horizontal factors measure
+ * WGS84 reference-surface metres per stored coordinate unit through the full inverse
+ * transform. For projected CRSs the vertical factor uses the square root of the
+ * inverse horizontal area scale, expressed in the declared vertical unit.
+ * This sizing convention is independent of altitude conversion; use the component
+ * unit metadata and converters for physical heights. Geocentric/identity factors
+ * are constant physical unit conversions.
+ */
+export type CRSRenderingScale = readonly [x: number, y: number, z: number];
+
+/** Evaluate at a position in the descriptor's CRS; null means scale calculation failed. */
+export type CRSRenderingScaleCallback = (coordinate: CRSCoordinate) => CRSRenderingScale | null;
+
+/** Synchronous conversion; omit output to allocate an array, or supply storage to reuse it. */
+export interface CRSConversion {
+  (coordinate: CRSCoordinate): number[];
+  <T extends CRSOutput>(coordinate: CRSCoordinate, output: T): T;
+}
+
+/** Prepared bidirectional conversion between a source CRS and a descriptor's target CRS. */
+export interface CRSConverter {
+  /** Convert source coordinates to target coordinates, optionally reusing output storage. */
+  readonly from: CRSConversion;
+  /** Convert target coordinates to source coordinates, optionally reusing output storage. */
+  readonly to: CRSConversion;
+  /** Normalize source coordinates for the target projection, optionally reusing output storage. */
+  readonly normalize: CRSConversion;
+}
+
+/** Prepared CRS metadata, target-space behavior, and converters keyed by source CRS string.
+ * WGS84 uses longitude/latitude in degrees and ellipsoidal height in metres. Converters
+ * retain the engine's datum policy; fourth and later components pass through.
+ */
+export interface CRSDescriptor extends CRSMetadata {
+  /** Original string under default conventions; otherwise a resolved @math.gl/geospatial/crs signature.
+   * Opaque to consumers; no arbitrary CRS equivalence comparison is implied.
+   * Does not fingerprint algorithm implementations or grid contents; equality does
+   * not guarantee packed-coordinate interchangeability across engines.
+   */
+  readonly signature: string;
+  /** Optional backend execution provenance; absent means unknown. Separate from CRS identity. */
+  readonly executionIdentity?: CRSExecutionIdentity;
+  /** Finite XYZ envelope chosen as an appropriate rendering target, in effective units and axis order.
+   * Bounds describe a rendering policy for the reference surface, not the algorithm's
+   * mathematical validity domain or altitude limits. Coordinates outside the envelope
+   * may still be converted; being inside it does not guarantee a valid conversion.
+   */
+  readonly renderingBounds: CRSBounds;
+  /** Optional explicit target-plane validity geometry. Absence means unknown. */
+  readonly projectionDomain?: CRSProjectionDomain;
+  /** Constant scale or target-position callback; no viewport fallback is applied. */
+  readonly renderingScale: CRSRenderingScale | CRSRenderingScaleCallback;
+  /** Return rendering sizing factors at the anchor; null means sampling is unavailable
+   * or derivatives fail numerical agreement. Invalid finite geometry raises an error. */
+  getRenderingScale(coordinate: CRSCoordinate): CRSRenderingScale | null;
+  /** Prepared converters; WGS84 is always available, plus explicitly requested source strings. */
+  readonly converter: Readonly<Record<string, CRSConverter>> & {
+    readonly WGS84: CRSConverter;
+  };
+}

package/src/crs/crs-descriptor.ts

@@ -0,0 +1,203 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {createCRSProjectionDomain, type CRSProjectionDomain} from './projection-domain';
+import {createCRSExecutionIdentity, type CRSExecutionIdentity} from './execution-identity';
+import {getCRSSignature} from './crs-metadata';
+import type {CRSMetadata, CRSUnit} from './crs-metadata';
+import type {
+  CRSBounds,
+  CRSConversion,
+  CRSConverter,
+  CRSDescriptor,
+  CRSRenderingScale,
+  CRSRenderingScaleCallback
+} from './crs-descriptor-types';
+import type {CRSCoordinate, CRSOutput} from './crs-descriptor-types';
+
+/** Backend-owned operations and rendering policy for an already prepared target CRS. */
+export type CRSDescriptorOptions = Readonly<{
+  metadata: CRSMetadata;
+  /** Optional opaque caller identity. Defaults to getCRSSignature(metadata). */
+  signature?: string;
+  /** Opt-in provenance for execution cache invalidation; never inferred from callbacks. */
+  executionIdentity?: CRSExecutionIdentity;
+  renderingBounds: CRSBounds;
+  /** Backend-supplied target domain, independently snapshotted when present. */
+  projectionDomain?: CRSProjectionDomain;
+  renderingScale: CRSRenderingScale | CRSRenderingScaleCallback;
+  /** WGS84 means longitude/latitude degrees and ellipsoidal height metres. */
+  converter: Readonly<Record<string, CRSConverter>> & {readonly WGS84: CRSConverter};
+}>;
+
+/** Assemble a descriptor without native parsing, projection algorithms or authority lookup.
+ * Data is snapshotted; callbacks retain their backend-owned state and lifetime.
+ * Shape validation does not establish geodetic correctness or CRS equivalence.
+ */
+export function createCRSDescriptor(options: CRSDescriptorOptions): CRSDescriptor {
+  const source = options.metadata;
+  requireValue(
+    ['geographic', 'projected', 'geocentric', 'identity'].includes(source.coordinateFrame),
+    'coordinateFrame'
+  );
+  requireValue(
+    typeof source.projection === 'string' && Boolean(source.projection.trim()),
+    'projection'
+  );
+  requireValue(typeof source.lossy === 'boolean', 'lossy');
+  requireValue(
+    typeof source.axis === 'string' &&
+      source.axis.length === 3 &&
+      /^[ewnsud]+$/.test(source.axis) &&
+      /[ew]/.test(source.axis) &&
+      /[ns]/.test(source.axis) &&
+      /[ud]/.test(source.axis),
+    'axis'
+  );
+  requireValue(
+    positive(source.ellipsoid.semiMajorAxis) && positive(source.ellipsoid.semiMinorAxis),
+    'ellipsoid'
+  );
+  requireValue(
+    Boolean(source.parameters) &&
+      typeof source.parameters === 'object' &&
+      !Array.isArray(source.parameters),
+    'parameters'
+  );
+  const parameters = {...source.parameters};
+  requireValue(
+    Object.values(parameters).every(value => value === undefined || typeof value === 'string'),
+    'parameters'
+  );
+  const areaOfUse = source.areaOfUse && ([...source.areaOfUse] as [number, number, number, number]);
+  if (areaOfUse)
+    requireValue(
+      areaOfUse.length === 4 && areaOfUse.every(Number.isFinite) && areaOfUse[1] <= areaOfUse[3],
+      'areaOfUse'
+    );
+  const metadata: CRSMetadata = {
+    coordinateFrame: source.coordinateFrame,
+    projection: source.projection,
+    parameters: Object.freeze(parameters),
+    ellipsoid: Object.freeze({
+      semiMajorAxis: source.ellipsoid.semiMajorAxis,
+      semiMinorAxis: source.ellipsoid.semiMinorAxis
+    }),
+    axis: source.axis,
+    xUnit: copyUnit(source.xUnit),
+    yUnit: copyUnit(source.yUnit),
+    zUnit: copyUnit(source.zUnit),
+    lossy: source.lossy,
+    areaOfUse: areaOfUse && Object.freeze(areaOfUse)
+  };
+  const signature = options.signature ?? getCRSSignature(metadata);
+  requireValue(typeof signature === 'string' && Boolean(signature.trim()), 'signature');
+  const bounds = options.renderingBounds;
+  requireValue(
+    Array.isArray(bounds) &&
+      bounds.length === 2 &&
+      [...bounds].every(
+        row => Array.isArray(row) && row.length === 3 && [...row].every(Number.isFinite)
+      ) &&
+      bounds[0].every((minimum, i) => minimum <= bounds[1][i]),
+    'renderingBounds'
+  );
+  const renderingBounds: CRSBounds = Object.freeze([
+    Object.freeze([...bounds[0]]) as CRSBounds[0],
+    Object.freeze([...bounds[1]]) as CRSBounds[1]
+  ]);
+  const suppliedScale = options.renderingScale;
+  const renderingScale =
+    typeof suppliedScale === 'function'
+      ? (coordinate: CRSCoordinate): CRSRenderingScale | null => {
+          const result = suppliedScale(coordinate);
+          return result === null ? null : copyScale(result);
+        }
+      : copyScale(suppliedScale);
+  requireValue(Object.prototype.hasOwnProperty.call(options.converter, 'WGS84'), 'converter.WGS84');
+  const converter = Object.create(null) as Record<string, CRSConverter> & {WGS84: CRSConverter};
+  for (const key of Object.getOwnPropertyNames(options.converter)) {
+    const operations = options.converter[key];
+    requireValue(Boolean(key.trim()), 'converter key');
+    converter[key] = Object.freeze({
+      from: bindConversion(operations, 'from'),
+      to: bindConversion(operations, 'to'),
+      normalize: bindConversion(operations, 'normalize')
+    });
+  }
+  return Object.freeze({
+    ...metadata,
+    signature,
+    ...(options.executionIdentity === undefined
+      ? {}
+      : {executionIdentity: createCRSExecutionIdentity(options.executionIdentity)}),
+    renderingBounds,
+    ...(options.projectionDomain === undefined
+      ? {}
+      : {projectionDomain: createCRSProjectionDomain(options.projectionDomain)}),
+    renderingScale,
+    getRenderingScale: (coordinate: CRSCoordinate) =>
+      typeof renderingScale === 'function' ? renderingScale(coordinate) : renderingScale,
+    converter: Object.freeze(converter)
+  });
+}
+
+function bindConversion(owner: CRSConverter, key: keyof CRSConverter): CRSConversion {
+  const operation = owner?.[key] as (coordinate: CRSCoordinate, output?: CRSOutput) => CRSOutput;
+  requireValue(typeof operation === 'function', `converter.${key}`);
+  function convert(coordinate: CRSCoordinate): number[];
+  function convert<T extends CRSOutput>(coordinate: CRSCoordinate, output: T): T;
+  function convert(coordinate: CRSCoordinate, output?: CRSOutput): CRSOutput {
+    // Capture the method and receiver at construction. Never adapt promises into sync conversions.
+    const result = operation.call(owner, coordinate, output);
+    requireSynchronous(result);
+    requireValue(
+      output === undefined ? Array.isArray(result) : result === output,
+      'converter result: synchronous array or supplied output required'
+    );
+    return result;
+  }
+  return convert;
+}
+
+function copyUnit(unit: CRSUnit): CRSUnit {
+  requireValue(
+    typeof unit.name === 'string' &&
+      Boolean(unit.name.trim()) &&
+      ((positive(unit.metersPerUnit) && unit.degreesPerUnit === undefined) ||
+        (positive(unit.degreesPerUnit) && unit.metersPerUnit === undefined)),
+    'unit'
+  );
+  return Object.freeze(
+    unit.metersPerUnit !== undefined
+      ? {name: unit.name, metersPerUnit: unit.metersPerUnit}
+      : {name: unit.name, degreesPerUnit: unit.degreesPerUnit}
+  );
+}
+
+function copyScale(value: CRSRenderingScale): CRSRenderingScale {
+  requireSynchronous(value);
+  requireValue(
+    Array.isArray(value) && value.length === 3 && [...value].every(positive),
+    'renderingScale'
+  );
+  return Object.freeze([...value]) as CRSRenderingScale;
+}
+
+function positive(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
+function requireSynchronous(value: unknown): void {
+  if (value && typeof (value as {then?: unknown}).then === 'function') {
+    // Observe a rejected accidental async result without creating an unhandled rejection.
+    // This cannot cancel work already started by a contract-violating backend.
+    void Promise.resolve(value).catch(() => undefined);
+    throw new TypeError('Invalid CRS descriptor result: synchronous callbacks required');
+  }
+}
+
+function requireValue(condition: boolean, field: string): asserts condition {
+  if (!condition) throw new TypeError(`Invalid CRS descriptor ${field}`);
+}

package/src/crs/crs-metadata.ts

@@ -0,0 +1,63 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+// Metadata-only entry: importing units/signatures must not pull syntax readers into split bundles.
+export {linearUnits} from './units-table';
+
+/** Coordinate unit metadata. */
+export type CRSUnit = Readonly<{
+  /** Unit name, such as degrees, radians, meters, kilometers, or feet. */
+  name: string;
+  /** Metres per coordinate unit for linear units; omitted for angular units. */
+  metersPerUnit?: number;
+  /** Degrees per coordinate unit for angular units; omitted for linear units. */
+  degreesPerUnit?: number;
+}>;
+
+/** Resolved executable CRS metadata, without projection algorithms or rendering conventions. */
+export type CRSMetadata = Readonly<{
+  /** Coordinate representation; identity describes an explicitly local, unreferenced space. */
+  coordinateFrame: 'geographic' | 'projected' | 'geocentric' | 'identity';
+  /** Backend projection name; native engines use PROJ algorithm names. Not a semantic CRS identity. */
+  projection: string;
+  /** Backend parameters. Native engines use resolved PROJ parameters: degrees for angles, metres for lengths. */
+  parameters: Readonly<Record<string, string | undefined>>;
+  /** Resolved rotational ellipsoid. A sphere has equal axes; both axes are in metres. */
+  ellipsoid: Readonly<{semiMajorAxis: number; semiMinorAxis: number}>;
+  /** Effective array axis order/signs: e/w, n/s, u/d. Independent of authoritative axis order. */
+  axis: string;
+  /** Unit of the X component, such as degrees, radians, meters, kilometers, or feet. */
+  xUnit: CRSUnit;
+  /** Unit of the Y component, such as degrees, radians, meters, kilometers, or feet. */
+  yUnit: CRSUnit;
+  /** Unit of the Z component, such as degrees, radians, meters, kilometers, or feet. */
+  zUnit: CRSUnit;
+  /** Declared geographic area of use in Greenwich degrees: west, south, east, north.
+   * East may be less than west for an extent crossing the antimeridian.
+   */
+  areaOfUse?: readonly [west: number, south: number, east: number, north: number];
+  /** Whether explicit horizontal extraction discarded part of the input definition. */
+  lossy: boolean;
+}>;
+
+/** Deterministic identity for resolved CRS metadata, independent of object/property order.
+ * This compares execution conventions, not arbitrary semantic equivalence of CRS definitions.
+ */
+export function getCRSSignature(crs: CRSMetadata): string {
+  // Derived rendering bounds and converter objects do not change resolved CRS identity.
+  return JSON.stringify([
+    crs.coordinateFrame,
+    crs.projection,
+    Object.keys(crs.parameters)
+      .sort()
+      .map(key => [key, crs.parameters[key]]),
+    [crs.ellipsoid.semiMajorAxis, crs.ellipsoid.semiMinorAxis],
+    crs.axis,
+    [crs.xUnit.name, crs.xUnit.metersPerUnit, crs.xUnit.degreesPerUnit],
+    [crs.yUnit.name, crs.yUnit.metersPerUnit, crs.yUnit.degreesPerUnit],
+    [crs.zUnit.name, crs.zUnit.metersPerUnit, crs.zUnit.degreesPerUnit],
+    crs.lossy,
+    crs.areaOfUse
+  ]);
+}

package/src/crs/crs.ts

@@ -0,0 +1,36 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {PROJJSONCRS} from './projjson-types';
+
+/** A registered or named CRS identifier, such as `EPSG:4326` or `WGS84`. */
+export type CRSIdentifier = string;
+
+/** A coordinate reference system serialized using WKT1 or WKT2. */
+export type WKTCRSDefinition = string;
+
+/** A coordinate reference system serialized using PROJ string syntax. */
+export type PROJStringDefinition = string;
+
+/** A serialized or named coordinate reference system definition. */
+export type CRSStringDefinition = CRSIdentifier | WKTCRSDefinition | PROJStringDefinition;
+
+/** Top-level coordinate reference system object types defined by PROJJSON v0.7. */
+export type PROJJSONCRSType = NonNullable<PROJJSONCRS['type']>;
+
+type PROJJSONCRSBranchByType<CRS, T> = CRS extends {type?: infer Type}
+  ? T extends Type
+    ? CRS & {type: T}
+    : never
+  : never;
+
+/** Selects PROJJSON CRS objects with a specific required top-level `type`. */
+export type PROJJSONCRSByType<T extends PROJJSONCRSType> = T extends unknown
+  ? PROJJSONCRSBranchByType<PROJJSONCRS, T>
+  : never;
+
+/** A serialized CRS definition or a standards-based PROJJSON CRS object. */
+export type CRSDefinition<T extends PROJJSONCRS = PROJJSONCRS> = CRSStringDefinition | T;
+
+export type {PROJJSONCRS};

package/src/crs/execution-identity.ts

@@ -0,0 +1,98 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {CRSDescriptor} from './crs-descriptor-types';
+import {createCRSProjectionDomain} from './projection-domain';
+
+/** Caller-declared execution provenance, not inferred from CRS metadata or callback code.
+ * Change this snapshot whenever any converter's behavior changes. Resource values must
+ * identify contents (e.g. checksums or immutable dataset versions), not mutable URLs.
+ */
+export type CRSExecutionIdentity = Readonly<{
+  backend: string;
+  version: string;
+  /** Selected operation/pipeline and policies applying to all supplied source converters. */
+  operation: string;
+  parameters?: Readonly<Record<string, string | number | boolean | null>>;
+  resources?: Readonly<Record<string, string>>;
+  /** Additional caller revision, including callback state or domain sampling policy. */
+  revision?: string;
+}>;
+
+/** Validate and freeze an execution identity without loading engines or hashing resources. */
+export function createCRSExecutionIdentity(identity: CRSExecutionIdentity): CRSExecutionIdentity {
+  if (!identity || typeof identity !== 'object') throw new TypeError('Invalid execution identity');
+  const backend = nonempty(identity.backend);
+  const version = nonempty(identity.version);
+  const operation = nonempty(identity.operation);
+  const parameters = copyRecord(identity.parameters, false);
+  const resources = copyRecord(identity.resources, true) as Readonly<Record<string, string>>;
+  return Object.freeze({
+    backend,
+    version,
+    operation,
+    parameters,
+    resources,
+    ...(identity.revision === undefined ? {} : {revision: nonempty(identity.revision)})
+  });
+}
+
+/** Deterministic opaque execution key, or null when execution identity is unknown.
+ * Includes CRS signature, converter names and explicit domain geometry. It is not a CRS
+ * equivalence test, cryptographic digest, or complete rendered-mesh cache key. Callers must
+ * also key source data, source CRS, direction, attributes, tessellation and view policy.
+ * Supplying incomplete provenance can still produce unsafe reuse; function bodies and
+ * external resources cannot be inspected here. Recreate descriptors when callbacks change.
+ */
+export function getCRSExecutionKey(descriptor: CRSDescriptor): string | null {
+  if (descriptor.executionIdentity === undefined) return null;
+  const identity = createCRSExecutionIdentity(descriptor.executionIdentity);
+  const domain =
+    descriptor.projectionDomain === undefined
+      ? null
+      : createCRSProjectionDomain(descriptor.projectionDomain);
+  return JSON.stringify([
+    'math.gl/crs-execution/v1',
+    descriptor.signature,
+    identity,
+    Object.keys(descriptor.converter).sort(),
+    domain
+  ]);
+}
+
+function nonempty(value: string): string {
+  if (typeof value !== 'string' || !value.trim())
+    throw new TypeError('Invalid execution identity string');
+  return value;
+}
+function copyRecord(value: CRSExecutionIdentity['parameters'], stringsOnly: boolean) {
+  if (value === undefined) return Object.freeze({});
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  )
+    throw new TypeError('Invalid execution identity record');
+  const result = Object.create(null) as Record<string, string | number | boolean | null>;
+  for (const key of Object.keys(value).sort()) {
+    nonempty(key);
+    const item = value[key];
+    if (stringsOnly) nonempty(item as string);
+    else if (
+      !(
+        item === null ||
+        typeof item === 'string' ||
+        typeof item === 'boolean' ||
+        (typeof item === 'number' && Number.isFinite(item))
+      )
+    )
+      throw new TypeError('Invalid execution parameter');
+    // JSON collapses -0 and 0; reject it rather than claiming identical execution.
+    if (Object.is(item, -0))
+      throw new TypeError('Execution parameters cannot contain negative zero');
+    result[key] = item;
+  }
+  return Object.freeze(result);
+}