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

package/dist/spatial/i3s-spatial-transformer.js

@@ -1,731 +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.js";
-import { createTilesetSpatialReference, markTilesetSpatialReferenceTransformed } from "./spatial-types.js";
-import { getI3SLinearUnitScale } from "./i3s-elevation.js";
-/**
- * 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. */
-    spatialReference;
-    /** Broad coordinate frame of the selected output CRS. */
-    targetCoordinateFrame;
-    /** Source-to-target position operation. */
-    positionTransformer;
-    /** Source-to-WGS84 geographic operation used for vector-frame conversion. */
-    sourceToGeographicTransformer;
-    /** WGS84-geographic-to-target operation used for normal finite differences. */
-    geographicToTargetTransformer;
-    /** Source frame recorded by I3S metadata. */
-    sourceCoordinateFrame;
-    /** Source Z multiplier that normalizes stored elevation values to meters. */
-    sourceVerticalUnitScale;
-    /** I3S elevation placement mode. */
-    elevationMode;
-    /** I3S elevation offset normalized to meters. */
-    elevationOffset;
-    /** Terrain or scene provider selected for the declared placement mode. */
-    elevationProvider;
-    /** Provider height multiplier that normalizes returned values to meters. */
-    providerUnitScale;
-    /** Optional provider-height to layer-height datum operation. */
-    providerHeightTransformer;
-    /**
-     * 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, options = {}) {
-        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) {
-        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) {
-        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. */
-    transformPlacedPosition(position) {
-        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) {
-        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) {
-        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, sourceOrigin) {
-        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, sourceOrigin) {
-        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, normals, normalReferenceFrame = 'earth-centered') {
-        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. */
-    transformPlacedPositions(sourcePositions, sourceOrigin) {
-        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, sourcePositions, normalReferenceFrame = 'earth-centered') {
-        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) {
-        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) {
-        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) {
-        return { region: getGeographicRegion(this.getGeographicBoundSamples(bounds)) };
-    }
-    /** Rebuild an I3S bound as WGS84 geographic after asynchronous elevation placement. */
-    async transformBoundingVolumeToGeographicAsync(bounds) {
-        return { region: getGeographicRegion(await this.getGeographicBoundSamplesAsync(bounds)) };
-    }
-    /** Rebuild an I3S bound as a WGS84 ECEF box for generic `Tileset3D` traversal. */
-    transformBoundingVolumeToGeocentric(bounds) {
-        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) {
-        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) {
-        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) {
-        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) {
-        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) {
-        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. */
-    getGeographicBoundSamples(bounds) {
-        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. */
-    async getGeographicBoundSamplesAsync(bounds) {
-        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. */
-    async placeGeographicBoundSamples(geographicSamples) {
-        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 = [];
-        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. */
-    placeSourcePositionsSync(sourcePositions, sourceHeightsAreMeters = false) {
-        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. */
-    async placeSourcePositions(sourcePositions, sourceHeightsAreMeters = false) {
-        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]];
-        });
-        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. */
-    transformEcefNormal(ecefNormal, geographic) {
-        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 = [];
-        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, options) {
-    return mode === 'relativeToScene'
-        ? options.sceneElevationProvider
-        : requiresElevationSurface(mode)
-            ? options.terrainElevationProvider
-            : undefined;
-}
-/** Return whether one placement mode requires external surface samples. */
-function requiresElevationSurface(mode) {
-    return mode === 'onTheGround' || mode === 'relativeToGround' || mode === 'relativeToScene';
-}
-/** Split one packed XYZ sequence into position arrays without losing Float64 precision. */
-function toPositionArrays(positions) {
-    if (positions.length % 3 !== 0) {
-        throw new Error('I3S position arrays must contain complete XYZ tuples');
-    }
-    const result = [];
-    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) {
-    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) {
-    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, sourceFrame, sourceToGeographicTransformer, sourceVerticalUnitScale) {
-    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() {
-    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() {
-    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() {
-    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, geographic) {
-    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, geographic) {
-    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) {
-    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) {
-    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) {
-    return ((((longitude + 180) % 360) + 360) % 360) - 180;
-}
-//# sourceMappingURL=i3s-spatial-transformer.js.map