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

package/src/projection/experimental/crs/ellipsoid-table.ts

@@ -0,0 +1,230 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2014 Mike Adair, Richard Greenwood, Didier Richard, Stephen Irons, Olivier Terral and Calvin Metcalf (proj4js)
+// SPDX-FileComment: Direct TypeScript port of proj4js 2.22.0. See ../../../../projection/PROJ4-LICENSE.md.
+
+const ellipsoids: Record<string, {a: number; b?: number; rf?: number; ellipseName: string}> = {
+  MERIT: {
+    a: 6378137,
+    rf: 298.257,
+    ellipseName: 'MERIT 1983'
+  },
+  SGS85: {
+    a: 6378136,
+    rf: 298.257,
+    ellipseName: 'Soviet Geodetic System 85'
+  },
+  GRS80: {
+    a: 6378137,
+    rf: 298.257222101,
+    ellipseName: 'GRS 1980(IUGG, 1980)'
+  },
+  IAU76: {
+    a: 6378140,
+    rf: 298.257,
+    ellipseName: 'IAU 1976'
+  },
+  airy: {
+    a: 6377563.396,
+    b: 6356256.91,
+    ellipseName: 'Airy 1830'
+  },
+  APL4: {
+    a: 6378137,
+    rf: 298.25,
+    ellipseName: 'Appl. Physics. 1965'
+  },
+  NWL9D: {
+    a: 6378145,
+    rf: 298.25,
+    ellipseName: 'Naval Weapons Lab., 1965'
+  },
+  mod_airy: {
+    a: 6377340.189,
+    b: 6356034.446,
+    ellipseName: 'Modified Airy'
+  },
+  andrae: {
+    a: 6377104.43,
+    rf: 300,
+    ellipseName: 'Andrae 1876 (Den., Iclnd.)'
+  },
+  aust_SA: {
+    a: 6378160,
+    rf: 298.25,
+    ellipseName: 'Australian Natl & S. Amer. 1969'
+  },
+  GRS67: {
+    a: 6378160,
+    rf: 298.247167427,
+    ellipseName: 'GRS 67(IUGG 1967)'
+  },
+  bessel: {
+    a: 6377397.155,
+    rf: 299.1528128,
+    ellipseName: 'Bessel 1841'
+  },
+  bess_nam: {
+    a: 6377483.865,
+    rf: 299.1528128,
+    ellipseName: 'Bessel 1841 (Namibia)'
+  },
+  clrk66: {
+    a: 6378206.4,
+    b: 6356583.8,
+    ellipseName: 'Clarke 1866'
+  },
+  clrk80: {
+    a: 6378249.145,
+    rf: 293.4663,
+    ellipseName: 'Clarke 1880 mod.'
+  },
+  clrk80ign: {
+    a: 6378249.2,
+    b: 6356515,
+    rf: 293.4660213,
+    ellipseName: 'Clarke 1880 (IGN)'
+  },
+  clrk58: {
+    a: 6378293.645208759,
+    rf: 294.2606763692654,
+    ellipseName: 'Clarke 1858'
+  },
+  CPM: {
+    a: 6375738.7,
+    rf: 334.29,
+    ellipseName: 'Comm. des Poids et Mesures 1799'
+  },
+  delmbr: {
+    a: 6376428,
+    rf: 311.5,
+    ellipseName: 'Delambre 1810 (Belgium)'
+  },
+  engelis: {
+    a: 6378136.05,
+    rf: 298.2566,
+    ellipseName: 'Engelis 1985'
+  },
+  evrst30: {
+    a: 6377276.345,
+    rf: 300.8017,
+    ellipseName: 'Everest 1830'
+  },
+  evrst48: {
+    a: 6377304.063,
+    rf: 300.8017,
+    ellipseName: 'Everest 1948'
+  },
+  evrst56: {
+    a: 6377301.243,
+    rf: 300.8017,
+    ellipseName: 'Everest 1956'
+  },
+  evrst69: {
+    a: 6377295.664,
+    rf: 300.8017,
+    ellipseName: 'Everest 1969'
+  },
+  evrstSS: {
+    a: 6377298.556,
+    rf: 300.8017,
+    ellipseName: 'Everest (Sabah & Sarawak)'
+  },
+  fschr60: {
+    a: 6378166,
+    rf: 298.3,
+    ellipseName: 'Fischer (Mercury Datum) 1960'
+  },
+  fschr60m: {
+    a: 6378155,
+    rf: 298.3,
+    ellipseName: 'Fischer 1960'
+  },
+  fschr68: {
+    a: 6378150,
+    rf: 298.3,
+    ellipseName: 'Fischer 1968'
+  },
+  helmert: {
+    a: 6378200,
+    rf: 298.3,
+    ellipseName: 'Helmert 1906'
+  },
+  hough: {
+    a: 6378270,
+    rf: 297,
+    ellipseName: 'Hough'
+  },
+  intl: {
+    a: 6378388,
+    rf: 297,
+    ellipseName: 'International 1909 (Hayford)'
+  },
+  kaula: {
+    a: 6378163,
+    rf: 298.24,
+    ellipseName: 'Kaula 1961'
+  },
+  lerch: {
+    a: 6378139,
+    rf: 298.257,
+    ellipseName: 'Lerch 1979'
+  },
+  mprts: {
+    a: 6397300,
+    rf: 191,
+    ellipseName: 'Maupertius 1738'
+  },
+  new_intl: {
+    a: 6378157.5,
+    b: 6356772.2,
+    ellipseName: 'New International 1967'
+  },
+  plessis: {
+    a: 6376523,
+    b: 6355863,
+    ellipseName: 'Plessis 1817 (France)'
+  },
+  krass: {
+    a: 6378245,
+    rf: 298.3,
+    ellipseName: 'Krassovsky, 1942'
+  },
+  SEasia: {
+    a: 6378155,
+    b: 6356773.3205,
+    ellipseName: 'Southeast Asia'
+  },
+  walbeck: {
+    a: 6376896,
+    b: 6355834.8467,
+    ellipseName: 'Walbeck'
+  },
+  WGS60: {
+    a: 6378165,
+    rf: 298.3,
+    ellipseName: 'WGS 60'
+  },
+  WGS66: {
+    a: 6378145,
+    rf: 298.25,
+    ellipseName: 'WGS 66'
+  },
+  WGS72: {
+    a: 6378135,
+    rf: 298.26,
+    ellipseName: 'WGS 72'
+  },
+  WGS84: {
+    a: 6378137,
+    rf: 298.257223563,
+    ellipseName: 'WGS 84'
+  },
+  sphere: {
+    a: 6370997,
+    b: 6370997,
+    ellipseName: 'Normal Sphere (r=6370997)'
+  }
+};
+
+export default ellipsoids;

