@loaders.gl/tiles 4.5.3 → 5.0.0-alpha.10

package/dist/spatial/spatial-types.d.ts

@@ -0,0 +1,190 @@
+import { type ReadonlyCRSDefinition, type SpatialReference, type SpatialReferenceAlternative, type SpatialReferenceCoordinateFrame, type SpatialReferenceProvenance, type SpatialReferenceRepresentation, type SpatialReferenceState } from '@math.gl/crs';
+import type { Geoid } from '@math.gl/geoid';
+/** How height values in a 3D dataset relate to the earth. */
+export type TilesetHeightReference = 'native' | 'ellipsoidal' | 'orthometric' | 'unknown';
+/** Height reference that an application may request for transformed output. */
+export type TilesetTargetHeightReference = 'native' | 'ellipsoidal' | 'orthometric';
+/** I3S placement rule applied after source-height interpretation. */
+export type TilesetElevationMode = 'absoluteHeight' | 'onTheGround' | 'relativeToGround' | 'relativeToScene';
+/** One WGS84 longitude/latitude location requested from an elevation provider. */
+export type TilesetElevationSample = readonly [longitude: number, latitude: number];
+/** WGS84 geographic footprint passed to an elevation provider. */
+export type TilesetElevationBounds = {
+    /** Western longitude in degrees. Greater than `east` when crossing the antimeridian. */
+    readonly west: number;
+    /** Southern latitude in degrees. */
+    readonly south: number;
+    /** Eastern longitude in degrees. Less than `west` when crossing the antimeridian. */
+    readonly east: number;
+    /** Northern latitude in degrees. */
+    readonly north: number;
+};
+/** Conservative elevation extrema over one geographic footprint. */
+export type TilesetElevationRange = {
+    /** Minimum elevation anywhere inside the footprint. */
+    readonly minimum: number;
+    /** Maximum elevation anywhere inside the footprint. */
+    readonly maximum: number;
+};
+/**
+ * Application-owned source of terrain or scene-surface heights.
+ *
+ * Providers receive WGS84 longitude/latitude locations and may batch asynchronous requests. They
+ * never need to transform horizontal coordinates. Returned heights default to meters in the
+ * layer's source height reference unless `unit` or `heightReference` says otherwise.
+ */
+export type TilesetElevationProvider = {
+    /** Height reference used by sampled values. Omit to use the layer's source height reference. */
+    readonly heightReference?: Exclude<TilesetHeightReference, 'native' | 'unknown'>;
+    /** Linear unit used by sampled values. Defaults to `meter`. */
+    readonly unit?: string;
+    /**
+     * Samples one height for every supplied location, preserving input order.
+     * @param positions - WGS84 longitude/latitude locations.
+     * @returns Finite heights with the same length and order as `positions`.
+     */
+    sampleElevations(positions: readonly TilesetElevationSample[]): readonly number[] | Promise<readonly number[]>;
+    /**
+     * Returns conservative elevation extrema over an entire geographic footprint.
+     *
+     * Bounds preparation requires this operation because point samples cannot detect an interior
+     * peak or depression and therefore cannot produce a culling-safe traversal volume.
+     *
+     * @param bounds - WGS84 geographic footprint in degrees.
+     * @returns Minimum and maximum elevations in this provider's declared unit and height reference.
+     */
+    getElevationRange(bounds: TilesetElevationBounds): TilesetElevationRange | Promise<TilesetElevationRange>;
+};
+/** Coordinate representation requested from a 3D tileset. */
+export type TilesetOutputCoordinates = 'auto' | 'ecef' | 'local-enu' | 'target-crs';
+/** Broad coordinate frame used by a 3D dataset. */
+export type TilesetCoordinateFrame = SpatialReferenceCoordinateFrame;
+/** Origin of a normalized spatial-reference value. */
+export type TilesetSpatialReferenceProvenance = SpatialReferenceProvenance;
+/**
+ * Simple application-facing spatial options shared by 3D Tiles and I3S.
+ *
+ * Source CRS details are normally discovered from dataset metadata. The source overrides are
+ * expert recovery controls for incomplete or non-standard datasets.
+ */
+export type TilesetSpatialOptions = {
+    /** CRS of transformed output coordinates. Omit to retain the format's natural world frame. */
+    targetCrs?: ReadonlyCRSDefinition;
+    /** Height reference of transformed output coordinates. Defaults to `native`. */
+    targetHeightReference?: TilesetTargetHeightReference;
+    /** Output coordinate representation. Defaults to `auto`. */
+    outputCoordinates?: TilesetOutputCoordinates;
+    /** Expert override used when source metadata is absent or incorrect. */
+    sourceCrs?: ReadonlyCRSDefinition;
+    /** Expert override for a dynamic coordinate reference epoch. */
+    coordinateEpoch?: number;
+    /** Registered geoid model name or an already parsed geoid model. */
+    geoidModel?: string | Geoid;
+    /** Terrain heights used by I3S `onTheGround` and `relativeToGround` placement. */
+    terrainElevationProvider?: TilesetElevationProvider;
+    /** Scene-surface heights used by I3S `relativeToScene` placement. */
+    sceneElevationProvider?: TilesetElevationProvider;
+};
+/**
+ * Normalized, readonly spatial metadata discovered for a 3D tileset.
+ *
+ * This is diagnostic output. Applications normally do not construct it.
+ */
+export type TilesetSpatialReference = SpatialReference & {
+    /** Source horizontal or compound CRS, when it can be identified. */
+    readonly sourceCrs?: ReadonlyCRSDefinition;
+    /** Source vertical CRS, when independently identified. */
+    readonly verticalCrs?: ReadonlyCRSDefinition;
+    /** Number of meters represented by one source Z unit. */
+    readonly verticalUnitScale: number;
+    /** Coordinate epoch attached to the source coordinates. */
+    readonly coordinateEpoch?: number;
+    /** Source height interpretation. */
+    readonly heightReference: TilesetHeightReference;
+    /** I3S placement rule, when the source layer declares one. */
+    readonly elevationMode?: TilesetElevationMode;
+    /** Declared I3S elevation offset before unit normalization. */
+    readonly elevationOffset?: number;
+    /** Unit of the I3S elevation offset. Defaults to `meter` when a mode is declared. */
+    readonly elevationUnit?: string;
+    /** Number of meters represented by one elevation-offset unit. */
+    readonly elevationUnitScale: number;
+    /** Broad frame in which source coordinates are encoded. */
+    readonly coordinateFrame: TilesetCoordinateFrame;
+    /** Coordinate component order used by the format wire representation. */
+    readonly axisOrder: 'xy' | 'yx' | 'xyz' | 'unknown';
+    /** How the source CRS was established. */
+    readonly provenance: TilesetSpatialReferenceProvenance;
+    /** Target CRS selected by application options, if any. */
+    readonly targetCrs?: ReadonlyCRSDefinition;
+    /** Target height interpretation selected by application options. */
+    readonly targetHeightReference: TilesetTargetHeightReference;
+    /** Output representation selected by application options. */
+    readonly outputCoordinates: TilesetOutputCoordinates;
+    /** Whether coordinates are native, ready to transform, transformed, or unresolved. */
+    readonly status: 'native' | 'transformable' | 'transformed' | 'unresolved';
+    /** Non-fatal qualifications retained for diagnostics and user interfaces. */
+    readonly warnings: readonly string[];
+};
+/** Input used by format adapters to create normalized spatial metadata. */
+export type CreateTilesetSpatialReferenceOptions = {
+    /** Discovered source CRS. */
+    sourceCrs?: ReadonlyCRSDefinition;
+    /** Whether the source CRS was explicit, defaulted, unknown, or absent. */
+    sourceCrsState?: SpatialReferenceState;
+    /** Serialization or naming form used by the source CRS. */
+    sourceCrsRepresentation?: SpatialReferenceRepresentation;
+    /** Additional source CRS representations retained by the format. */
+    sourceCrsAlternatives?: readonly SpatialReferenceAlternative[];
+    /** Discovered vertical CRS. */
+    verticalCrs?: ReadonlyCRSDefinition;
+    /** Per-component source units, aligned with the stored coordinate order. */
+    units?: readonly string[];
+    /** Number of meters represented by one discovered source Z unit. */
+    verticalUnitScale?: number;
+    /** Discovered coordinate epoch. */
+    coordinateEpoch?: number;
+    /** Discovered height interpretation. */
+    heightReference?: TilesetHeightReference;
+    /** Format-specific elevation placement rule. */
+    elevationMode?: TilesetElevationMode;
+    /** Format-specific elevation offset before unit normalization. */
+    elevationOffset?: number;
+    /** Unit of the format-specific elevation offset. */
+    elevationUnit?: string;
+    /** Number of meters represented by one elevation-offset unit. */
+    elevationUnitScale?: number;
+    /** Discovered broad coordinate frame. */
+    coordinateFrame?: TilesetCoordinateFrame;
+    /** Format wire-axis order. */
+    axisOrder?: 'xy' | 'yx' | 'xyz' | 'unknown';
+    /** Metadata provenance. */
+    provenance?: TilesetSpatialReferenceProvenance;
+    /** Non-fatal discovery qualifications. */
+    warnings?: readonly string[];
+};
+/**
+ * Combines format discovery with the intentionally small application option surface.
+ *
+ * @param discovered - Values derived from dataset metadata and format defaults.
+ * @param options - Application target options and expert recovery overrides.
+ * @returns Normalized immutable spatial metadata.
+ */
+export declare function createTilesetSpatialReference(discovered: CreateTilesetSpatialReferenceOptions, options?: TilesetSpatialOptions): TilesetSpatialReference;
+/**
+ * Applies application target and recovery options to format-discovered spatial metadata.
+ *
+ * @param discovered - Readonly metadata returned by a format adapter.
+ * @param options - Application target options and expert recovery overrides.
+ * @returns A new normalized immutable descriptor.
+ */
+export declare function applyTilesetSpatialOptions(discovered: TilesetSpatialReference | undefined, options?: TilesetSpatialOptions): TilesetSpatialReference;
+/**
+ * Marks a normalized descriptor after every returned coordinate and bound has entered its target
+ * frame.
+ *
+ * @param spatialReference - Transformable spatial descriptor.
+ * @returns An immutable descriptor with `status: 'transformed'`.
+ */
+export declare function markTilesetSpatialReferenceTransformed(spatialReference: TilesetSpatialReference): TilesetSpatialReference;
+//# sourceMappingURL=spatial-types.d.ts.map

