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

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-identifier.ts

@@ -0,0 +1,86 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {CRSIdentifier} from './crs';
+
+/** WMS 1.3 `CRS:` codes and the OGC register entries they abbreviate. */
+const WMS_CRS_CODES = new Map<string, string>([
+  ['84', 'CRS84'],
+  ['83', 'CRS83'],
+  ['27', 'CRS27']
+]);
+/** Explicit input conveniences, not a case-insensitivity rule for all registry names. */
+const KNOWN_AUTHORITIES = new Set(['EPSG', 'OGC', 'ESRI', 'IAU']);
+const OGC_CRS_CODES = new Map<string, string>([
+  ['CRS84', 'CRS84'],
+  ['CRS83', 'CRS83'],
+  ['CRS27', 'CRS27'],
+  ['CRS84H', 'CRS84h']
+]);
+
+const AUTHORITY_CODE = /^([A-Z][A-Z0-9_-]*):([A-Z0-9_.-]+)$/i;
+const OGC_URN = /^urn:ogc:def:crs:([A-Z][A-Z0-9_-]*):([^:]*):([A-Z0-9_.-]+)$/i;
+const OGC_URI =
+  /^https?:\/\/www\.opengis\.net\/def\/crs\/([A-Z][A-Z0-9_-]*)\/([^/]+)\/([A-Z0-9_.-]+)\/?$/i;
+
+/**
+ * Normalizes recognized spellings of an authority CRS identifier to `AUTHORITY:CODE`.
+ *
+ * Recognized forms are `AUTHORITY:CODE`, the WMS 1.3 codes `CRS:84`, `CRS:83` and `CRS:27`,
+ * OGC URNs (`urn:ogc:def:crs:EPSG::32619`) and OGC URIs
+ * (`http://www.opengis.net/def/crs/EPSG/0/32619`). Known authority prefixes (EPSG, OGC, ESRI and IAU) and explicitly known OGC CRS codes
+ * accept case-insensitive input aliases. Other authority and code spellings are preserved.
+ *
+ * A version is removed only when it is empty or `0`, or when it is `1.3` on an OGC `CRS84`,
+ * `CRS83` or `CRS27` code, which the OGC register publishes only at that version. Any other
+ * versioned identifier is returned unchanged, so it does not compare equal to an unversioned one.
+ * Unrecognized strings are also returned unchanged.
+ *
+ * The result identifies a registry entry only. Different codes are never equated: `EPSG:4326` and
+ * `OGC:CRS84` stay distinct, as do Web Mercator aliases. No datum equivalence, axis-order
+ * convention or registry lookup is applied.
+ *
+ * @param identifier - CRS identifier as written by a source or service.
+ * @returns The canonical `AUTHORITY:CODE` identifier, or `identifier` unchanged.
+ */
+export function normalizeCRSIdentifier(identifier: CRSIdentifier): CRSIdentifier {
+  const text = identifier.trim();
+
+  const authorityCode = AUTHORITY_CODE.exec(text);
+  if (authorityCode) {
+    const [, authority, code] = authorityCode;
+    if (authority.toUpperCase() === 'CRS') {
+      const ogcCode = WMS_CRS_CODES.get(code);
+      return ogcCode ? `OGC:${ogcCode}` : identifier;
+    }
+    return formatIdentifier(authority, code);
+  }
+
+  const versioned = OGC_URN.exec(text) || OGC_URI.exec(text);
+  if (versioned) {
+    const [, authority, version, code] = versioned;
+    return isUnversioned(authority, version, code) ? formatIdentifier(authority, code) : identifier;
+  }
+
+  return identifier;
+}
+
+/** Whether a URN or URI version names no particular revision of the registry entry. */
+function isUnversioned(authority: string, version: string, code: string): boolean {
+  if (version === '' || version === '0') return true;
+  const ogcCode = code.toUpperCase();
+  return (
+    authority.toUpperCase() === 'OGC' &&
+    version === '1.3' &&
+    Array.from(WMS_CRS_CODES.values()).includes(ogcCode)
+  );
+}
+
+function formatIdentifier(authority: string, code: string): CRSIdentifier {
+  const upperAuthority = authority.toUpperCase();
+  const canonicalAuthority = KNOWN_AUTHORITIES.has(upperAuthority) ? upperAuthority : authority;
+  const canonicalCode =
+    canonicalAuthority === 'OGC' ? OGC_CRS_CODES.get(code.toUpperCase()) || code : code;
+  return `${canonicalAuthority}:${canonicalCode}`;
+}

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};