package/src/projection/experimental/crs/normalize.ts

@@ -0,0 +1,318 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import {inferCRSRepresentation} from '../../../crs/spatial-reference';
+import {parsePROJString} from '../../../crs/proj-string';
+import {applySpatialReference, resolveCRSInput} from './spatial-reference';
+import type {TypeScriptCRSInput} from './spatial-reference';
+import {DEGREES_TO_RADIANS, numberParameter} from '../parameters';
+import type {ProjectionParameters} from '../types';
+import {getDatumDefinitions} from './datum-catalog';
+import ellipsoids from './ellipsoid-table';
+import primeMeridians from './primemeridian-table';
+import {linearUnits} from '../../../crs/crs-metadata';
+import {TypeScriptCRSError, unsupportedStage} from './types';
+import type {CRSNormalizationOptions, Ellipsoid, NormalizedCRS, ParsedCRS} from './types';
+import type {ReadonlyCRSDefinition} from '../../../crs/spatial-reference';
+
+const ALIASES: Readonly<Record<string, string>> = {
+  WGS84: '+proj=longlat +datum=WGS84',
+  'EPSG:4326': '+proj=longlat +datum=WGS84',
+  'EPSG:4269': '+proj=longlat +datum=NAD83',
+  'EPSG:4978': '+proj=geocent +datum=WGS84',
+  'EPSG:4979': '+proj=longlat +datum=WGS84',
+  'EPSG:3857': '+proj=merc +a=6378137 +b=6378137 +nadgrids=@null +units=m',
+  'EPSG:3785': 'EPSG:3857',
+  GOOGLE: 'EPSG:3857',
+  'EPSG:900913': 'EPSG:3857',
+  'EPSG:102113': 'EPSG:3857'
+};
+export const CORE_PARAMETERS = [
+  'proj',
+  'datum',
+  'ellps',
+  'a',
+  'b',
+  'rf',
+  'f',
+  'R',
+  'units',
+  'to_meter',
+  'vunits',
+  'vto_meter',
+  'no_defs',
+  'type',
+  'title',
+  'towgs84',
+  'nadgrids',
+  'geoidgrids',
+  'axis',
+  'pm',
+  'over',
+  'lon_wrap'
+];
+export const CORE_FLAGS = ['no_defs', 'over'];
+const own = (object: object, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(object, key);
+const keyOf = (value: string): string => value.toLowerCase().replace(/[\s_-]/g, '');
+function lookup<T>(table: Record<string, T>, name: string): T | undefined {
+  const key = Object.keys(table).find(key => keyOf(key) === keyOf(name));
+  return key === undefined ? undefined : table[key];
+}
+
+/** PROJ decimal, radians (r), and DMS angles; normalized output is decimal degrees. */
+export function parseAngle(text: string): number {
+  if (/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(text)) {
+    const value = Number(text);
+    if (Number.isFinite(value)) return value;
+  }
+  if (/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?r$/i.test(text)) {
+    const value = Number(text.slice(0, -1)) / DEGREES_TO_RADIANS;
+    if (Number.isFinite(value)) return value;
+  }
+  const dms =
+    /^([+-]?)(\d+(?:\.\d*)?)(?:d(?:(\d+(?:\.\d*)?)'(?:(\d+(?:\.\d*)?)")?)?)?([NSEW])?$/i.exec(text);
+  if (dms && (/d/i.test(text) || dms[5])) {
+    const minutes = Number(dms[3] || 0),
+      seconds = Number(dms[4] || 0);
+    if (minutes < 60 && seconds < 60) {
+      const sign = dms[1] === '-' ? -1 : 1;
+      const direction = /[SW]/i.test(dms[5] || '') ? -1 : 1;
+      const value = sign * direction * (Number(dms[2]) + minutes / 60 + seconds / 3600);
+      if (Number.isFinite(value)) return value;
+    }
+  }
+  throw new Error('Invalid angular parameter: ' + text);
+}
+
+/** Expand local aliases and built-in identifiers without executing or parsing a projection. */
+export function resolveLocalCRSDefinition(
+  input: ReadonlyCRSDefinition,
+  options: CRSNormalizationOptions = {}
+): ReadonlyCRSDefinition {
+  let definition = input;
+  const aliases = options.aliases || {};
+  const visited = new Set<string>();
+  while (typeof definition === 'string' && (own(aliases, definition) || own(ALIASES, definition))) {
+    if (visited.has(definition)) throw new Error('Circular CRS alias: ' + definition);
+    visited.add(definition);
+    definition = own(aliases, definition) ? aliases[definition] : ALIASES[definition];
+  }
+  if (typeof definition === 'string') {
+    const utm = /^EPSG:(326|327)(\d{2})$/.exec(definition);
+    if (utm && Number(utm[2]) >= 1 && Number(utm[2]) <= 60) {
+      definition =
+        '+proj=utm +datum=WGS84 +zone=' + Number(utm[2]) + (utm[1] === '327' ? ' +south' : '');
+    }
+    if (definition === 'EPSG:5041' || definition === 'EPSG:5042') {
+      definition =
+        '+proj=stere +datum=WGS84 +lat_0=' +
+        (definition === 'EPSG:5041' ? 90 : -90) +
+        ' +k_0=0.994 +x_0=2000000 +y_0=2000000';
+    }
+  }
+  return definition;
+}
+
+export function normalizeCRS(
+  input: TypeScriptCRSInput,
+  options: CRSNormalizationOptions = {}
+): NormalizedCRS {
+  const datums = getDatumDefinitions(options);
+  const resolved = resolveCRSInput(input, options);
+  const definition = resolveLocalCRSDefinition(resolved.definition, options);
+  let parsed: ParsedCRS;
+  if (inferCRSRepresentation(definition) === 'proj-string' && typeof definition === 'string') {
+    const parameters: Record<string, string | undefined> = Object.create(null);
+    for (const parameter of parsePROJString(definition).parameters) {
+      if (own(parameters, parameter.name))
+        throw new Error('Duplicate PROJ parameter: +' + parameter.name);
+      parameters[parameter.name] = parameter.value;
+    }
+    parsed = {parameters};
+  } else {
+    const parser = options.parsers?.find(candidate => candidate.canParse(definition));
+    if (!parser) {
+      const serialized = ['wkt', 'projjson'].includes(inferCRSRepresentation(definition));
+      throw new TypeScriptCRSError(
+        serialized ? 'missing-parser' : 'unknown-syntax',
+        inferCRSRepresentation(definition) === 'identifier'
+          ? 'Unsupported CRS definition: ' + definition + '; resolve it first'
+          : 'Unsupported CRS definition; register a WKT or PROJJSON parser for structured definitions'
+      );
+    }
+    parsed = parser.parse(definition, options);
+  }
+  const parameters = {...parsed.parameters};
+  for (const name of [
+    'lon_0',
+    'lat_0',
+    'lat_1',
+    'lat_2',
+    'lat_ts',
+    'lon_wrap',
+    'lon_1',
+    'lon_2',
+    'lonc',
+    'alpha',
+    'gamma',
+    'tilt',
+    'azi',
+    'o_alpha',
+    'o_lon_c',
+    'o_lat_c',
+    'o_lon_p',
+    'o_lat_p',
+    'o_lon_1',
+    'o_lat_1',
+    'o_lon_2',
+    'o_lat_2'
+  ]) {
+    if (parameters[name] !== undefined) parameters[name] = String(parseAngle(parameters[name]));
+  }
+  const suppliedName = parameters['proj'];
+  const lowerName = suppliedName?.toLowerCase();
+  const name =
+    lowerName === 'geocentric'
+      ? 'geocent'
+      : ['longlat', 'latlong', 'latlon', 'lonlat', 'identity', 'geocent'].includes(lowerName)
+        ? lowerName
+        : suppliedName;
+  if (!name) throw new Error('CRS requires +proj');
+  const kind = ['longlat', 'latlong', 'latlon', 'lonlat'].includes(name)
+    ? 'geographic'
+    : name === 'geocent'
+      ? 'geocentric'
+      : name === 'identity'
+        ? 'identity'
+        : 'projected';
+  const datumName = parameters['datum'];
+  const datum = datumName && datumName !== 'none' ? lookup(datums, datumName) : undefined;
+  if (datumName && datumName !== 'none' && !datum)
+    unsupportedStage('Unknown datum: ' + datumName + '; register a datumCatalogs plugin');
+  const ellipsoid = getEllipsoid(parameters, datum?.ellipse);
+  const grids = parameters['nadgrids'] ?? datum?.nadgrids;
+  const gridReferences =
+    grids === undefined
+      ? undefined
+      : grids.split(',').map(entry => {
+          const optional = entry.startsWith('@');
+          const name = optional ? entry.slice(1) : entry;
+          if (!name || /\s/.test(name)) throw new Error('Invalid datum grid name');
+          return Object.freeze({name, optional});
+        });
+  const rawShift = parameters['towgs84'] ?? datum?.towgs84;
+  let shift: readonly number[] | undefined;
+  if (rawShift !== undefined) {
+    shift = rawShift.split(',').map(value => numberParameter({value}, 'value', NaN));
+    if (
+      ![3, 7].includes(shift.length) ||
+      shift.some(value => !Number.isFinite(value)) ||
+      (shift.length === 7 && shift[6] <= -1e6)
+    ) {
+      throw new Error('+towgs84 requires three or seven finite values and positive scale');
+    }
+  }
+  if (datumName === 'none') shift = undefined;
+  if (gridReferences && datumName !== 'none') shift = [0, 0, 0];
+  const datumEllipsoid =
+    grids === '@null' || grids === 'null' ? getEllipsoid({ellps: 'WGS84'}) : ellipsoid;
+  const axis = parameters['axis'] || 'enu';
+  if (axis.length !== 3 || !/[ew]/.test(axis) || !/[ns]/.test(axis) || !/[ud]/.test(axis))
+    throw new Error('Invalid axis: ' + axis);
+  const angularUnit = parsed.angularUnit ?? DEGREES_TO_RADIANS;
+  if (
+    kind === 'geographic' &&
+    ((parameters['units'] && parameters['units'] !== 'degrees') || own(parameters, 'to_meter'))
+  )
+    throw new Error('Geographic coordinates must use angular units');
+  if (kind !== 'geographic' && parameters['units'] === 'degrees')
+    throw new Error('Linear coordinates require linear units');
+  const toMeter = unitFactor(parameters, 'units', 'to_meter');
+  const verticalUnit = parsed.verticalUnit ?? unitFactor(parameters, 'vunits', 'vto_meter');
+  if (!(verticalUnit > 0) || !Number.isFinite(verticalUnit))
+    throw new Error('Invalid vertical unit');
+  if (!(angularUnit > 0) || !Number.isFinite(angularUnit)) throw new Error('Invalid angular unit');
+  const pm = parameters['pm'];
+  const primeMeridian =
+    pm === undefined ? 0 : (lookup(primeMeridians, pm) ?? parseAngle(pm)) * DEGREES_TO_RADIANS;
+  return applySpatialReference(
+    Object.freeze({
+      kind,
+      projection: name,
+      parameters: Object.freeze(parameters),
+      ellipsoid,
+      datum: Object.freeze({
+        ellipsoid: datumEllipsoid,
+        towgs84: shift && Object.freeze(shift),
+        grids:
+          datumName === 'none' || grids === '@null' || grids === 'null'
+            ? undefined
+            : gridReferences && Object.freeze(gridReferences)
+      }),
+      areaOfUse: parsed.areaOfUse,
+      angularUnit,
+      toMeter,
+      verticalUnit,
+      primeMeridian,
+      axis,
+      longitudeWrap:
+        parameters['lon_wrap'] === undefined
+          ? undefined
+          : Number(parameters['lon_wrap']) * DEGREES_TO_RADIANS,
+      lossy: Boolean(parsed.lossy || resolved.lossy)
+    }),
+    resolved.spatialReference
+  );
+}
+function unitFactor(parameters: ProjectionParameters, unitKey: string, factorKey: string): number {
+  const unit = parameters[unitKey];
+  const table = linearUnits;
+  if (unitKey === 'vunits' && unit === 'degrees') throw new Error('Height requires linear units');
+  if (unit && !['m', 'degrees'].includes(unit) && !own(table, unit))
+    throw new Error('Unsupported units: ' + unit);
+  const factor = numberParameter(
+    parameters,
+    factorKey,
+    unit && table[unit] ? table[unit].metersPerUnit : 1
+  );
+  if (!(factor > 0)) throw new Error('+' + factorKey + ' must be positive');
+  return factor;
+}
+function getEllipsoid(parameters: ProjectionParameters, datumEllipsoid?: string): Ellipsoid {
+  const name = datumEllipsoid || parameters['ellps'] || 'WGS84';
+  const definition = lookup(ellipsoids, name);
+  if (!definition) throw new Error('Unsupported ellipsoid: ' + name);
+  const a = numberParameter(parameters, 'a', definition.a);
+  const f = numberParameter(parameters, 'f', NaN);
+  const rf = numberParameter(
+    parameters,
+    'rf',
+    Number.isNaN(f) ? definition.rf || 0 : f === 0 ? 0 : 1 / f
+  );
+  const b = numberParameter(
+    parameters,
+    'b',
+    rf
+      ? a * (1 - 1 / rf)
+      : own(parameters, 'f') || own(parameters, 'rf') || own(parameters, 'a')
+        ? a
+        : definition.b || a
+  );
+  const radius = numberParameter(parameters, 'R', 0);
+  if (
+    a <= 0 ||
+    b <= 0 ||
+    b > a ||
+    rf < 0 ||
+    (rf > 0 && rf <= 1) ||
+    (own(parameters, 'R') && radius <= 0) ||
+    (!Number.isNaN(f) && (f < 0 || f >= 1))
+  )
+    throw new Error('Invalid ellipsoid dimensions');
+  return Object.freeze({
+    semiMajorAxis: radius || a,
+    semiMinorAxis: radius || b,
+    eccentricitySquared: radius ? 0 : 1 - (b / a) ** 2
+  });
+}

package/src/projection/experimental/crs/primemeridian-table.ts

@@ -0,0 +1,22 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2014 Mike Adair, Richard Greenwood, Didier Richard, Stephen Irons, Olivier Terral and Calvin Metcalf (proj4js)
+// SPDX-FileComment: Direct TypeScript port of proj4js 2.22.0. See ../../../../projection/PROJ4-LICENSE.md.
+
+const primeMeridian: Record<string, number> = {};
+
+primeMeridian['greenwich'] = 0.0; // "0dE",
+primeMeridian['lisbon'] = -9.131906111111; // "9d07'54.862\"W",
+primeMeridian['paris'] = 2.337229166667; // "2d20'14.025\"E",
+primeMeridian['bogota'] = -74.080916666667; // "74d04'51.3\"W",
+primeMeridian['madrid'] = -3.687938888889; // "3d41'16.58\"W",
+primeMeridian['rome'] = 12.452333333333; // "12d27'8.4\"E",
+primeMeridian['bern'] = 7.439583333333; // "7d26'22.5\"E",
+primeMeridian['jakarta'] = 106.807719444444; // "106d48'27.79\"E",
+primeMeridian['ferro'] = -17.666666666667; // "17d40'W",
+primeMeridian['brussels'] = 4.367975; // "4d22'4.71\"E",
+primeMeridian['stockholm'] = 18.058277777778; // "18d3'29.8\"E",
+primeMeridian['athens'] = 23.7163375; // "23d42'58.815\"E",
+primeMeridian['oslo'] = 10.722916666667; // "10d43'22.5\"E"
+
+export default primeMeridian;

package/src/projection/experimental/crs/projjson.ts

@@ -0,0 +1,12 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import {inferCRSRepresentation} from '../../../crs/spatial-reference';
+import type {CRSParser} from './types';
+import {object, readStructuredCRS} from './structured';
+/** Opt-in execution adapter for @math.gl/geospatial/crs's readonly PROJJSON CRS union. */
+export const projJSONCRSParser: CRSParser = {
+  name: 'projjson',
+  canParse: definition => inferCRSRepresentation(definition) === 'projjson',
+  parse: (definition, options) => readStructuredCRS(object(definition), options)
+};

package/src/projection/experimental/crs/resolve.ts

@@ -0,0 +1,78 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {inferCRSRepresentation} from '../../../crs/spatial-reference';
+import type {
+  CRSInput,
+  CRSReference,
+  KnownCRSReference,
+  SpatialReference
+} from '../../../crs/spatial-reference';
+import type {CreateProjectionOptions, ProjectionEngineOptions} from '../../types';
+import type {ProjectionDescriptor} from '../projection-descriptor';
+import type {ProjectionPlugin} from '../types';
+import {resolveLocalCRSDefinition} from './normalize';
+import {resolveCRSInput} from './spatial-reference';
+
+type Options = ProjectionEngineOptions<ProjectionPlugin | ProjectionDescriptor> &
+  CreateProjectionOptions;
+
+/** Capture both endpoints before the first asynchronous lookup. */
+export async function prepareEngineOptions<T extends Options>(options: T): Promise<T> {
+  const captured = {
+    ...options,
+    from: capture(options.from ?? 'WGS84'),
+    to: capture(options.to ?? 'WGS84')
+  };
+  const [from, to] = await Promise.all([
+    prepareCRSInput(captured.from, captured),
+    prepareCRSInput(captured.to, captured)
+  ]);
+  return {...captured, from, to};
+}
+
+/** Local aliases/built-ins and registered readers take precedence over external lookup. */
+export async function prepareCRSInput(captured: CRSInput, options: Options): Promise<CRSInput> {
+  // Enforce epoch/vertical policy before attempting lookup; metadata must never be dropped.
+  const source = resolveCRSInput(captured, options);
+  const local = resolveLocalCRSDefinition(source.definition, options);
+  // resolveCRSInput above rejects unknown/absent references. Callers already captured the input.
+  const reference = (
+    typeof captured === 'string' || 'type' in captured
+      ? undefined
+      : 'crs' in captured
+        ? (captured as SpatialReference).crs
+        : (captured as CRSReference)
+  ) as KnownCRSReference | undefined;
+  const representation =
+    local === source.definition && reference
+      ? reference.representation
+      : inferCRSRepresentation(local);
+  if (representation !== 'identifier' || options.parsers?.some(p => p.canParse(local))) {
+    return captured;
+  }
+  const result = await options.resolver!.resolve({
+    state: 'explicit',
+    provenance: reference?.provenance ?? 'unknown',
+    definition: local,
+    representation
+  });
+  const definition = resolveCRSInput(result.input, options).definition;
+  if (!reference) return definition;
+  const metadata = captured as CRSReference | SpatialReference;
+  const resolved = {
+    ...reference,
+    definition,
+    representation: inferCRSRepresentation(definition),
+    alternatives: [
+      {definition: reference.definition, representation: reference.representation},
+      ...(reference.alternatives ?? [])
+    ]
+  };
+  return 'crs' in metadata ? {...metadata, crs: resolved} : resolved;
+}
+
+function capture(input: CRSInput): CRSInput {
+  return typeof input === 'string' ? input : JSON.parse(JSON.stringify(input));
+}