package/dist/spatial/spatial-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-types.d.ts","sourceRoot":"","sources":["../../src/spatial/spatial-types.ts"],"names":[],"mappings":"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"}

package/dist/spatial/spatial-types.js

@@ -0,0 +1,192 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { createSpatialReference, inferCRSRepresentation } from '@math.gl/crs';
+import { getSpatialCoordinateFrame } from "./get-spatial-coordinate-frame.js";
+/**
+ * Combines format discovery with the intentionally small application option surface.
+ *
+ * @param discovered - Values derived from dataset metadata and format defaults.
+ * @param options - Application target options and expert recovery overrides.
+ * @returns Normalized immutable spatial metadata.
+ */
+export function createTilesetSpatialReference(discovered, options = {}) {
+    const hasSourceCrsOverride = options.sourceCrs !== undefined;
+    const sourceCrs = options.sourceCrs || discovered.sourceCrs;
+    const outputCoordinates = options.outputCoordinates || 'auto';
+    const targetCrs = options.targetCrs || (outputCoordinates === 'ecef' ? 'EPSG:4978' : undefined);
+    const targetHeightReference = options.targetHeightReference || 'native';
+    const verticalUnitScale = discovered.verticalUnitScale ?? 1;
+    const elevationUnitScale = discovered.elevationUnitScale ?? 1;
+    const elevationOffset = discovered.elevationOffset || 0;
+    const requiresSurface = discovered.elevationMode === 'onTheGround' ||
+        discovered.elevationMode === 'relativeToGround' ||
+        discovered.elevationMode === 'relativeToScene';
+    const hasElevationProvider = discovered.elevationMode === 'relativeToScene'
+        ? Boolean(options.sceneElevationProvider)
+        : !requiresSurface || Boolean(options.terrainElevationProvider);
+    const hasFormatVerticalOperation = verticalUnitScale !== 1 ||
+        elevationUnitScale !== 1 ||
+        (discovered.elevationMode !== undefined &&
+            (requiresSurface ||
+                (discovered.elevationMode === 'absoluteHeight' && elevationOffset !== 0)));
+    const needsHeightTransform = targetHeightReference !== 'native' && targetHeightReference !== discovered.heightReference;
+    const hasRequestedTransform = Boolean(targetCrs) ||
+        targetHeightReference !== 'native' ||
+        outputCoordinates !== 'auto' ||
+        hasFormatVerticalOperation;
+    const hasRequiredTarget = outputCoordinates !== 'target-crs' || Boolean(targetCrs);
+    const hasHeightMetadata = !needsHeightTransform || (discovered.heightReference || 'unknown') !== 'unknown';
+    const hasVerticalUnits = Number.isFinite(verticalUnitScale) &&
+        verticalUnitScale > 0 &&
+        Number.isFinite(elevationUnitScale) &&
+        elevationUnitScale > 0;
+    const canTransform = Boolean(sourceCrs) &&
+        hasRequestedTransform &&
+        hasRequiredTarget &&
+        hasHeightMetadata &&
+        hasVerticalUnits &&
+        hasElevationProvider &&
+        outputCoordinates !== 'local-enu';
+    const provenance = hasSourceCrsOverride ? 'caller-override' : discovered.provenance || 'unknown';
+    const coordinateFrame = hasSourceCrsOverride && sourceCrs
+        ? getSpatialCoordinateFrame(sourceCrs)
+        : discovered.coordinateFrame;
+    const sourceCrsState = hasSourceCrsOverride
+        ? 'explicit'
+        : discovered.sourceCrsState ||
+            (sourceCrs ? (provenance === 'format-default' ? 'default' : 'explicit') : 'absent');
+    const spatialReference = createSpatialReference({
+        crs: sourceCrs
+            ? {
+                state: sourceCrsState === 'default' ? 'default' : 'explicit',
+                definition: sourceCrs,
+                representation: (!hasSourceCrsOverride && discovered.sourceCrsRepresentation) ||
+                    inferCRSRepresentation(sourceCrs),
+                provenance,
+                alternatives: hasSourceCrsOverride ? undefined : discovered.sourceCrsAlternatives
+            }
+            : {
+                state: sourceCrsState === 'unknown' ? 'unknown' : 'absent',
+                provenance
+            },
+        vertical: discovered.verticalCrs
+            ? {
+                state: 'explicit',
+                definition: discovered.verticalCrs,
+                representation: inferCRSRepresentation(discovered.verticalCrs),
+                provenance: discovered.provenance || 'metadata'
+            }
+            : undefined,
+        coordinateEpoch: options.coordinateEpoch ?? discovered.coordinateEpoch,
+        coordinateFrame,
+        coordinateOrder: getCoordinateOrder(discovered.axisOrder),
+        units: hasSourceCrsOverride ? undefined : discovered.units
+    });
+    const normalizedSourceCrs = getKnownCRSDefinition(spatialReference.crs);
+    const normalizedVerticalCrs = spatialReference.vertical
+        ? getKnownCRSDefinition(spatialReference.vertical)
+        : undefined;
+    const normalizedTargetCrs = targetCrs ? cloneReadonlyCRSDefinition(targetCrs) : undefined;
+    return Object.freeze({
+        ...spatialReference,
+        sourceCrs: normalizedSourceCrs,
+        verticalCrs: normalizedVerticalCrs,
+        verticalUnitScale,
+        coordinateEpoch: options.coordinateEpoch ?? discovered.coordinateEpoch,
+        heightReference: discovered.heightReference || 'unknown',
+        elevationMode: discovered.elevationMode,
+        elevationOffset: discovered.elevationOffset,
+        elevationUnit: discovered.elevationUnit,
+        elevationUnitScale,
+        coordinateFrame: coordinateFrame || 'unknown',
+        axisOrder: discovered.axisOrder || 'unknown',
+        provenance,
+        targetCrs: normalizedTargetCrs,
+        targetHeightReference,
+        outputCoordinates,
+        status: hasRequestedTransform ? (canTransform ? 'transformable' : 'unresolved') : 'native',
+        warnings: Object.freeze([...(discovered.warnings || [])])
+    });
+}
+/**
+ * Applies application target and recovery options to format-discovered spatial metadata.
+ *
+ * @param discovered - Readonly metadata returned by a format adapter.
+ * @param options - Application target options and expert recovery overrides.
+ * @returns A new normalized immutable descriptor.
+ */
+export function applyTilesetSpatialOptions(discovered, options = {}) {
+    return createTilesetSpatialReference({
+        sourceCrs: discovered?.sourceCrs,
+        sourceCrsState: discovered?.crs.state,
+        sourceCrsRepresentation: discovered?.crs.state === 'explicit' || discovered?.crs.state === 'default'
+            ? discovered.crs.representation
+            : undefined,
+        sourceCrsAlternatives: discovered?.crs.state === 'explicit' || discovered?.crs.state === 'default'
+            ? discovered.crs.alternatives
+            : undefined,
+        verticalCrs: discovered?.verticalCrs,
+        units: discovered?.units,
+        verticalUnitScale: discovered?.verticalUnitScale,
+        coordinateEpoch: discovered?.coordinateEpoch,
+        heightReference: discovered?.heightReference,
+        elevationMode: discovered?.elevationMode,
+        elevationOffset: discovered?.elevationOffset,
+        elevationUnit: discovered?.elevationUnit,
+        elevationUnitScale: discovered?.elevationUnitScale,
+        coordinateFrame: discovered?.coordinateFrame,
+        axisOrder: discovered?.axisOrder,
+        provenance: discovered?.provenance,
+        warnings: discovered?.warnings
+    }, options);
+}
+/** Return a known definition from a canonical CRS reference. */
+function getKnownCRSDefinition(reference) {
+    return reference.state === 'explicit' || reference.state === 'default'
+        ? reference.definition
+        : undefined;
+}
+/** Clone and deeply freeze a target CRS through the canonical math.gl constructor. */
+function cloneReadonlyCRSDefinition(definition) {
+    const spatialReference = createSpatialReference({
+        crs: {
+            state: 'explicit',
+            definition,
+            representation: inferCRSRepresentation(definition),
+            provenance: 'caller-override'
+        }
+    });
+    const clonedDefinition = getKnownCRSDefinition(spatialReference.crs);
+    if (!clonedDefinition) {
+        throw new Error('Failed to normalize a known target CRS definition');
+    }
+    return clonedDefinition;
+}
+/** Convert the legacy tileset axis label to the common stored-coordinate order. */
+function getCoordinateOrder(axisOrder) {
+    switch (axisOrder) {
+        case 'xy':
+            return ['x', 'y'];
+        case 'yx':
+            return ['y', 'x'];
+        case 'xyz':
+            return ['x', 'y', 'z'];
+        default:
+            return [];
+    }
+}
+/**
+ * Marks a normalized descriptor after every returned coordinate and bound has entered its target
+ * frame.
+ *
+ * @param spatialReference - Transformable spatial descriptor.
+ * @returns An immutable descriptor with `status: 'transformed'`.
+ */
+export function markTilesetSpatialReferenceTransformed(spatialReference) {
+    if (spatialReference.status !== 'transformable' && spatialReference.status !== 'transformed') {
+        throw new Error('Only a transformable spatial reference can be marked as transformed');
+    }
+    return Object.freeze({ ...spatialReference, status: 'transformed' });
+}
+//# sourceMappingURL=spatial-types.js.map

