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

package/src/raster-set.ts

@@ -10,57 +10,76 @@ import type {
 } from '@loaders.gl/loader-utils';
 
 /** Accepted raster request currently retained by {@link RasterSet}. */
-export type RasterSetRequest<DataT = RasterData> = {
+export type RasterSetRequest<
+  DataT extends RasterData = RasterData,
+  ParametersT extends object = GetRasterParameters
+> = {
   /** Unique request id assigned by the manager. */
   requestId: number;
   /** Raster request parameters that produced the accepted raster payload. */
-  parameters: GetRasterParameters;
+  parameters: ParametersT;
   /** Raster retained as the current output. */
   raster: DataT;
 };
 
 /** Arguments supplied to {@link RasterSetBaseProps.shouldRefetch}. */
-export type RasterSetShouldRefetchArgs<DataT = RasterData> = {
+export type RasterSetShouldRefetchArgs<
+  DataT extends RasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = {
   /** Current accepted request retained by the raster manager, if any. */
-  currentRequest: RasterSetRequest<DataT> | null;
+  currentRequest: RasterSetRequest<DataT, ParametersT> | null;
   /** Source metadata resolved by {@link RasterSet.loadMetadata}, if available. */
-  metadata: RasterSourceMetadata | null;
+  metadata: MetadataT | null;
   /** Candidate raster request parameters under evaluation. */
-  nextParameters: GetRasterParameters;
+  nextParameters: ParametersT;
 };
 
 /** Configuration shared by all {@link RasterSet} instances. */
-export type RasterSetBaseProps<DataT = RasterData> = {
+export type RasterSetBaseProps<
+  DataT extends RasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = {
   /** Callback used to load source metadata. */
-  getMetadata: () => Promise<RasterSourceMetadata>;
+  getMetadata: () => Promise<MetadataT>;
   /** Callback used to load raster data for a viewport-derived request. */
-  getRaster: (parameters: GetRasterParameters) => Promise<DataT>;
+  getRaster: (parameters: ParametersT) => Promise<DataT>;
   /** Debounce interval applied before issuing raster requests. */
   debounceTime?: number;
   /** Optional policy callback that can skip redundant raster requests. */
-  shouldRefetch?: (args: RasterSetShouldRefetchArgs<DataT>) => boolean;
+  shouldRefetch?: (args: RasterSetShouldRefetchArgs<DataT, ParametersT, MetadataT>) => boolean;
 };
 
 /** Options for creating a {@link RasterSet}. */
-export type RasterSetProps<DataT = RasterData> = Partial<RasterSetBaseProps<DataT>> & {
+export type RasterSetProps<
+  DataT extends RasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = Partial<RasterSetBaseProps<DataT, ParametersT, MetadataT>> & {
   /** Optional loaders.gl raster source backing this manager. */
-  rasterSource?: RasterSource | null;
+  rasterSource?: RasterSource<DataT, ParametersT & GetRasterParameters, MetadataT> | null;
 };
 
 /** Subscription callbacks emitted by {@link RasterSet}. */
-export type RasterSetListener<DataT = RasterData> = {
+export type RasterSetListener<
+  DataT extends RasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> = {
   /** Fired when metadata/raster loading starts or stops. */
   onLoadingStateChange?: (isLoading: boolean) => void;
   /** Fired when source metadata resolves successfully. */
-  onMetadataLoad?: (metadata: RasterSourceMetadata) => void;
+  onMetadataLoad?: (metadata: MetadataT) => void;
   /** Fired when metadata loading fails. */
   onMetadataLoadError?: (error: Error) => void;
   /** Fired when a new raster request is issued. */
-  onRasterLoadStart?: (requestId: number, parameters: GetRasterParameters) => void;
+  onRasterLoadStart?: (requestId: number, parameters: ParametersT) => void;
   /** Fired when a raster request resolves and becomes current. */
-  onRasterLoad?: (request: RasterSetRequest<DataT>) => void;
+  onRasterLoad?: (request: RasterSetRequest<DataT, ParametersT>) => void;
   /** Fired when a raster request fails. */
-  onRasterLoadError?: (requestId: number, error: Error, parameters: GetRasterParameters) => void;
+  onRasterLoadError?: (requestId: number, error: Error, parameters: ParametersT) => void;
   /** Fired when metadata or the current raster changes. */
   onUpdate?: () => void;
 };
@@ -84,14 +103,24 @@ const DEFAULT_RASTERSET_PROPS: Required<Omit<RasterSetProps, 'rasterSource'>> =
   shouldRefetch: () => true
 };
 
-/** Shared raster request manager used by viewport-driven raster examples and layers. */
-export class RasterSet<DataT = RasterData> {
+/**
+ * Shared raster request manager used by viewport-driven raster examples and layers.
+ *
+ * @typeParam DataT Raster payload retained by the manager.
+ * @typeParam ParametersT Request parameters accepted by the source.
+ * @typeParam MetadataT Metadata returned by the source.
+ */
+export class RasterSet<
+  DataT extends RasterData = RasterData,
+  ParametersT extends object = GetRasterParameters,
+  MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+> {
   /** Cached metadata returned by the backing source, if any. */
-  metadata: RasterSourceMetadata | null = null;
+  metadata: MetadataT | null = null;
 
-  private _opts: Required<RasterSetProps<DataT>>;
-  private _listeners = new Set<RasterSetListener<DataT>>();
-  private _currentRequest: RasterSetRequest<DataT> | null = null;
+  private _opts: Required<RasterSetProps<DataT, ParametersT, MetadataT>>;
+  private _listeners = new Set<RasterSetListener<DataT, ParametersT, MetadataT>>();
+  private _currentRequest: RasterSetRequest<DataT, ParametersT> | null = null;
   private _lastAcceptedRequestId = -1;
   private _nextRequestId = 0;
   private _loadCounter = 0;
@@ -100,7 +129,7 @@ export class RasterSet<DataT = RasterData> {
   private _finalized = false;
 
   /** Creates a raster manager from a source or direct callbacks. */
-  constructor(opts: RasterSetProps<DataT>) {
+  constructor(opts: RasterSetProps<DataT, ParametersT, MetadataT>) {
     this._opts = this._normalizeOptions(opts);
     if (!this._opts.rasterSource && (!opts.getRaster || !opts.getMetadata)) {
       throw new Error(
@@ -110,11 +139,29 @@ export class RasterSet<DataT = RasterData> {
   }
 
   /** Convenience factory for wrapping a loaders.gl {@link RasterSource}. */
-  static fromRasterSource<DataT = RasterData>(
-    rasterSource: RasterSource,
-    opts: Omit<RasterSetProps<DataT>, 'rasterSource' | 'getRaster' | 'getMetadata'> = {}
-  ): RasterSet<DataT> {
-    return new RasterSet<DataT>({...opts, rasterSource});
+  static fromRasterSource<
+    DataT extends RasterData = RasterData,
+    ParametersT extends GetRasterParameters = GetRasterParameters,
+    MetadataT extends RasterSourceMetadata = RasterSourceMetadata
+  >(
+    rasterSource: RasterSource<DataT, ParametersT, MetadataT>,
+    opts: Omit<
+      RasterSetProps<DataT, ParametersT, MetadataT>,
+      'rasterSource' | 'getRaster' | 'getMetadata'
+    > = {}
+  ): RasterSet<DataT, ParametersT, MetadataT> {
+    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. */
@@ -128,23 +175,23 @@ export class RasterSet<DataT = RasterData> {
   }
 
   /** Current accepted request and raster payload, if any. */
-  get currentRequest(): RasterSetRequest<DataT> | null {
+  get currentRequest(): RasterSetRequest<DataT, ParametersT> | null {
     return this._currentRequest;
   }
 
   /** Backing raster source when constructed from one. */
-  get rasterSource(): RasterSource | null {
+  get rasterSource(): RasterSource<DataT, ParametersT & GetRasterParameters, MetadataT> | null {
     return this._opts.rasterSource;
   }
 
   /** Subscribes to metadata and raster lifecycle events. */
-  subscribe(listener: RasterSetListener<DataT>): () => void {
+  subscribe(listener: RasterSetListener<DataT, ParametersT, MetadataT>): () => void {
     this._listeners.add(listener);
     return () => this._listeners.delete(listener);
   }
 
   /** Updates source callbacks or debounce settings, resetting state when the source changes. */
-  setOptions(opts: RasterSetProps<DataT>): void {
+  setOptions(opts: RasterSetProps<DataT, ParametersT, MetadataT>): void {
     const previousRasterSource = this._opts.rasterSource;
     const nextOptions = this._normalizeOptions({...this._opts, ...opts});
     const sourceChanged =
@@ -165,7 +212,7 @@ export class RasterSet<DataT = RasterData> {
   }
 
   /** Loads metadata from the current raster source or callbacks. */
-  async loadMetadata(): Promise<RasterSourceMetadata> {
+  async loadMetadata(): Promise<MetadataT> {
     this._startLoading();
     try {
       const metadata = await this._opts.getMetadata();
@@ -192,7 +239,7 @@ export class RasterSet<DataT = RasterData> {
   }
 
   /** Debounces and issues a new raster request for the supplied parameters. */
-  requestRaster(parameters: GetRasterParameters, debounceTime = this._opts.debounceTime): number {
+  requestRaster(parameters: ParametersT, debounceTime = this._opts.debounceTime): number {
     if (!this.shouldRefetchRaster(parameters)) {
       return this._currentRequest?.requestId ?? -1;
     }
@@ -213,7 +260,7 @@ export class RasterSet<DataT = RasterData> {
   }
 
   /** Returns `true` when the supplied parameters warrant a new raster fetch. */
-  shouldRefetchRaster(parameters: GetRasterParameters): boolean {
+  shouldRefetchRaster(parameters: ParametersT): boolean {
     return this._opts.shouldRefetch({
       currentRequest: this._currentRequest,
       metadata: this.metadata,
@@ -230,7 +277,7 @@ export class RasterSet<DataT = RasterData> {
   }
 
   /** Loads a raster immediately and accepts it only if it is the newest completed request. */
-  private async _loadRaster(requestId: number, parameters: GetRasterParameters): Promise<void> {
+  private async _loadRaster(requestId: number, parameters: ParametersT): Promise<void> {
     if (this._finalized) {
       return;
     }
@@ -243,7 +290,9 @@ export class RasterSet<DataT = RasterData> {
     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 ||
@@ -276,7 +325,9 @@ export class RasterSet<DataT = RasterData> {
   }
 
   /** Resolves current options from either a source or direct callbacks. */
-  private _normalizeOptions(opts: RasterSetProps<DataT>): Required<RasterSetProps<DataT>> {
+  private _normalizeOptions(
+    opts: RasterSetProps<DataT, ParametersT, MetadataT>
+  ): Required<RasterSetProps<DataT, ParametersT, MetadataT>> {
     const rasterSource = opts.rasterSource || null;
     return {
       ...DEFAULT_RASTERSET_PROPS,
@@ -288,22 +339,24 @@ export class RasterSet<DataT = RasterData> {
           if (rasterSource) {
             return rasterSource.getMetadata();
           }
-          return DEFAULT_RASTERSET_PROPS.getMetadata();
+          return DEFAULT_RASTERSET_PROPS.getMetadata() as Promise<MetadataT>;
         }),
       getRaster:
         opts.getRaster ||
-        ((parameters: GetRasterParameters) => {
+        ((parameters: ParametersT) => {
           if (rasterSource) {
-            return rasterSource.getRaster(parameters) as Promise<DataT>;
+            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:
         (opts.shouldRefetch as
-          | ((args: RasterSetShouldRefetchArgs<DataT>) => boolean)
+          | ((args: RasterSetShouldRefetchArgs<DataT, ParametersT, MetadataT>) => boolean)
           | undefined) ||
-        ((args: RasterSetShouldRefetchArgs<DataT>) =>
+        ((args: RasterSetShouldRefetchArgs<DataT, ParametersT, MetadataT>) =>
           DEFAULT_RASTERSET_PROPS.shouldRefetch(args as RasterSetShouldRefetchArgs))
     };
   }
@@ -357,6 +410,26 @@ export class RasterSet<DataT = RasterData> {
   }
 }
 
+/** 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;
+}