@loaders.gl/tiles 5.0.0-alpha.12 → 5.0.0-alpha.13

package/src/spatial/i3s-spatial-transformer.ts

@@ -1,1021 +0,0 @@
-// loaders.gl
-// SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
-
-import {Matrix3, Matrix4, Quaternion, Vector3} from '@math.gl/core';
-import {Ellipsoid} from '@math.gl/geospatial';
-import {
-  getSpatialCoordinateFrame,
-  SpatialCoordinateTransformer
-} from './spatial-coordinate-transformer';
-import {
-  createTilesetSpatialReference,
-  markTilesetSpatialReferenceTransformed
-} from './spatial-types';
-import {getI3SLinearUnitScale} from './i3s-elevation';
-import type {
-  TilesetCoordinateFrame,
-  TilesetElevationBounds,
-  TilesetElevationMode,
-  TilesetElevationProvider,
-  TilesetSpatialOptions,
-  TilesetSpatialReference
-} from './spatial-types';
-
-/** Minimal I3S oriented bounding box required by the spatial adapter. */
-export type I3SSpatialObb = {
-  /** Center in source CRS coordinates. */
-  center: ArrayLike<number>;
-  /** Half lengths along the oriented axes. */
-  halfSize: ArrayLike<number>;
-  /** Orientation quaternion. */
-  quaternion: ArrayLike<number>;
-};
-
-/** Input used to rebuild an I3S node bound in the selected output frame. */
-export type I3SSpatialBounds = {
-  /** Minimum bounding sphere encoded as source center plus radius. */
-  mbs?: ArrayLike<number>;
-  /** Oriented source bound, preferred when available. */
-  obb?: I3SSpatialObb;
-  /** Frame in which I3S vectors and quaternions are expressed. */
-  normalReferenceFrame?: string;
-};
-
-/** Renderer-ready positions and metadata produced for an I3S geometry resource. */
-export type I3STransformedPositions = {
-  /** Float32 offsets from the stable target origin. */
-  positions: Float32Array;
-  /** Reconstructed absolute source positions retained for normal transformation. */
-  sourcePositions: Float64Array;
-  /** Stable origin in target CRS coordinates. */
-  origin: [number, number, number];
-  /** Origin used by geographic deck.gl coordinate systems. */
-  cartographicOrigin: [number, number, number];
-  /** Renderer coordinate-system discriminator. */
-  coordinateSystem: 'cartesian' | 'lnglat-offsets';
-  /** Translation matrix used for Cartesian target offsets. */
-  modelMatrix: Matrix4;
-};
-
-/** Double-precision conversion geometry after I3S units, elevation and CRS placement. */
-export type I3STransformedGeometry = {
-  /** Absolute target xyz positions, before any writer-owned float32 rebasing. */
-  positions: Float64Array;
-  /** Optional unit normals in the target basis. */
-  normals?: Float32Array;
-};
-
-/**
- * Applies one normalized I3S horizontal CRS operation consistently to geometry, normals, origins,
- * and node bounds.
- */
-export class I3SSpatialTransformer {
-  /** Descriptor attached to output after all adapter-owned spatial values have been transformed. */
-  readonly spatialReference: TilesetSpatialReference;
-
-  /** Broad coordinate frame of the selected output CRS. */
-  readonly targetCoordinateFrame: TilesetCoordinateFrame;
-
-  /** Source-to-target position operation. */
-  private readonly positionTransformer: SpatialCoordinateTransformer;
-
-  /** Source-to-WGS84 geographic operation used for vector-frame conversion. */
-  private readonly sourceToGeographicTransformer: SpatialCoordinateTransformer;
-
-  /** WGS84-geographic-to-target operation used for normal finite differences. */
-  private readonly geographicToTargetTransformer: SpatialCoordinateTransformer;
-
-  /** Source frame recorded by I3S metadata. */
-  private readonly sourceCoordinateFrame: TilesetCoordinateFrame;
-
-  /** Source Z multiplier that normalizes stored elevation values to meters. */
-  private readonly sourceVerticalUnitScale: number;
-
-  /** I3S elevation placement mode. */
-  private readonly elevationMode?: TilesetElevationMode;
-
-  /** I3S elevation offset normalized to meters. */
-  private readonly elevationOffset: number;
-
-  /** Terrain or scene provider selected for the declared placement mode. */
-  private readonly elevationProvider?: TilesetElevationProvider;
-
-  /** Provider height multiplier that normalizes returned values to meters. */
-  private readonly providerUnitScale: number;
-
-  /** Optional provider-height to layer-height datum operation. */
-  private readonly providerHeightTransformer?: SpatialCoordinateTransformer;
-
-  /**
-   * Creates an I3S spatial adapter.
-   *
-   * @param spatialReference - Transformable I3S spatial descriptor.
-   * @param options - Registered geoid and custom resource options used by the shared transformer.
-   */
-  constructor(spatialReference: TilesetSpatialReference, options: TilesetSpatialOptions = {}) {
-    if (spatialReference.status !== 'transformable' && spatialReference.status !== 'transformed') {
-      throw new Error('I3SSpatialTransformer requires a requested, transformable spatial output');
-    }
-    const targetCrs = spatialReference.targetCrs || spatialReference.sourceCrs;
-    if (!targetCrs) {
-      throw new Error('I3S spatial transformation requires a target CRS');
-    }
-
-    this.positionTransformer = new SpatialCoordinateTransformer(spatialReference, options);
-    this.sourceCoordinateFrame = spatialReference.coordinateFrame;
-    this.sourceVerticalUnitScale = spatialReference.verticalUnitScale;
-    this.elevationMode = spatialReference.elevationMode;
-    this.elevationOffset =
-      (spatialReference.elevationOffset || 0) * spatialReference.elevationUnitScale;
-    this.elevationProvider = getElevationProvider(this.elevationMode, options);
-    if (
-      this.elevationProvider &&
-      (typeof this.elevationProvider.sampleElevations !== 'function' ||
-        typeof this.elevationProvider.getElevationRange !== 'function')
-    ) {
-      throw new Error(
-        'An I3S elevation provider must implement sampleElevations() and getElevationRange()'
-      );
-    }
-    const providerUnitScale = getI3SLinearUnitScale(this.elevationProvider?.unit || 'meter');
-    if (this.elevationProvider && providerUnitScale === undefined) {
-      throw new Error(`Unsupported elevation-provider unit ${this.elevationProvider.unit}`);
-    }
-    this.providerUnitScale = providerUnitScale || 1;
-    this.targetCoordinateFrame = getSpatialCoordinateFrame(targetCrs);
-    this.spatialReference = markTilesetSpatialReferenceTransformed(spatialReference);
-
-    const sourceToGeographicReference = createTilesetSpatialReference(
-      {
-        sourceCrs: spatialReference.sourceCrs,
-        heightReference: spatialReference.heightReference,
-        coordinateFrame: spatialReference.coordinateFrame,
-        axisOrder: spatialReference.axisOrder,
-        provenance: spatialReference.provenance
-      },
-      {targetCrs: 'EPSG:4326'}
-    );
-    this.sourceToGeographicTransformer = new SpatialCoordinateTransformer(
-      sourceToGeographicReference
-    );
-
-    if (requiresElevationSurface(this.elevationMode)) {
-      if (!this.elevationProvider) {
-        const providerName = this.elevationMode === 'relativeToScene' ? 'scene' : 'terrain';
-        throw new Error(
-          `I3S elevation mode ${this.elevationMode} requires a ${providerName} elevation provider`
-        );
-      }
-      if (spatialReference.heightReference === 'unknown') {
-        throw new Error(
-          `I3S elevation mode ${this.elevationMode} requires a known source height reference`
-        );
-      }
-      const providerHeightReference =
-        this.elevationProvider.heightReference || spatialReference.heightReference;
-      if (providerHeightReference !== spatialReference.heightReference) {
-        if (
-          spatialReference.heightReference !== 'ellipsoidal' &&
-          spatialReference.heightReference !== 'orthometric'
-        ) {
-          throw new Error(
-            'Converting elevation-provider heights requires an ellipsoidal or orthometric source height reference'
-          );
-        }
-        const providerHeightSpatialReference = createTilesetSpatialReference(
-          {
-            sourceCrs: 'EPSG:4326',
-            heightReference: providerHeightReference,
-            coordinateFrame: 'geographic',
-            axisOrder: 'xyz',
-            provenance: 'caller-override'
-          },
-          {
-            targetCrs: 'EPSG:4326',
-            targetHeightReference: spatialReference.heightReference,
-            geoidModel: options.geoidModel
-          }
-        );
-        this.providerHeightTransformer = new SpatialCoordinateTransformer(
-          providerHeightSpatialReference,
-          options
-        );
-      }
-    }
-
-    const geographicToTargetReference = createTilesetSpatialReference(
-      {
-        sourceCrs: 'EPSG:4326',
-        heightReference: spatialReference.heightReference,
-        coordinateFrame: 'geographic',
-        axisOrder: 'xyz',
-        provenance: 'format-default'
-      },
-      {
-        targetCrs,
-        targetHeightReference: spatialReference.targetHeightReference,
-        geoidModel: options.geoidModel
-      }
-    );
-    this.geographicToTargetTransformer = new SpatialCoordinateTransformer(
-      geographicToTargetReference,
-      options
-    );
-  }
-
-  /** Transform one absolute I3S source position. */
-  transformPosition(position: ArrayLike<number>): [number, number, number] {
-    const placedPosition = this.placeSourcePositionsSync(position);
-    const transformed = this.positionTransformer.transformPosition([
-      placedPosition[0],
-      placedPosition[1],
-      placedPosition[2]
-    ]);
-    return [transformed[0], transformed[1], transformed[2]];
-  }
-
-  /** Transform one absolute I3S source position after asynchronous surface placement. */
-  async transformPositionAsync(position: ArrayLike<number>): Promise<[number, number, number]> {
-    const placedPosition = await this.placeSourcePositions(position);
-    const transformed = this.positionTransformer.transformPosition([
-      placedPosition[0],
-      placedPosition[1],
-      placedPosition[2]
-    ]);
-    return [transformed[0], transformed[1], transformed[2]];
-  }
-
-  /** Transform an already placed, meter-normalized position to the requested target. */
-  private transformPlacedPosition(position: ArrayLike<number>): [number, number, number] {
-    const transformed = this.positionTransformer.transformPosition([
-      position[0],
-      position[1],
-      position[2]
-    ]);
-    return [transformed[0], transformed[1], transformed[2]];
-  }
-
-  /** Transform one absolute I3S source position to WGS84 longitude, latitude, and height. */
-  transformSourcePositionToGeographic(position: ArrayLike<number>): [number, number, number] {
-    const placedPosition = this.placeSourcePositionsSync(position);
-    const transformed = this.sourceToGeographicTransformer.transformPosition([
-      placedPosition[0],
-      placedPosition[1],
-      placedPosition[2]
-    ]);
-    return [transformed[0], transformed[1], transformed[2]];
-  }
-
-  /** Transform one source position to WGS84 after asynchronous elevation placement. */
-  async transformSourcePositionToGeographicAsync(
-    position: ArrayLike<number>
-  ): Promise<[number, number, number]> {
-    const placedPosition = await this.placeSourcePositions(position);
-    const transformed = this.sourceToGeographicTransformer.transformPosition([
-      placedPosition[0],
-      placedPosition[1],
-      placedPosition[2]
-    ]);
-    return [transformed[0], transformed[1], transformed[2]];
-  }
-
-  /**
-   * Transform absolute Float64 positions and return stable Float32 offsets around a target origin.
-   *
-   * @param sourcePositions - Absolute positions in source CRS order.
-   * @param sourceOrigin - Stable source origin, normally the node MBS or OBB center.
-   */
-  transformPositions(
-    sourcePositions: ArrayLike<number>,
-    sourceOrigin: ArrayLike<number>
-  ): I3STransformedPositions {
-    const placedSourcePositions = this.placeSourcePositionsSync(sourcePositions);
-    const placedSourceOrigin = this.placeSourcePositionsSync(sourceOrigin);
-    return this.transformPlacedPositions(placedSourcePositions, placedSourceOrigin);
-  }
-
-  /**
-   * Transform positions after asynchronously sampling any requested terrain or scene surface.
-   *
-   * @param sourcePositions - Absolute positions in source CRS order.
-   * @param sourceOrigin - Stable source origin, normally the node MBS or OBB center.
-   * @returns Renderer-ready target-frame offsets and stable origin metadata.
-   */
-  async transformPositionsAsync(
-    sourcePositions: ArrayLike<number>,
-    sourceOrigin: ArrayLike<number>
-  ): Promise<I3STransformedPositions> {
-    const combinedPositions = new Float64Array(sourcePositions.length + 3);
-    combinedPositions.set(Array.from(sourcePositions), 0);
-    combinedPositions.set(Array.from(sourceOrigin).slice(0, 3), sourcePositions.length);
-    const placedPositions = await this.placeSourcePositions(combinedPositions);
-    return this.transformPlacedPositions(
-      placedPositions.subarray(0, sourcePositions.length),
-      placedPositions.subarray(sourcePositions.length)
-    );
-  }
-
-  /**
-   * Transforms conversion geometry without passing through renderer float32 offsets.
-   * Positions and normals share one batch of elevation samples. Source arrays remain unchanged.
-   * @param sourcePositions - Packed absolute xyz positions in source units.
-   * @param normals - Optional packed normals paired with the positions.
-   * @param normalReferenceFrame - I3S earth-centered or vertex-reference-frame declaration.
-   * @returns Absolute target positions and optional transformed normals.
-   */
-  async transformGeometryAsync(
-    sourcePositions: ArrayLike<number>,
-    normals?: ArrayLike<number>,
-    normalReferenceFrame = 'earth-centered'
-  ): Promise<I3STransformedGeometry> {
-    if (sourcePositions.length % 3 || (normals && normals.length !== sourcePositions.length)) {
-      throw new Error('Conversion positions and normals must contain matching finite xyz triples');
-    }
-    for (let index = 0; index < sourcePositions.length; index++) {
-      if (
-        !Number.isFinite(sourcePositions[index]) ||
-        (normals && !Number.isFinite(normals[index]))
-      ) {
-        throw new Error(
-          'Conversion positions and normals must contain matching finite xyz triples'
-        );
-      }
-    }
-    if (!['earth-centered', 'vertex-reference-frame'].includes(normalReferenceFrame)) {
-      throw new Error('Unsupported I3S normal reference frame');
-    }
-    const placedPositions = await this.placeSourcePositions(sourcePositions);
-    return {
-      positions: this.positionTransformer.transformPositions(placedPositions),
-      normals: normals
-        ? this.transformNormals(normals, placedPositions, normalReferenceFrame)
-        : undefined
-    };
-  }
-
-  /** Transform already placed positions into renderer-relative target coordinates. */
-  private transformPlacedPositions(
-    sourcePositions: ArrayLike<number>,
-    sourceOrigin: ArrayLike<number>
-  ): I3STransformedPositions {
-    const origin = this.transformPlacedPosition(sourceOrigin);
-    const positions = new Float32Array(sourcePositions.length);
-    const absoluteSourcePositions = Float64Array.from(sourcePositions);
-
-    for (let index = 0; index < sourcePositions.length; index += 3) {
-      const transformed = this.transformPlacedPosition([
-        sourcePositions[index],
-        sourcePositions[index + 1],
-        sourcePositions[index + 2]
-      ]);
-      positions[index] = transformed[0] - origin[0];
-      positions[index + 1] = transformed[1] - origin[1];
-      positions[index + 2] = transformed[2] - origin[2];
-    }
-
-    const isGeographic = this.targetCoordinateFrame === 'geographic';
-    const modelMatrix = isGeographic ? new Matrix4() : new Matrix4().translate(origin);
-    return {
-      positions,
-      sourcePositions: absoluteSourcePositions,
-      origin,
-      cartographicOrigin: isGeographic ? origin : [0, 0, 0],
-      coordinateSystem: isGeographic ? 'lnglat-offsets' : 'cartesian',
-      modelMatrix
-    };
-  }
-
-  /**
-   * Transform I3S normals into the selected target basis.
-   *
-   * Earth-centered normals are rotated directly. Vertex-reference-frame normals are first mapped
-   * through the local east/north/up basis at each source position.
-   *
-   * @param normals - Three-component normal vectors.
-   * @param sourcePositions - Absolute source position paired with each normal.
-   * @param normalReferenceFrame - I3S normal frame declaration.
-   */
-  transformNormals(
-    normals: ArrayLike<number>,
-    sourcePositions: ArrayLike<number>,
-    normalReferenceFrame = 'earth-centered'
-  ): Float32Array {
-    if (normals.length !== sourcePositions.length || normals.length % 3) {
-      throw new Error('I3S normals and positions must have matching xyz component counts');
-    }
-    const transformedNormals = new Float32Array(normals.length);
-    // Earth-centered I3S normals already use the output ECEF basis; no position projection is needed.
-    if (
-      normalReferenceFrame === 'earth-centered' &&
-      (this.spatialReference.targetCrs || this.spatialReference.sourceCrs) === 'EPSG:4978'
-    ) {
-      for (let index = 0; index < normals.length; index += 3) {
-        const length = Math.hypot(normals[index], normals[index + 1], normals[index + 2]);
-        for (let axis = 0; axis < 3; axis++) {
-          transformedNormals[index + axis] = length
-            ? normals[index + axis] / length
-            : normals[index + axis];
-        }
-      }
-      return transformedNormals;
-    }
-    for (let index = 0; index < normals.length; index += 3) {
-      const geographic = this.sourceToGeographicTransformer.transformPosition([
-        sourcePositions[index],
-        sourcePositions[index + 1],
-        sourcePositions[index + 2]
-      ]);
-      const inputNormal = new Vector3([
-        normals[index],
-        normals[index + 1],
-        normals[index + 2]
-      ]).normalize();
-      const ecefNormal =
-        normalReferenceFrame === 'earth-centered'
-          ? inputNormal
-          : localEnuVectorToEcef(inputNormal, geographic);
-      const outputNormal = this.transformEcefNormal(ecefNormal, geographic);
-      transformedNormals.set(outputNormal, index);
-    }
-    return transformedNormals;
-  }
-
-  /**
-   * Rebuild an I3S node bound from transformed corner or sphere-axis samples.
-   *
-   * @param bounds - Source MBS/OBB fields.
-   * @returns A generic tile `region` for geographic output or axis-aligned `box` otherwise.
-   */
-  transformBoundingVolume(bounds: I3SSpatialBounds): {box?: number[]; region?: number[]} {
-    const geographicSamples = this.getGeographicBoundSamples(bounds);
-    const targetSamples = geographicSamples.map(position =>
-      this.geographicToTargetTransformer.transformPosition(position)
-    );
-    return this.targetCoordinateFrame === 'geographic'
-      ? {region: getGeographicRegion(targetSamples)}
-      : {box: getAxisAlignedBox(targetSamples)};
-  }
-
-  /** Rebuild an I3S bound in the target frame after asynchronous elevation placement. */
-  async transformBoundingVolumeAsync(
-    bounds: I3SSpatialBounds
-  ): Promise<{box?: number[]; region?: number[]}> {
-    const geographicSamples = await this.getGeographicBoundSamplesAsync(bounds);
-    const targetSamples = geographicSamples.map(position =>
-      this.geographicToTargetTransformer.transformPosition(position)
-    );
-    return this.targetCoordinateFrame === 'geographic'
-      ? {region: getGeographicRegion(targetSamples)}
-      : {box: getAxisAlignedBox(targetSamples)};
-  }
-
-  /** Rebuild an I3S bound as a WGS84 geographic region for geographic traversal algorithms. */
-  transformBoundingVolumeToGeographic(bounds: I3SSpatialBounds): {region: number[]} {
-    return {region: getGeographicRegion(this.getGeographicBoundSamples(bounds))};
-  }
-
-  /** Rebuild an I3S bound as WGS84 geographic after asynchronous elevation placement. */
-  async transformBoundingVolumeToGeographicAsync(
-    bounds: I3SSpatialBounds
-  ): Promise<{region: number[]}> {
-    return {region: getGeographicRegion(await this.getGeographicBoundSamplesAsync(bounds))};
-  }
-
-  /** Rebuild an I3S bound as a WGS84 ECEF box for generic `Tileset3D` traversal. */
-  transformBoundingVolumeToGeocentric(bounds: I3SSpatialBounds): {box: number[]} {
-    const cartesianSamples = this.getGeographicBoundSamples(bounds).map(position =>
-      Array.from(Ellipsoid.WGS84.cartographicToCartesian(new Vector3(position)))
-    );
-    return {box: getAxisAlignedBox(cartesianSamples)};
-  }
-
-  /** Rebuild an I3S bound as WGS84 ECEF after asynchronous elevation placement. */
-  async transformBoundingVolumeToGeocentricAsync(
-    bounds: I3SSpatialBounds
-  ): Promise<{box: number[]}> {
-    const cartesianSamples = (await this.getGeographicBoundSamplesAsync(bounds)).map(position =>
-      Array.from(Ellipsoid.WGS84.cartographicToCartesian(new Vector3(position)))
-    );
-    return {box: getAxisAlignedBox(cartesianSamples)};
-  }
-
-  /** Return a WGS84 geographic MBS used by the I3S screen-threshold calculation. */
-  transformBoundingSphereToGeographic(bounds: I3SSpatialBounds): [number, number, number, number] {
-    const sourceCenter = bounds.mbs?.length
-      ? Array.from(bounds.mbs).slice(0, 3)
-      : bounds.obb
-        ? Array.from(bounds.obb.center).slice(0, 3)
-        : null;
-    if (!sourceCenter) {
-      throw new Error('I3S spatial transformation requires an MBS or OBB bound');
-    }
-    const placedCenter = this.placeSourcePositionsSync(sourceCenter);
-    const geographicCenter = this.sourceToGeographicTransformer.transformPosition(
-      Array.from(placedCenter)
-    );
-    const radius = bounds.mbs?.length
-      ? bounds.mbs[3]
-      : Math.hypot(...Array.from(bounds.obb!.halfSize).slice(0, 3));
-    return [geographicCenter[0], geographicCenter[1], geographicCenter[2], radius];
-  }
-
-  /** Return a placed WGS84 MBS used by the I3S screen-threshold calculation. */
-  async transformBoundingSphereToGeographicAsync(
-    bounds: I3SSpatialBounds
-  ): Promise<[number, number, number, number]> {
-    return getGeographicBoundingSphere(await this.getGeographicBoundSamplesAsync(bounds));
-  }
-
-  /**
-   * Rebuild traversal, target-output, and I3S LOD bounds from one elevation-sampling batch.
-   *
-   * @param bounds - Source MBS/OBB fields.
-   * @returns Parallel bounds in WGS84 ECEF, the selected output frame, and WGS84 geographic.
-   */
-  async transformBoundsAsync(bounds: I3SSpatialBounds): Promise<{
-    boundingVolume: {box: number[]};
-    spatialBoundingVolume: {box?: number[]; region?: number[]};
-    i3sLodMbs: [number, number, number, number];
-  }> {
-    const geographicSamples = await this.getGeographicBoundSamplesAsync(bounds);
-    const cartesianSamples = geographicSamples.map(position =>
-      Array.from(Ellipsoid.WGS84.cartographicToCartesian(new Vector3(position)))
-    );
-    const targetSamples = geographicSamples.map(position =>
-      this.geographicToTargetTransformer.transformPosition(position)
-    );
-    return {
-      boundingVolume: {box: getAxisAlignedBox(cartesianSamples)},
-      spatialBoundingVolume:
-        this.targetCoordinateFrame === 'geographic'
-          ? {region: getGeographicRegion(targetSamples)}
-          : {box: getAxisAlignedBox(targetSamples)},
-      i3sLodMbs: requiresElevationSurface(this.elevationMode)
-        ? getGeographicBoundingSphere(geographicSamples)
-        : this.transformBoundingSphereToGeographic(bounds)
-    };
-  }
-
-  /**
-   * Rebuild Point Cloud traversal and target-output bounds from one elevation-sampling batch.
-   *
-   * @param bounds - Source OBB fields.
-   * @returns WGS84 geographic traversal bound plus the selected output-frame bound.
-   */
-  async transformPointCloudBoundsAsync(bounds: I3SSpatialBounds): Promise<{
-    boundingVolume: {region: number[]};
-    spatialBoundingVolume: {box?: number[]; region?: number[]};
-  }> {
-    const geographicSamples = await this.getGeographicBoundSamplesAsync(bounds);
-    const targetSamples = geographicSamples.map(position =>
-      this.geographicToTargetTransformer.transformPosition(position)
-    );
-    return {
-      boundingVolume: {region: getGeographicRegion(geographicSamples)},
-      spatialBoundingVolume:
-        this.targetCoordinateFrame === 'geographic'
-          ? {region: getGeographicRegion(targetSamples)}
-          : {box: getAxisAlignedBox(targetSamples)}
-    };
-  }
-
-  /** Sample a source I3S bound and normalize every sample to WGS84 geographic coordinates. */
-  private getGeographicBoundSamples(bounds: I3SSpatialBounds): number[][] {
-    const sourceSamples = getSourceBoundSamples(
-      bounds,
-      this.sourceCoordinateFrame,
-      this.sourceToGeographicTransformer,
-      this.sourceVerticalUnitScale
-    );
-    if (!sourceSamples.length) {
-      throw new Error('I3S spatial transformation requires an MBS or OBB bound');
-    }
-    const placedSourceSamples = this.placeSourcePositionsSync(sourceSamples.flat(), true);
-    const placedSamples = toPositionArrays(placedSourceSamples);
-    return this.sourceCoordinateFrame === 'geographic'
-      ? placedSamples
-      : placedSamples.map(position =>
-          this.sourceToGeographicTransformer.transformPosition(position)
-        );
-  }
-
-  /** Sample, place, and normalize one source bound to WGS84 geographic coordinates. */
-  private async getGeographicBoundSamplesAsync(bounds: I3SSpatialBounds): Promise<number[][]> {
-    const sourceSamples = getSourceBoundSamples(
-      bounds,
-      this.sourceCoordinateFrame,
-      this.sourceToGeographicTransformer,
-      this.sourceVerticalUnitScale
-    );
-    if (!sourceSamples.length) {
-      throw new Error('I3S spatial transformation requires an MBS or OBB bound');
-    }
-    if (requiresElevationSurface(this.elevationMode)) {
-      const geographicSamples =
-        this.sourceCoordinateFrame === 'geographic'
-          ? sourceSamples
-          : sourceSamples.map(position =>
-              this.sourceToGeographicTransformer.transformPosition(position)
-            );
-      return await this.placeGeographicBoundSamples(geographicSamples);
-    }
-    const placedSamples = toPositionArrays(
-      await this.placeSourcePositions(sourceSamples.flat(), true)
-    );
-    return this.sourceCoordinateFrame === 'geographic'
-      ? placedSamples
-      : placedSamples.map(position =>
-          this.sourceToGeographicTransformer.transformPosition(position)
-        );
-  }
-
-  /** Apply a provider's conservative surface range to an entire geographic bound footprint. */
-  private async placeGeographicBoundSamples(geographicSamples: number[][]): Promise<number[][]> {
-    const elevationProvider = this.elevationProvider!;
-    const elevationRange = await elevationProvider.getElevationRange(
-      getElevationBounds(geographicSamples)
-    );
-    const minimumProviderHeight = elevationRange.minimum * this.providerUnitScale;
-    const maximumProviderHeight = elevationRange.maximum * this.providerUnitScale;
-    if (
-      !Number.isFinite(minimumProviderHeight) ||
-      !Number.isFinite(maximumProviderHeight) ||
-      minimumProviderHeight > maximumProviderHeight
-    ) {
-      throw new Error(
-        'Elevation provider returned an invalid range; minimum and maximum must be finite and ordered'
-      );
-    }
-
-    const sourceHeights = geographicSamples.map(position => position[2]);
-    const minimumSourceHeight = Math.min(...sourceHeights);
-    const maximumSourceHeight = Math.max(...sourceHeights);
-    const placedSamples: number[][] = [];
-    for (const [longitude, latitude] of geographicSamples) {
-      const convertedMinimum = this.providerHeightTransformer
-        ? this.providerHeightTransformer.transformPosition([
-            longitude,
-            latitude,
-            minimumProviderHeight
-          ])[2]
-        : minimumProviderHeight;
-      const convertedMaximum = this.providerHeightTransformer
-        ? this.providerHeightTransformer.transformPosition([
-            longitude,
-            latitude,
-            maximumProviderHeight
-          ])[2]
-        : maximumProviderHeight;
-      const minimumSurfaceHeight = Math.min(convertedMinimum, convertedMaximum);
-      const maximumSurfaceHeight = Math.max(convertedMinimum, convertedMaximum);
-      const minimumHeight =
-        this.elevationMode === 'onTheGround'
-          ? minimumSurfaceHeight
-          : minimumSurfaceHeight + minimumSourceHeight + this.elevationOffset;
-      const maximumHeight =
-        this.elevationMode === 'onTheGround'
-          ? maximumSurfaceHeight
-          : maximumSurfaceHeight + maximumSourceHeight + this.elevationOffset;
-      placedSamples.push(
-        [longitude, latitude, minimumHeight],
-        [longitude, latitude, maximumHeight]
-      );
-    }
-    return placedSamples;
-  }
-
-  /** Apply source units and non-surface placement without awaiting external resources. */
-  private placeSourcePositionsSync(
-    sourcePositions: ArrayLike<number>,
-    sourceHeightsAreMeters = false
-  ): Float64Array {
-    if (requiresElevationSurface(this.elevationMode)) {
-      throw new Error(
-        `I3S elevation mode ${this.elevationMode} requires asynchronous surface placement`
-      );
-    }
-    const positions = Float64Array.from(sourcePositions);
-    const offset = this.elevationMode === 'absoluteHeight' ? this.elevationOffset : 0;
-    for (let index = 2; index < positions.length; index += 3) {
-      positions[index] =
-        positions[index] * (sourceHeightsAreMeters ? 1 : this.sourceVerticalUnitScale) + offset;
-    }
-    return positions;
-  }
-
-  /** Apply source units and all I3S elevation-placement modes. */
-  private async placeSourcePositions(
-    sourcePositions: ArrayLike<number>,
-    sourceHeightsAreMeters = false
-  ): Promise<Float64Array> {
-    if (!requiresElevationSurface(this.elevationMode)) {
-      return this.placeSourcePositionsSync(sourcePositions, sourceHeightsAreMeters);
-    }
-
-    const positions = Float64Array.from(sourcePositions);
-    const geographicLocations = toPositionArrays(positions).map(position => {
-      const geographic = this.sourceToGeographicTransformer.transformPosition(position);
-      return [geographic[0], geographic[1]] as const;
-    });
-    const sampledHeights = await this.elevationProvider!.sampleElevations(geographicLocations);
-    if (sampledHeights.length !== geographicLocations.length) {
-      throw new Error(
-        `Elevation provider returned ${sampledHeights.length} heights for ${geographicLocations.length} positions`
-      );
-    }
-
-    for (let positionIndex = 0; positionIndex < geographicLocations.length; positionIndex++) {
-      const sampledHeight = sampledHeights[positionIndex] * this.providerUnitScale;
-      if (!Number.isFinite(sampledHeight)) {
-        throw new Error(
-          `Elevation provider returned a non-finite height at index ${positionIndex}`
-        );
-      }
-      const [longitude, latitude] = geographicLocations[positionIndex];
-      const surfaceHeight = this.providerHeightTransformer
-        ? this.providerHeightTransformer.transformPosition([longitude, latitude, sampledHeight])[2]
-        : sampledHeight;
-      const sourceHeight =
-        positions[positionIndex * 3 + 2] *
-        (sourceHeightsAreMeters ? 1 : this.sourceVerticalUnitScale);
-      positions[positionIndex * 3 + 2] =
-        this.elevationMode === 'onTheGround'
-          ? surfaceHeight
-          : surfaceHeight + sourceHeight + this.elevationOffset;
-    }
-    return positions;
-  }
-
-  /** Transform one earth-centered normal to the selected target basis. */
-  private transformEcefNormal(ecefNormal: Vector3, geographic: number[]): Vector3 {
-    if (this.targetCoordinateFrame === 'geocentric') {
-      return ecefNormal.normalize();
-    }
-    if (this.targetCoordinateFrame === 'geographic') {
-      return ecefVectorToLocalEnu(ecefNormal, geographic).normalize();
-    }
-
-    const cartesian = Ellipsoid.WGS84.cartographicToCartesian(new Vector3(geographic));
-    const jacobianColumns: number[] = [];
-    for (const direction of getPositiveAxisDirections()) {
-      const positiveGeographic = Ellipsoid.WGS84.cartesianToCartographic(
-        new Vector3(cartesian).add(direction)
-      );
-      const negativeGeographic = Ellipsoid.WGS84.cartesianToCartographic(
-        new Vector3(cartesian).subtract(direction)
-      );
-      const positiveTarget =
-        this.geographicToTargetTransformer.transformPosition(positiveGeographic);
-      const negativeTarget =
-        this.geographicToTargetTransformer.transformPosition(negativeGeographic);
-      jacobianColumns.push(
-        (positiveTarget[0] - negativeTarget[0]) / 2,
-        (positiveTarget[1] - negativeTarget[1]) / 2,
-        (positiveTarget[2] - negativeTarget[2]) / 2
-      );
-    }
-    const normalMatrix = new Matrix3(jacobianColumns);
-    if (Math.abs(normalMatrix.determinant()) < 1e-12) {
-      throw new Error('Cannot transform an I3S normal through a singular local projection');
-    }
-    normalMatrix.invert().transpose();
-    return new Vector3(ecefNormal).transformByMatrix3(normalMatrix).normalize();
-  }
-}
-
-/** Select the application-owned surface required by one I3S elevation mode. */
-function getElevationProvider(
-  mode: TilesetElevationMode | undefined,
-  options: TilesetSpatialOptions
-): TilesetElevationProvider | undefined {
-  return mode === 'relativeToScene'
-    ? options.sceneElevationProvider
-    : requiresElevationSurface(mode)
-      ? options.terrainElevationProvider
-      : undefined;
-}
-
-/** Return whether one placement mode requires external surface samples. */
-function requiresElevationSurface(mode: TilesetElevationMode | undefined): boolean {
-  return mode === 'onTheGround' || mode === 'relativeToGround' || mode === 'relativeToScene';
-}
-
-/** Split one packed XYZ sequence into position arrays without losing Float64 precision. */
-function toPositionArrays(positions: ArrayLike<number>): number[][] {
-  if (positions.length % 3 !== 0) {
-    throw new Error('I3S position arrays must contain complete XYZ tuples');
-  }
-  const result: number[][] = [];
-  for (let index = 0; index < positions.length; index += 3) {
-    result.push([positions[index], positions[index + 1], positions[index + 2]]);
-  }
-  return result;
-}
-
-/** Return a dateline-aware WGS84 footprint in degrees for an elevation range request. */
-function getElevationBounds(geographicSamples: number[][]): TilesetElevationBounds {
-  const region = getGeographicRegion(geographicSamples);
-  return {
-    west: (region[0] * 180) / Math.PI,
-    south: (region[1] * 180) / Math.PI,
-    east: (region[2] * 180) / Math.PI,
-    north: (region[3] * 180) / Math.PI
-  };
-}
-
-/** Build a conservative WGS84 geographic sphere from placed geographic samples. */
-function getGeographicBoundingSphere(
-  geographicSamples: number[][]
-): [number, number, number, number] {
-  if (!geographicSamples.length) {
-    throw new Error('I3S spatial transformation requires at least one bound sample');
-  }
-  const cartesianSamples = geographicSamples.map(position =>
-    Ellipsoid.WGS84.cartographicToCartesian(new Vector3(position))
-  );
-  const cartesianCenter = new Vector3();
-  for (const sample of cartesianSamples) {
-    cartesianCenter.add(sample);
-  }
-  cartesianCenter.scale(1 / cartesianSamples.length);
-  let radius = 0;
-  for (const sample of cartesianSamples) {
-    radius = Math.max(radius, new Vector3(sample).subtract(cartesianCenter).magnitude());
-  }
-  const geographicCenter = Ellipsoid.WGS84.cartesianToCartographic(cartesianCenter);
-  return [geographicCenter[0], geographicCenter[1], geographicCenter[2], radius];
-}
-
-/** Generate source-frame samples that conservatively cover an I3S MBS or OBB. */
-function getSourceBoundSamples(
-  bounds: I3SSpatialBounds,
-  sourceFrame: TilesetCoordinateFrame,
-  sourceToGeographicTransformer: SpatialCoordinateTransformer,
-  sourceVerticalUnitScale: number
-): number[][] {
-  const obb = bounds.obb;
-  if (obb) {
-    const center = Array.from(obb.center).slice(0, 3);
-    center[2] *= sourceVerticalUnitScale;
-    const halfSize = Array.from(obb.halfSize).slice(0, 3);
-    const quaternion = new Quaternion().fromArray(Array.from(obb.quaternion));
-    const axes = [
-      new Vector3([halfSize[0], 0, 0]).transformByQuaternion(quaternion),
-      new Vector3([0, halfSize[1], 0]).transformByQuaternion(quaternion),
-      new Vector3([0, 0, halfSize[2]]).transformByQuaternion(quaternion)
-    ];
-    if (sourceFrame === 'geographic') {
-      const geographicCenter = sourceToGeographicTransformer.transformPosition(center);
-      const cartesianCenter = Ellipsoid.WGS84.cartographicToCartesian(
-        new Vector3(geographicCenter)
-      );
-      const cartesianAxes =
-        bounds.normalReferenceFrame === 'vertex-reference-frame'
-          ? axes.map(axis => localEnuVectorToEcef(axis, geographicCenter))
-          : axes;
-      return getBoxSigns().map(signs => {
-        const corner = new Vector3(cartesianCenter);
-        for (let axisIndex = 0; axisIndex < 3; axisIndex++) {
-          corner.add(new Vector3(cartesianAxes[axisIndex]).scale(signs[axisIndex]));
-        }
-        return Array.from(Ellipsoid.WGS84.cartesianToCartographic(corner));
-      });
-    }
-    return getBoxSigns().map(signs => {
-      const corner = new Vector3(center);
-      for (let axisIndex = 0; axisIndex < 3; axisIndex++) {
-        corner.add(new Vector3(axes[axisIndex]).scale(signs[axisIndex]));
-      }
-      return Array.from(corner);
-    });
-  }
-
-  const mbs = bounds.mbs ? Array.from(bounds.mbs) : [];
-  if (mbs.length < 4) {
-    return [];
-  }
-  const center = mbs.slice(0, 3);
-  center[2] *= sourceVerticalUnitScale;
-  const radius = mbs[3];
-  if (sourceFrame === 'geographic') {
-    const geographicCenter = sourceToGeographicTransformer.transformPosition(center);
-    const cartesianCenter = Ellipsoid.WGS84.cartographicToCartesian(new Vector3(geographicCenter));
-    return getAxisDirections().map(direction =>
-      Array.from(
-        Ellipsoid.WGS84.cartesianToCartographic(
-          new Vector3(cartesianCenter).add(new Vector3(direction).scale(radius))
-        )
-      )
-    );
-  }
-  return getAxisDirections().map(direction =>
-    Array.from(new Vector3(center).add(new Vector3(direction).scale(radius)))
-  );
-}
-
-/** Return the eight sign combinations of a box. */
-function getBoxSigns(): number[][] {
-  return [-1, 1].flatMap(x => [-1, 1].flatMap(y => [-1, 1].map(z => [x, y, z])));
-}
-
-/** Return positive and negative unit directions for three Cartesian axes. */
-function getAxisDirections(): number[][] {
-  return [
-    [1, 0, 0],
-    [-1, 0, 0],
-    [0, 1, 0],
-    [0, -1, 0],
-    [0, 0, 1],
-    [0, 0, -1]
-  ];
-}
-
-/** Return the positive ECEF basis used to calculate a local projection Jacobian. */
-function getPositiveAxisDirections(): Vector3[] {
-  return [new Vector3([1, 0, 0]), new Vector3([0, 1, 0]), new Vector3([0, 0, 1])];
-}
-
-/** Convert a local east/north/up vector into an earth-centered vector. */
-function localEnuVectorToEcef(vector: ArrayLike<number>, geographic: ArrayLike<number>): Vector3 {
-  const longitude = (geographic[0] * Math.PI) / 180;
-  const latitude = (geographic[1] * Math.PI) / 180;
-  const east = new Vector3([-Math.sin(longitude), Math.cos(longitude), 0]);
-  const north = new Vector3([
-    -Math.sin(latitude) * Math.cos(longitude),
-    -Math.sin(latitude) * Math.sin(longitude),
-    Math.cos(latitude)
-  ]);
-  const up = new Vector3([
-    Math.cos(latitude) * Math.cos(longitude),
-    Math.cos(latitude) * Math.sin(longitude),
-    Math.sin(latitude)
-  ]);
-  return east.scale(vector[0]).add(north.scale(vector[1])).add(up.scale(vector[2]));
-}
-
-/** Convert an earth-centered vector into local east/north/up components. */
-function ecefVectorToLocalEnu(vector: Vector3, geographic: ArrayLike<number>): Vector3 {
-  const longitude = (geographic[0] * Math.PI) / 180;
-  const latitude = (geographic[1] * Math.PI) / 180;
-  const east = new Vector3([-Math.sin(longitude), Math.cos(longitude), 0]);
-  const north = new Vector3([
-    -Math.sin(latitude) * Math.cos(longitude),
-    -Math.sin(latitude) * Math.sin(longitude),
-    Math.cos(latitude)
-  ]);
-  const up = new Vector3([
-    Math.cos(latitude) * Math.cos(longitude),
-    Math.cos(latitude) * Math.sin(longitude),
-    Math.sin(latitude)
-  ]);
-  return new Vector3([east.dot(vector), north.dot(vector), up.dot(vector)]);
-}
-
-/** Build a target-frame axis-aligned generic tile box. */
-function getAxisAlignedBox(positions: number[][]): number[] {
-  const minimum = [Infinity, Infinity, Infinity];
-  const maximum = [-Infinity, -Infinity, -Infinity];
-  for (const position of positions) {
-    for (let component = 0; component < 3; component++) {
-      minimum[component] = Math.min(minimum[component], position[component]);
-      maximum[component] = Math.max(maximum[component], position[component]);
-    }
-  }
-  const center = minimum.map((value, index) => (value + maximum[index]) / 2);
-  const halfSize = minimum.map((value, index) => (maximum[index] - value) / 2);
-  return [center[0], center[1], center[2], halfSize[0], 0, 0, 0, halfSize[1], 0, 0, 0, halfSize[2]];
-}
-
-/** Build a dateline-aware geographic tile region in radians. */
-function getGeographicRegion(positions: number[][]): number[] {
-  const referenceLongitude = positions[0][0];
-  let minimumLongitude = Infinity;
-  let maximumLongitude = -Infinity;
-  let minimumLatitude = Infinity;
-  let maximumLatitude = -Infinity;
-  let minimumHeight = Infinity;
-  let maximumHeight = -Infinity;
-  for (const position of positions) {
-    const longitude = referenceLongitude + normalizeLongitude(position[0] - referenceLongitude);
-    minimumLongitude = Math.min(minimumLongitude, longitude);
-    maximumLongitude = Math.max(maximumLongitude, longitude);
-    minimumLatitude = Math.min(minimumLatitude, position[1]);
-    maximumLatitude = Math.max(maximumLatitude, position[1]);
-    minimumHeight = Math.min(minimumHeight, position[2]);
-    maximumHeight = Math.max(maximumHeight, position[2]);
-  }
-  return [
-    (normalizeLongitude(minimumLongitude) * Math.PI) / 180,
-    (minimumLatitude * Math.PI) / 180,
-    (normalizeLongitude(maximumLongitude) * Math.PI) / 180,
-    (maximumLatitude * Math.PI) / 180,
-    minimumHeight,
-    maximumHeight
-  ];
-}
-
-/** Normalize a longitude delta to the interval [-180, 180). */
-function normalizeLongitude(longitude: number): number {
-  return ((((longitude + 180) % 360) + 360) % 360) - 180;
-}