package/dist/spatial/spatial-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-types.js","sourceRoot":"","sources":["../../src/spatial/spatial-types.ts"],"names":[],"mappings":"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"}

package/dist/spatial/tiles-3d-spatial-transformer.d.ts

@@ -0,0 +1,32 @@
+import type { TilesetSpatialOptions, TilesetSpatialReference } from "./spatial-types.js";
+/** Structural 3D Tiles volume shape used by the source adapter. */
+export type Tiles3DSpatialBoundingVolume = {
+    box?: number[];
+    sphere?: number[];
+    region?: number[];
+    [key: string]: unknown;
+};
+/**
+ * Applies nonlinear CRS operations to 3D Tiles geometry bounds.
+ *
+ * Bounds are rebuilt from conservative samples. This intentionally produces an axis-aligned box
+ * in the target frame; it is safe for culling and screen-space-error calculations even when the
+ * source volume is rotated or the projection is nonlinear.
+ */
+export declare class Tiles3DSpatialTransformer {
+    /** Normalized reference describing the completed operation. */
+    readonly spatialReference: TilesetSpatialReference;
+    private readonly coordinateTransformer;
+    private readonly geographicCoordinateTransformer;
+    /** Creates a 3D Tiles transformer for a requested target CRS. */
+    constructor(spatialReference: TilesetSpatialReference, options?: TilesetSpatialOptions);
+    /** Transform packed POSITION values into the target CRS. */
+    transformPositions(positions: ArrayLike<number>): Float64Array;
+    /** Transform packed NORMAL values using the corresponding source positions. */
+    transformNormals(normals: ArrayLike<number>, positions: ArrayLike<number>): Float32Array;
+    /** Rebuild a conservative target-frame volume from a source volume. */
+    transformBoundingVolume(volume: Tiles3DSpatialBoundingVolume, sourceTransform?: ArrayLike<number>): Tiles3DSpatialBoundingVolume;
+    /** Transforms one WGS84 region sample into the selected output frame. */
+    private transformRegionSample;
+}
+//# sourceMappingURL=tiles-3d-spatial-transformer.d.ts.map

