@loaders.gl/tiles 5.0.0-alpha.2 → 5.0.0-alpha.3

package/src/raster-set.ts

@@ -12,7 +12,7 @@ import type {
 /** Accepted raster request currently retained by {@link RasterSet}. */
 export type RasterSetRequest<
   DataT extends RasterData = RasterData,
-  ParametersT extends GetRasterParameters = GetRasterParameters
+  ParametersT extends object = GetRasterParameters
 > = {
   /** Unique request id assigned by the manager. */
   requestId: number;
@@ -25,7 +25,7 @@ export type RasterSetRequest<
 /** Arguments supplied to {@link RasterSetBaseProps.shouldRefetch}. */
 export type RasterSetShouldRefetchArgs<
   DataT extends RasterData = RasterData,
-  ParametersT extends GetRasterParameters = GetRasterParameters,
+  ParametersT extends object = GetRasterParameters,
   MetadataT extends RasterSourceMetadata = RasterSourceMetadata
 > = {
   /** Current accepted request retained by the raster manager, if any. */
@@ -39,7 +39,7 @@ export type RasterSetShouldRefetchArgs<
 /** Configuration shared by all {@link RasterSet} instances. */
 export type RasterSetBaseProps<
   DataT extends RasterData = RasterData,
-  ParametersT extends GetRasterParameters = GetRasterParameters,
+  ParametersT extends object = GetRasterParameters,
   MetadataT extends RasterSourceMetadata = RasterSourceMetadata
 > = {
   /** Callback used to load source metadata. */
@@ -55,17 +55,17 @@ export type RasterSetBaseProps<
 /** Options for creating a {@link RasterSet}. */
 export type RasterSetProps<
   DataT extends RasterData = RasterData,
-  ParametersT extends GetRasterParameters = GetRasterParameters,
+  ParametersT extends object = GetRasterParameters,
   MetadataT extends RasterSourceMetadata = RasterSourceMetadata
 > = Partial<RasterSetBaseProps<DataT, ParametersT, MetadataT>> & {
   /** Optional loaders.gl raster source backing this manager. */
-  rasterSource?: RasterSource<DataT, ParametersT, MetadataT> | null;
+  rasterSource?: RasterSource<DataT, ParametersT & GetRasterParameters, MetadataT> | null;
 };
 
 /** Subscription callbacks emitted by {@link RasterSet}. */
 export type RasterSetListener<
   DataT extends RasterData = RasterData,
-  ParametersT extends GetRasterParameters = GetRasterParameters,
+  ParametersT extends object = GetRasterParameters,
   MetadataT extends RasterSourceMetadata = RasterSourceMetadata
 > = {
   /** Fired when metadata/raster loading starts or stops. */
@@ -112,7 +112,7 @@ const DEFAULT_RASTERSET_PROPS: Required<Omit<RasterSetProps, 'rasterSource'>> =
  */
 export class RasterSet<
   DataT extends RasterData = RasterData,
-  ParametersT extends GetRasterParameters = GetRasterParameters,
+  ParametersT extends object = GetRasterParameters,
   MetadataT extends RasterSourceMetadata = RasterSourceMetadata
 > {
   /** Cached metadata returned by the backing source, if any. */
@@ -153,6 +153,17 @@ export class RasterSet<
     return new RasterSet<DataT, ParametersT, MetadataT>({...opts, rasterSource});
   }
 
+  /** Convenience factory for sources whose requests are not viewport-shaped. */
+  static fromCallbacks<
+    DataT extends RasterData = RasterData,
+    ParametersT extends object = GetRasterParameters,
+    MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+  >(
+    opts: RasterSetBaseProps<DataT, ParametersT, MetadataT>
+  ): RasterSet<DataT, ParametersT, MetadataT> {
+    return new RasterSet<DataT, ParametersT, MetadataT>(opts);
+  }
+
   /** Whether the manager has no requests in flight and a current raster. */
   get isLoaded(): boolean {
     return this._loadCounter === 0 && Boolean(this._currentRequest);
@@ -169,7 +180,7 @@ export class RasterSet<
   }
 
   /** Backing raster source when constructed from one. */
-  get rasterSource(): RasterSource<DataT, ParametersT, MetadataT> | null {
+  get rasterSource(): RasterSource<DataT, ParametersT & GetRasterParameters, MetadataT> | null {
     return this._opts.rasterSource;
   }
 
@@ -279,7 +290,9 @@ export class RasterSet<
     try {
       const abortController = new AbortController();
       this._abortController = abortController;
-      const raster = await this._opts.getRaster({...parameters, signal: abortController.signal});
+      const raster = await this._opts.getRaster(
+        withAbortSignal(parameters, abortController.signal)
+      );
       if (
         this._finalized ||
         abortController.signal.aborted ||
@@ -332,9 +345,11 @@ export class RasterSet<
         opts.getRaster ||
         ((parameters: ParametersT) => {
           if (rasterSource) {
-            return rasterSource.getRaster(parameters);
+            return rasterSource.getRaster(parameters as ParametersT & GetRasterParameters);
           }
-          return DEFAULT_RASTERSET_PROPS.getRaster(parameters) as Promise<DataT>;
+          return DEFAULT_RASTERSET_PROPS.getRaster(
+            parameters as GetRasterParameters
+          ) as Promise<DataT>;
         }),
       debounceTime: opts.debounceTime ?? DEFAULT_RASTERSET_PROPS.debounceTime,
       shouldRefetch:
@@ -395,6 +410,26 @@ export class RasterSet<
   }
 }
 
+/** Adds cancellation to a request while preserving its array/prototype shape. */
+function withAbortSignal<ParametersT extends object>(
+  parameters: ParametersT,
+  signal: AbortSignal
+): ParametersT {
+  const request = Array.isArray(parameters)
+    ? parameters.slice()
+    : Object.create(
+        Object.getPrototypeOf(parameters),
+        Object.getOwnPropertyDescriptors(parameters)
+      );
+  Object.defineProperty(request, 'signal', {
+    configurable: true,
+    enumerable: true,
+    value: signal,
+    writable: true
+  });
+  return request as ParametersT;
+}
+
 /** Normalizes arbitrary thrown values to `Error` instances for raster-set callbacks. */
 function normalizeRasterSetError(error: unknown, message: string): Error {
   if (error instanceof Error) {

package/src/spatial/format-spatial-reference.ts

@@ -0,0 +1,311 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ReadonlyCRSDefinition} from '@math.gl/crs';
+import {getI3SLinearUnitScale, getI3SVerticalUnitScale} from './i3s-elevation';
+import {createTilesetSpatialReference} from './spatial-types';
+import type {TilesetElevationMode, TilesetSpatialReference} from './spatial-types';
+
+/** ArcGIS/I3S spatial reference fields used without depending on the I3S package. */
+type I3SSpatialReferenceLike = {
+  wkid?: number;
+  latestWkid?: number;
+  vcsWkid?: number;
+  latestVcsWkid?: number;
+  wkt?: string;
+};
+
+/** I3S layer fields needed for spatial metadata discovery. */
+type I3SLayerLike = {
+  spatialReference?: I3SSpatialReferenceLike;
+  fullExtent?: {spatialReference?: I3SSpatialReferenceLike};
+  heightModelInfo?: {
+    heightModel?: string;
+    vertCRS?: ReadonlyCRSDefinition;
+    heightUnit?: string;
+  };
+  ZFactor?: number;
+  elevationInfo?: {mode?: string; offset?: number; unit?: string};
+};
+
+/** 3D Tiles metadata schema property used for semantic lookup. */
+type Tiles3DMetadataProperty = {semantic?: string};
+
+/** 3D Tiles document fields needed for CRS semantic discovery. */
+type Tiles3DLike = {
+  schema?: {
+    classes?: Record<string, unknown>;
+  };
+  schemaUri?: string;
+  metadata?: {class?: string; properties?: Record<string, unknown>};
+  root?: {boundingVolume?: {region?: unknown}};
+};
+
+/**
+ * Discovers normalized spatial metadata from an I3S scene-layer document.
+ *
+ * I3S encodes geographic coordinates in longitude/latitude wire order even for authority
+ * definitions whose formal axis order differs.
+ *
+ * @param layer - Parsed I3S layer document.
+ * @returns Normalized source spatial metadata.
+ */
+export function getI3SSpatialReference(layer: I3SLayerLike): TilesetSpatialReference {
+  const spatialReference = layer.spatialReference || layer.fullExtent?.spatialReference;
+  const sourceCrs = getI3SCrsDefinition(spatialReference);
+  const verticalCrs =
+    layer.heightModelInfo?.vertCRS || getI3SVerticalCrsDefinition(spatialReference);
+  const heightModel = layer.heightModelInfo?.heightModel;
+  const verticalUnit = layer.heightModelInfo?.heightUnit;
+  const verticalUnitScale = getI3SVerticalUnitScale(verticalUnit, layer.ZFactor);
+  const heightReference =
+    heightModel === 'ellipsoidal'
+      ? 'ellipsoidal'
+      : heightModel === 'gravity_related_height'
+        ? 'orthometric'
+        : 'unknown';
+  const sourceIdentifier = getCrsIdentifier(spatialReference);
+  const coordinateFrame =
+    sourceIdentifier === undefined
+      ? getWktCoordinateFrame(spatialReference?.wkt)
+      : getIdentifierCoordinateFrame(sourceIdentifier);
+  const units = getI3SCoordinateUnits(coordinateFrame, verticalUnit, layer.ZFactor);
+  const warnings: string[] = [];
+  const elevationMode = getI3SElevationMode(layer.elevationInfo?.mode);
+  const elevationUnit = layer.elevationInfo ? layer.elevationInfo.unit || 'meter' : undefined;
+  const elevationUnitScale = getI3SLinearUnitScale(elevationUnit);
+  if (verticalUnitScale === undefined) {
+    warnings.push(
+      layer.ZFactor !== undefined
+        ? `I3S ZFactor ${layer.ZFactor} is not a positive finite conversion factor`
+        : `Unsupported I3S vertical unit ${verticalUnit}`
+    );
+  }
+  if (layer.elevationInfo && elevationUnitScale === undefined) {
+    warnings.push(`Unsupported I3S elevation unit ${elevationUnit}`);
+  }
+  if (layer.elevationInfo?.mode && !elevationMode) {
+    warnings.push(`Unsupported I3S elevation mode ${layer.elevationInfo.mode}`);
+  }
+  if (elevationMode && elevationMode !== 'absoluteHeight') {
+    warnings.push(
+      `I3S elevation mode ${elevationMode} requires a terrain or scene elevation provider`
+    );
+  }
+
+  return createTilesetSpatialReference({
+    sourceCrs,
+    sourceCrsRepresentation:
+      sourceIdentifier !== undefined ? 'identifier' : sourceCrs ? 'wkt' : undefined,
+    sourceCrsAlternatives:
+      sourceIdentifier !== undefined && spatialReference?.wkt
+        ? [{definition: spatialReference.wkt, representation: 'wkt'}]
+        : undefined,
+    verticalCrs,
+    units,
+    verticalUnitScale: verticalUnitScale ?? Number.NaN,
+    heightReference,
+    elevationMode,
+    elevationOffset: layer.elevationInfo?.offset,
+    elevationUnit,
+    elevationUnitScale:
+      layer.elevationInfo?.mode && !elevationMode
+        ? Number.NaN
+        : (elevationUnitScale ?? (layer.elevationInfo ? Number.NaN : 1)),
+    coordinateFrame,
+    axisOrder: sourceCrs ? 'xyz' : 'unknown',
+    provenance: sourceCrs ? 'metadata' : 'unknown',
+    warnings
+  });
+}
+
+/** Return per-component I3S units only when their coordinate association is unambiguous. */
+function getI3SCoordinateUnits(
+  coordinateFrame: TilesetSpatialReference['coordinateFrame'],
+  verticalUnit: string | undefined,
+  zFactor: number | undefined
+): readonly string[] | undefined {
+  if (coordinateFrame === 'geocentric') {
+    return ['meter', 'meter', 'meter'];
+  }
+  if (coordinateFrame === 'geographic' && (verticalUnit || zFactor === undefined)) {
+    return ['degree', 'degree', verticalUnit || 'meter'];
+  }
+  return undefined;
+}
+
+/** Return a supported I3S elevation mode without widening the public descriptor. */
+function getI3SElevationMode(mode: string | undefined): TilesetElevationMode | undefined {
+  switch (mode) {
+    case 'absoluteHeight':
+    case 'onTheGround':
+    case 'relativeToGround':
+    case 'relativeToScene':
+      return mode;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Discovers the 3D Tiles geocentric CRS and coordinate epoch from structured metadata semantics.
+ *
+ * The method intentionally does not infer ECEF from coordinate magnitude. A root `region`
+ * establishes the format's global ellipsoidal frame, while local tilesets without an explicit
+ * semantic remain unknown.
+ *
+ * @param tileset - Parsed 3D Tiles tileset document.
+ * @returns Normalized source spatial metadata.
+ */
+export function get3DTilesSpatialReference(tileset: Tiles3DLike): TilesetSpatialReference {
+  const geocentricCrs = getTilesetSemanticValue(tileset, 'TILESET_CRS_GEOCENTRIC');
+  const coordinateEpoch = getTilesetSemanticValue(tileset, 'TILESET_CRS_COORDINATE_EPOCH');
+  const warnings: string[] = [];
+
+  let sourceCrs: ReadonlyCRSDefinition | undefined;
+  let provenance: TilesetSpatialReference['provenance'] = 'unknown';
+  let sourceCrsState: 'explicit' | 'default' | 'unknown' | 'absent' | undefined;
+  if (typeof geocentricCrs === 'string' && geocentricCrs.toUpperCase() !== 'UNKNOWN') {
+    sourceCrs = geocentricCrs;
+    provenance = 'metadata';
+    sourceCrsState = 'explicit';
+  } else if (geocentricCrs !== undefined) {
+    warnings.push('3D Tiles geocentric CRS is explicitly unknown');
+    provenance = 'metadata';
+    sourceCrsState = 'unknown';
+  } else if (tileset.root?.boundingVolume?.region) {
+    sourceCrs = 'EPSG:4978';
+    provenance = 'format-default';
+    sourceCrsState = 'default';
+  } else if (tileset.schemaUri && !tileset.schema) {
+    warnings.push(
+      'External 3D Tiles metadata schema must be loaded before CRS semantics can resolve'
+    );
+  }
+
+  const epoch = parseCoordinateEpoch(coordinateEpoch);
+  if (coordinateEpoch !== undefined && epoch === undefined) {
+    warnings.push('3D Tiles coordinate epoch is not a finite decimal year');
+  }
+
+  return createTilesetSpatialReference({
+    sourceCrs,
+    sourceCrsState,
+    sourceCrsRepresentation: sourceCrs ? 'identifier' : undefined,
+    coordinateEpoch: epoch,
+    heightReference: sourceCrs ? 'ellipsoidal' : 'unknown',
+    coordinateFrame: sourceCrs ? 'geocentric' : 'unknown',
+    axisOrder: sourceCrs ? 'xyz' : 'unknown',
+    provenance,
+    warnings
+  });
+}
+
+/** Parse the 3D Tiles decimal-year string while tolerating legacy numeric producer output. */
+function parseCoordinateEpoch(value: unknown): number | undefined {
+  if (typeof value !== 'string' && typeof value !== 'number') {
+    return undefined;
+  }
+  if (typeof value === 'string' && !value.trim()) {
+    return undefined;
+  }
+  const epoch = Number(value);
+  return Number.isFinite(epoch) ? epoch : undefined;
+}
+
+/** Return an I3S horizontal CRS definition, preferring current WKID aliases over legacy values. */
+function getI3SCrsDefinition(
+  spatialReference?: I3SSpatialReferenceLike
+): ReadonlyCRSDefinition | undefined {
+  const identifier = getCrsIdentifier(spatialReference);
+  if (identifier !== undefined) {
+    return `EPSG:${identifier}`;
+  }
+  return spatialReference?.wkt;
+}
+
+/** Return an I3S vertical CRS definition. */
+function getI3SVerticalCrsDefinition(
+  spatialReference?: I3SSpatialReferenceLike
+): ReadonlyCRSDefinition | undefined {
+  const identifier = spatialReference?.latestVcsWkid ?? spatialReference?.vcsWkid;
+  return identifier === undefined ? undefined : `EPSG:${identifier}`;
+}
+
+/** Return the preferred horizontal WKID. */
+function getCrsIdentifier(spatialReference?: I3SSpatialReferenceLike): number | undefined {
+  return spatialReference?.latestWkid ?? spatialReference?.wkid;
+}
+
+/** Classify common EPSG identifiers used by I3S into their coordinate frames. */
+function getIdentifierCoordinateFrame(
+  identifier: number
+): TilesetSpatialReference['coordinateFrame'] {
+  if (identifier === 4978) {
+    return 'geocentric';
+  }
+  if (identifier === 4326 || identifier === 4490 || identifier === 4979) {
+    return 'geographic';
+  }
+  return 'projected';
+}
+
+/**
+ * Classify a WKT root coordinate system without guessing when the declaration is ambiguous.
+ *
+ * WKT2 uses `GEODCRS` for both geographic and geocentric systems, so its `CS` declaration is
+ * inspected before assigning a frame.
+ */
+function getWktCoordinateFrame(wkt?: string): TilesetSpatialReference['coordinateFrame'] {
+  if (!wkt) {
+    return 'unknown';
+  }
+
+  const normalizedWkt = wkt.trim().toUpperCase();
+  const rootKeyword = normalizedWkt.match(/^([A-Z][A-Z0-9_]*)\s*[\[(]/)?.[1];
+  if (rootKeyword === 'GEOCCS') {
+    return 'geocentric';
+  }
+  if (
+    rootKeyword === 'GEOGCS' ||
+    rootKeyword === 'GEOGRAPHICCRS' ||
+    rootKeyword === 'GEOGRAPHIC2DCRS' ||
+    rootKeyword === 'GEOGRAPHIC3DCRS'
+  ) {
+    return 'geographic';
+  }
+  if (rootKeyword === 'PROJCS' || rootKeyword === 'PROJCRS' || rootKeyword === 'PROJECTEDCRS') {
+    return 'projected';
+  }
+  if (rootKeyword === 'GEODCRS' || rootKeyword === 'GEODETICCRS') {
+    if (/\bCS\s*[\[(]\s*CARTESIAN\s*,\s*3\b/.test(normalizedWkt)) {
+      return 'geocentric';
+    }
+    if (/\bCS\s*[\[(]\s*ELLIPSOIDAL\s*,\s*[23]\b/.test(normalizedWkt)) {
+      return 'geographic';
+    }
+  }
+  return 'unknown';
+}
+
+/** Resolve a tileset-wide structured metadata property by its standard semantic. */
+function getTilesetSemanticValue(tileset: Tiles3DLike, semantic: string): unknown {
+  const classIdentifier = tileset.metadata?.class;
+  if (!classIdentifier) {
+    return undefined;
+  }
+  const classDefinition = tileset.schema?.classes?.[classIdentifier] as
+    | {properties?: Record<string, Tiles3DMetadataProperty>}
+    | undefined;
+  const propertyDefinitions = classDefinition?.properties;
+  const propertyValues = tileset.metadata?.properties;
+  for (const [propertyIdentifier, propertyDefinition] of Object.entries(
+    propertyDefinitions || {}
+  )) {
+    if (propertyDefinition.semantic === semantic) {
+      return propertyValues?.[propertyIdentifier];
+    }
+  }
+  return undefined;
+}

package/src/spatial/get-spatial-coordinate-frame.ts

@@ -0,0 +1,74 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ReadonlyCRSDefinition, SpatialReferenceCoordinateFrame} from '@math.gl/crs';
+
+const GEOGRAPHIC_CRS = 'EPSG:4326';
+const GEOCENTRIC_CRS = 'EPSG:4978';
+
+/** Normalize common OGC URL and URN CRS spellings to authority identifiers. */
+function normalizeCrsIdentifier(identifier: string): string {
+  const normalizedIdentifier = identifier.trim().toUpperCase();
+  const ogcMatch = normalizedIdentifier.match(
+    /(?:\/DEF\/CRS\/|URN:OGC:DEF:CRS:)([A-Z0-9_-]+)(?:\/|::)(?:[^/:]*[/:])?([A-Z0-9_.-]+)$/
+  );
+  return ogcMatch ? `${ogcMatch[1]}:${ogcMatch[2]}` : normalizedIdentifier;
+}
+
+/**
+ * Classify a CRS definition into the broad coordinate frame used by 3D format adapters.
+ *
+ * @param definition - CRS definition to classify.
+ * @returns The broad geographic, geocentric, projected, local, or unknown frame.
+ */
+export function getSpatialCoordinateFrame(
+  definition: ReadonlyCRSDefinition
+): SpatialReferenceCoordinateFrame {
+  if (typeof definition === 'string') {
+    const normalized = normalizeCrsIdentifier(definition);
+    if (normalized === GEOCENTRIC_CRS || /^GEOCCS\s*[\[(]/.test(normalized)) {
+      return 'geocentric';
+    }
+    if (
+      normalized === GEOGRAPHIC_CRS ||
+      normalized === 'EPSG:4490' ||
+      normalized === 'EPSG:4979' ||
+      normalized === 'OGC:CRS84' ||
+      normalized.includes('+PROJ=LONGLAT') ||
+      normalized.includes('+PROJ=LATLONG') ||
+      /^(?:GEOGCS|GEOGCRS|GEOGRAPHICCRS|GEOGRAPHIC2DCRS|GEOGRAPHIC3DCRS)\s*[\[(]/.test(normalized)
+    ) {
+      return 'geographic';
+    }
+    if (/^(?:GEODCRS|GEODETICCRS)\s*[\[(]/.test(normalized)) {
+      return /CS\s*[\[(]\s*CARTESIAN/.test(normalized) ? 'geocentric' : 'geographic';
+    }
+    return 'projected';
+  }
+
+  const projJsonDefinition = definition as {
+    type?: string;
+    source_crs?: ReadonlyCRSDefinition;
+    components?: readonly ReadonlyCRSDefinition[];
+    coordinate_system?: {subtype?: string};
+  };
+  if (projJsonDefinition.type === 'BoundCRS' && projJsonDefinition.source_crs) {
+    return getSpatialCoordinateFrame(projJsonDefinition.source_crs);
+  }
+  if (projJsonDefinition.type === 'CompoundCRS' && projJsonDefinition.components?.[0]) {
+    return getSpatialCoordinateFrame(projJsonDefinition.components[0]);
+  }
+  if (String(projJsonDefinition.type).includes('Projected')) {
+    return 'projected';
+  }
+  if (String(projJsonDefinition.type).includes('Geographic')) {
+    return 'geographic';
+  }
+  if (String(projJsonDefinition.type).includes('Geodetic')) {
+    return projJsonDefinition.coordinate_system?.subtype === 'Cartesian'
+      ? 'geocentric'
+      : 'geographic';
+  }
+  return 'projected';
+}

package/src/spatial/i3s-elevation.ts

@@ -0,0 +1,96 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+const LINEAR_UNIT_TO_METERS: Readonly<Record<string, number>> = Object.freeze({
+  meter: 1,
+  millimeter: 0.001,
+  centimeter: 0.01,
+  decimeter: 0.1,
+  kilometer: 1000,
+  foot: 0.3048,
+  yard: 0.9144,
+  mile: 1609.344,
+  'us-foot': 1200 / 3937,
+  'us-inch': 0.0254000508001016,
+  'us-yard': 3600 / 3937,
+  'us-mile': 6336000 / 3937,
+  'clarke-foot': 0.3047972654,
+  'clarke-yard': 0.9143917962,
+  'clarke-link': 0.201166195164,
+  'sears-yard': 0.914398414616,
+  'sears-foot': 0.304799471539,
+  'sears-chain': 20.1167651216,
+  'sears-1922-truncated-chain': 20.116756,
+  'benoit-1895-b-chain': 20.1167824944,
+  'indian-yard': 0.914398530744,
+  'indian-1937-yard': 0.91439523,
+  'gold-coast-foot': 0.304799710181
+});
+
+const LINEAR_UNIT_ALIASES: Readonly<Record<string, string>> = Object.freeze({
+  m: 'meter',
+  metre: 'meter',
+  meters: 'meter',
+  metres: 'meter',
+  mm: 'millimeter',
+  millimetre: 'millimeter',
+  millimeters: 'millimeter',
+  millimetres: 'millimeter',
+  cm: 'centimeter',
+  centimetre: 'centimeter',
+  centimeters: 'centimeter',
+  centimetres: 'centimeter',
+  dm: 'decimeter',
+  decimetre: 'decimeter',
+  decimeters: 'decimeter',
+  decimetres: 'decimeter',
+  km: 'kilometer',
+  kilometre: 'kilometer',
+  kilometers: 'kilometer',
+  kilometres: 'kilometer',
+  ft: 'foot',
+  feet: 'foot',
+  'us-survey-foot': 'us-foot',
+  'us-survey-feet': 'us-foot',
+  yd: 'yard',
+  yards: 'yard',
+  mi: 'mile',
+  miles: 'mile'
+});
+
+/**
+ * Resolves an ArcGIS/I3S linear unit to meters.
+ *
+ * @param unit - I3S `heightUnit`, `elevationInfo.unit`, or provider unit.
+ * @returns Meters per unit, or `undefined` when the declaration is unsupported.
+ */
+export function getI3SLinearUnitScale(unit: string | undefined): number | undefined {
+  if (!unit) {
+    return undefined;
+  }
+  const normalized = unit.trim().toLowerCase().replaceAll('_', '-');
+  const canonical = LINEAR_UNIT_ALIASES[normalized] || normalized;
+  return LINEAR_UNIT_TO_METERS[canonical];
+}
+
+/**
+ * Resolves the source-Z conversion declared by an I3S layer.
+ *
+ * Legacy `ZFactor` is an explicit conversion to meters and takes precedence over the descriptive
+ * `heightUnit`. This avoids applying the same feet-to-meters conversion twice on layers that
+ * publish both fields.
+ *
+ * @param heightUnit - Unit declared by `heightModelInfo.heightUnit`.
+ * @param zFactor - Legacy layer conversion factor.
+ * @returns Meters per stored Z unit, or `undefined` for an invalid declaration.
+ */
+export function getI3SVerticalUnitScale(
+  heightUnit: string | undefined,
+  zFactor: number | undefined
+): number | undefined {
+  if (zFactor !== undefined) {
+    return Number.isFinite(zFactor) && zFactor > 0 ? zFactor : undefined;
+  }
+  return heightUnit ? getI3SLinearUnitScale(heightUnit) : 1;
+}