package/dist/spatial/tiles-3d-spatial-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiles-3d-spatial-transformer.d.ts","sourceRoot":"","sources":["../../src/spatial/tiles-3d-spatial-transformer.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAC,qBAAqB,EAAE,uBAAuB,EAAC,2BAAwB;AAEpF,mEAAmE;AACnE,MAAM,MAAM,4BAA4B,GAAG;IACzC,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,yBAAyB;IACpC,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,EAAE,uBAAuB,CAAC;IACnD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA+B;IACrE,OAAO,CAAC,QAAQ,CAAC,+BAA+B,CAA+B;IAE/E,iEAAiE;gBACrD,gBAAgB,EAAE,uBAAuB,EAAE,OAAO,GAAE,qBAA0B;IAkB1F,4DAA4D;IAC5D,kBAAkB,CAAC,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,YAAY;IAI9D,+EAA+E;IAC/E,gBAAgB,CAAC,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,YAAY;IAIxF,uEAAuE;IACvE,uBAAuB,CACrB,MAAM,EAAE,4BAA4B,EACpC,eAAe,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,GAClC,4BAA4B;IAgB/B,yEAAyE;IACzE,OAAO,CAAC,qBAAqB;CAa9B"}

package/dist/spatial/tiles-3d-spatial-transformer.js

@@ -0,0 +1,175 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { SpatialCoordinateTransformer } from "./spatial-coordinate-transformer.js";
+import { getSpatialCoordinateFrame } from "./get-spatial-coordinate-frame.js";
+import { Matrix4 } from '@math.gl/core';
+import { Ellipsoid } from '@math.gl/geospatial';
+/**
+ * Applies nonlinear CRS operations to 3D Tiles geometry bounds.
+ *
+ * Bounds are rebuilt from conservative samples. This intentionally produces an axis-aligned box
+ * in the target frame; it is safe for culling and screen-space-error calculations even when the
+ * source volume is rotated or the projection is nonlinear.
+ */
+export class Tiles3DSpatialTransformer {
+    /** Normalized reference describing the completed operation. */
+    spatialReference;
+    coordinateTransformer;
+    geographicCoordinateTransformer;
+    /** Creates a 3D Tiles transformer for a requested target CRS. */
+    constructor(spatialReference, options = {}) {
+        this.coordinateTransformer = new SpatialCoordinateTransformer(spatialReference, options);
+        // 3D Tiles regions are always encoded as WGS84 longitude/latitude radians, independently
+        // of the tileset's local CRS. Build a second pipeline for that fixed source frame.
+        const geographicSpatialReference = {
+            ...spatialReference,
+            sourceCrs: 'EPSG:4326',
+            targetCrs: spatialReference.targetCrs || spatialReference.sourceCrs,
+            coordinateFrame: 'geographic',
+            axisOrder: 'xy'
+        };
+        this.geographicCoordinateTransformer = new SpatialCoordinateTransformer(geographicSpatialReference, options);
+        this.spatialReference = spatialReference;
+    }
+    /** Transform packed POSITION values into the target CRS. */
+    transformPositions(positions) {
+        return this.coordinateTransformer.transformPositions(positions);
+    }
+    /** Transform packed NORMAL values using the corresponding source positions. */
+    transformNormals(normals, positions) {
+        return this.coordinateTransformer.transformNormals(normals, positions);
+    }
+    /** Rebuild a conservative target-frame volume from a source volume. */
+    transformBoundingVolume(volume, sourceTransform) {
+        const transform = sourceTransform ? new Matrix4(Array.from(sourceTransform)) : undefined;
+        const samples = volume.region
+            ? getRegionSamples(volume.region)
+            : getVolumeSamples(volume).map(sample => transform ? Array.from(transform.transformAsPoint(sample)) : sample);
+        if (!samples.length) {
+            return volume;
+        }
+        const transformed = volume.region
+            ? samples.map(sample => this.transformRegionSample(sample))
+            : samples.map(sample => this.coordinateTransformer.transformPosition(sample));
+        return { box: createAxisAlignedBox(transformed) };
+    }
+    /** Transforms one WGS84 region sample into the selected output frame. */
+    transformRegionSample(sample) {
+        const [longitudeDegrees, latitudeDegrees, height] = sample;
+        const targetCrs = this.spatialReference.targetCrs || this.spatialReference.sourceCrs;
+        if (targetCrs && getSpatialCoordinateFrame(targetCrs) === 'geocentric') {
+            const cartesian = Ellipsoid.WGS84.cartographicToCartesian([
+                longitudeDegrees,
+                latitudeDegrees,
+                height
+            ]);
+            return Array.from(cartesian);
+        }
+        return this.geographicCoordinateTransformer.transformPosition(sample);
+    }
+}
+/** Samples region corners, center lines, and both height planes in degrees/meters. */
+function getRegionSamples(region) {
+    if (region.length < 6 || region.some(value => !Number.isFinite(value))) {
+        return [];
+    }
+    const [west, south, east, north, minimumHeight, maximumHeight] = region;
+    const longitudeEnd = east < west ? east + Math.PI * 2 : east;
+    const longitudes = getIntervalSamples(west, longitudeEnd);
+    const latitudes = getIntervalSamples(south, north);
+    const samples = [];
+    for (const longitude of longitudes) {
+        for (const latitude of latitudes) {
+            for (const height of [minimumHeight, maximumHeight]) {
+                samples.push([(longitude * 180) / Math.PI, (latitude * 180) / Math.PI, height]);
+            }
+        }
+    }
+    return samples;
+}
+/** Includes interval endpoints and every quarter-turn where ECEF axes reach an extremum. */
+function getIntervalSamples(start, end) {
+    const samples = [start, (start + end) / 2, end];
+    const angularStep = Math.PI / 2;
+    const firstCriticalIndex = Math.ceil(start / angularStep);
+    const lastCriticalIndex = Math.floor(end / angularStep);
+    for (let criticalIndex = firstCriticalIndex; criticalIndex <= lastCriticalIndex; criticalIndex++) {
+        samples.push(criticalIndex * angularStep);
+    }
+    return samples;
+}
+function getVolumeSamples(volume) {
+    if (volume.box && volume.box.length >= 12) {
+        const center = volume.box.slice(0, 3);
+        const axes = [volume.box.slice(3, 6), volume.box.slice(6, 9), volume.box.slice(9, 12)];
+        const samples = [];
+        for (let firstIndex = 0; firstIndex <= 4; firstIndex++) {
+            for (let secondIndex = 0; secondIndex <= 4; secondIndex++) {
+                for (let thirdIndex = 0; thirdIndex <= 4; thirdIndex++) {
+                    const first = firstIndex / 2 - 1;
+                    const second = secondIndex / 2 - 1;
+                    const third = thirdIndex / 2 - 1;
+                    samples.push([
+                        center[0] + first * axes[0][0] + second * axes[1][0] + third * axes[2][0],
+                        center[1] + first * axes[0][1] + second * axes[1][1] + third * axes[2][1],
+                        center[2] + first * axes[0][2] + second * axes[1][2] + third * axes[2][2]
+                    ]);
+                }
+            }
+        }
+        return samples;
+    }
+    if (volume.sphere && volume.sphere.length >= 4) {
+        const [x, y, z, radius] = volume.sphere;
+        const samples = [
+            [x - radius, y, z],
+            [x + radius, y, z],
+            [x, y - radius, z],
+            [x, y + radius, z],
+            [x, y, z - radius],
+            [x, y, z + radius]
+        ];
+        for (let longitudeIndex = 0; longitudeIndex < 16; longitudeIndex++) {
+            const longitude = (longitudeIndex * Math.PI * 2) / 16;
+            samples.push([x + radius * Math.cos(longitude), y + radius * Math.sin(longitude), z]);
+        }
+        return samples;
+    }
+    // Regions are already WGS84 geographic volumes. Keep them unchanged until a dedicated
+    // geographic-region adapter can account for longitude wrapping and datum semantics.
+    return [];
+}
+function createAxisAlignedBox(samples) {
+    const minimum = [Infinity, Infinity, Infinity];
+    const maximum = [-Infinity, -Infinity, -Infinity];
+    for (const sample of samples) {
+        for (let axis = 0; axis < 3; axis++) {
+            minimum[axis] = Math.min(minimum[axis], sample[axis]);
+            maximum[axis] = Math.max(maximum[axis], sample[axis]);
+        }
+    }
+    const padding = [
+        Math.max((maximum[0] - minimum[0]) * 0.01, 1e-9),
+        Math.max((maximum[1] - minimum[1]) * 0.01, 1e-9),
+        Math.max((maximum[2] - minimum[2]) * 0.01, 1e-9)
+    ];
+    const center = [
+        (minimum[0] + maximum[0]) / 2,
+        (minimum[1] + maximum[1]) / 2,
+        (minimum[2] + maximum[2]) / 2
+    ];
+    return [
+        ...center,
+        (maximum[0] - minimum[0]) / 2 + padding[0],
+        0,
+        0,
+        0,
+        (maximum[1] - minimum[1]) / 2 + padding[1],
+        0,
+        0,
+        0,
+        (maximum[2] - minimum[2]) / 2 + padding[2]
+    ];
+}
+//# sourceMappingURL=tiles-3d-spatial-transformer.js.map

package/dist/spatial/tiles-3d-spatial-transformer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiles-3d-spatial-transformer.js","sourceRoot":"","sources":["../../src/spatial/tiles-3d-spatial-transformer.ts"],"names":[],"mappings":"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"}