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

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":"AAAA,aAAa;AACb,+BAA+B;AAC/B,oCAAoC;AAEpC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EAQvB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAC,yBAAyB,EAAC,0CAAuC;AA0LzE;;;;;;GAMG;AACH,MAAM,UAAU,6BAA6B,CAC3C,UAAgD,EAChD,UAAiC,EAAE;IAEnC,MAAM,oBAAoB,GAAG,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC;IAC7D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,SAAS,CAAC;IAC5D,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,MAAM,CAAC;IAC9D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,iBAAiB,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAChG,MAAM,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,IAAI,QAAQ,CAAC;IACxE,MAAM,iBAAiB,GAAG,UAAU,CAAC,iBAAiB,IAAI,CAAC,CAAC;IAC5D,MAAM,kBAAkB,GAAG,UAAU,CAAC,kBAAkB,IAAI,CAAC,CAAC;IAC9D,MAAM,eAAe,GAAG,UAAU,CAAC,eAAe,IAAI,CAAC,CAAC;IACxD,MAAM,eAAe,GACnB,UAAU,CAAC,aAAa,KAAK,aAAa;QAC1C,UAAU,CAAC,aAAa,KAAK,kBAAkB;QAC/C,UAAU,CAAC,aAAa,KAAK,iBAAiB,CAAC;IACjD,MAAM,oBAAoB,GACxB,UAAU,CAAC,aAAa,KAAK,iBAAiB;QAC5C,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,sBAAsB,CAAC;QACzC,CAAC,CAAC,CAAC,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACpE,MAAM,0BAA0B,GAC9B,iBAAiB,KAAK,CAAC;QACvB,kBAAkB,KAAK,CAAC;QACxB,CAAC,UAAU,CAAC,aAAa,KAAK,SAAS;YACrC,CAAC,eAAe;gBACd,CAAC,UAAU,CAAC,aAAa,KAAK,gBAAgB,IAAI,eAAe,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACjF,MAAM,oBAAoB,GACxB,qBAAqB,KAAK,QAAQ,IAAI,qBAAqB,KAAK,UAAU,CAAC,eAAe,CAAC;IAC7F,MAAM,qBAAqB,GACzB,OAAO,CAAC,SAAS,CAAC;QAClB,qBAAqB,KAAK,QAAQ;QAClC,iBAAiB,KAAK,MAAM;QAC5B,0BAA0B,CAAC;IAC7B,MAAM,iBAAiB,GAAG,iBAAiB,KAAK,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC;IACnF,MAAM,iBAAiB,GACrB,CAAC,oBAAoB,IAAI,CAAC,UAAU,CAAC,eAAe,IAAI,SAAS,CAAC,KAAK,SAAS,CAAC;IACnF,MAAM,gBAAgB,GACpB,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAClC,iBAAiB,GAAG,CAAC;QACrB,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QACnC,kBAAkB,GAAG,CAAC,CAAC;IACzB,MAAM,YAAY,GAChB,OAAO,CAAC,SAAS,CAAC;QAClB,qBAAqB;QACrB,iBAAiB;QACjB,iBAAiB;QACjB,gBAAgB;QAChB,oBAAoB;QACpB,iBAAiB,KAAK,WAAW,CAAC;IAEpC,MAAM,UAAU,GAAG,oBAAoB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,IAAI,SAAS,CAAC;IACjG,MAAM,eAAe,GACnB,oBAAoB,IAAI,SAAS;QAC/B,CAAC,CAAC,yBAAyB,CAAC,SAAS,CAAC;QACtC,CAAC,CAAC,UAAU,CAAC,eAAe,CAAC;IACjC,MAAM,cAAc,GAAG,oBAAoB;QACzC,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,UAAU,CAAC,cAAc;YACzB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,KAAK,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACxF,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;QAC9C,GAAG,EAAE,SAAS;YACZ,CAAC,CAAC;gBACE,KAAK,EAAE,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU;gBAC5D,UAAU,EAAE,SAAS;gBACrB,cAAc,EACZ,CAAC,CAAC,oBAAoB,IAAI,UAAU,CAAC,uBAAuB,CAAC;oBAC7D,sBAAsB,CAAC,SAAS,CAAC;gBACnC,UAAU;gBACV,YAAY,EAAE,oBAAoB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,qBAAqB;aAClF;YACH,CAAC,CAAC;gBACE,KAAK,EAAE,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;gBAC1D,UAAU;aACX;QACL,QAAQ,EAAE,UAAU,CAAC,WAAW;YAC9B,CAAC,CAAC;gBACE,KAAK,EAAE,UAAU;gBACjB,UAAU,EAAE,UAAU,CAAC,WAAW;gBAClC,cAAc,EAAE,sBAAsB,CAAC,UAAU,CAAC,WAAW,CAAC;gBAC9D,UAAU,EAAE,UAAU,CAAC,UAAU,IAAI,UAAU;aAChD;YACH,CAAC,CAAC,SAAS;QACb,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,UAAU,CAAC,eAAe;QACtE,eAAe;QACf,eAAe,EAAE,kBAAkB,CAAC,UAAU,CAAC,SAAS,CAAC;QACzD,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK;KAC3D,CAAC,CAAC;IACH,MAAM,mBAAmB,GAAG,qBAAqB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACxE,MAAM,qBAAqB,GAAG,gBAAgB,CAAC,QAAQ;QACrD,CAAC,CAAC,qBAAqB,CAAC,gBAAgB,CAAC,QAAQ,CAAC;QAClD,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,mBAAmB,GAAG,SAAS,CAAC,CAAC,CAAC,0BAA0B,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE1F,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,gBAAgB;QACnB,SAAS,EAAE,mBAAmB;QAC9B,WAAW,EAAE,qBAAqB;QAClC,iBAAiB;QACjB,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,UAAU,CAAC,eAAe;QACtE,eAAe,EAAE,UAAU,CAAC,eAAe,IAAI,SAAS;QACxD,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,kBAAkB;QAClB,eAAe,EAAE,eAAe,IAAI,SAAS;QAC7C,SAAS,EAAE,UAAU,CAAC,SAAS,IAAI,SAAS;QAC5C,UAAU;QACV,SAAS,EAAE,mBAAmB;QAC9B,qBAAqB;QACrB,iBAAiB;QACjB,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,QAAQ;QAC1F,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;KAC1D,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,UAA+C,EAC/C,UAAiC,EAAE;IAEnC,OAAO,6BAA6B,CAClC;QACE,SAAS,EAAE,UAAU,EAAE,SAAS;QAChC,cAAc,EAAE,UAAU,EAAE,GAAG,CAAC,KAAK;QACrC,uBAAuB,EACrB,UAAU,EAAE,GAAG,CAAC,KAAK,KAAK,UAAU,IAAI,UAAU,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS;YACzE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,cAAc;YAC/B,CAAC,CAAC,SAAS;QACf,qBAAqB,EACnB,UAAU,EAAE,GAAG,CAAC,KAAK,KAAK,UAAU,IAAI,UAAU,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS;YACzE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY;YAC7B,CAAC,CAAC,SAAS;QACf,WAAW,EAAE,UAAU,EAAE,WAAW;QACpC,KAAK,EAAE,UAAU,EAAE,KAAK;QACxB,iBAAiB,EAAE,UAAU,EAAE,iBAAiB;QAChD,eAAe,EAAE,UAAU,EAAE,eAAe;QAC5C,eAAe,EAAE,UAAU,EAAE,eAAe;QAC5C,aAAa,EAAE,UAAU,EAAE,aAAa;QACxC,eAAe,EAAE,UAAU,EAAE,eAAe;QAC5C,aAAa,EAAE,UAAU,EAAE,aAAa;QACxC,kBAAkB,EAAE,UAAU,EAAE,kBAAkB;QAClD,eAAe,EAAE,UAAU,EAAE,eAAe;QAC5C,SAAS,EAAE,UAAU,EAAE,SAAS;QAChC,UAAU,EAAE,UAAU,EAAE,UAAU;QAClC,QAAQ,EAAE,UAAU,EAAE,QAAQ;KAC/B,EACD,OAAO,CACR,CAAC;AACJ,CAAC;AAED,gEAAgE;AAChE,SAAS,qBAAqB,CAC5B,SAAkC;IAElC,OAAO,SAAS,CAAC,KAAK,KAAK,UAAU,IAAI,SAAS,CAAC,KAAK,KAAK,SAAS;QACpE,CAAC,CAAC,SAAS,CAAC,UAAU;QACtB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,sFAAsF;AACtF,SAAS,0BAA0B,CAAC,UAAiC;IACnE,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;QAC9C,GAAG,EAAE;YACH,KAAK,EAAE,UAAU;YACjB,UAAU;YACV,cAAc,EAAE,sBAAsB,CAAC,UAAU,CAAC;YAClD,UAAU,EAAE,iBAAiB;SAC9B;KACF,CAAC,CAAC;IACH,MAAM,gBAAgB,GAAG,qBAAqB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACrE,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,mFAAmF;AACnF,SAAS,kBAAkB,CACzB,SAA4D;IAE5D,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACpB,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACpB,KAAK,KAAK;YACR,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QACzB;YACE,OAAO,EAAE,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sCAAsC,CACpD,gBAAyC;IAEzC,IAAI,gBAAgB,CAAC,MAAM,KAAK,eAAe,IAAI,gBAAgB,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QAC7F,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAC,GAAG,gBAAgB,EAAE,MAAM,EAAE,aAAa,EAAC,CAAC,CAAC;AACrE,CAAC"}

package/dist/tileset-3d/common/tile-3d.d.ts

@@ -1,11 +1,29 @@
 import { Matrix4 } from '@math.gl/core';
+import { CullingVolume } from '@math.gl/culling';
+import type { CullingResult } from '@math.gl/culling';
 import type { Tileset3D } from "./tileset-3d.js";
 import type { DoublyLinkedListNode } from "../../utils/doubly-linked-list-node.js";
 import { TILE_REFINEMENT } from "../../constants.js";
-import type { TileContentLoadResult } from "./tileset-source.js";
+import type { TileChildrenLoadResult, TileContentLoadResult } from "./tileset-source.js";
 import { FrameState } from "../helpers/frame-state.js";
 import { CartographicBounds } from "../helpers/bounding-volume.js";
 import { TilesetTraverser } from "./tileset-traverser.js";
+/**
+ * Classifies render-content visibility across all content volumes owned by a tile.
+ *
+ * Content volumes form a union: one visible content entry keeps the tile renderable even when
+ * another entry is outside the frustum or clipping planes. The traversal volume is intentionally
+ * not used here except as a fallback when a tile has no content-specific volume. This separation
+ * keeps clipping render-only and prevents a tight content volume from pruning descendants.
+ *
+ * @param contentVolumes - Transformed content volumes in source order.
+ * @param fallbackVolume - Tile volume used when content does not declare its own volume.
+ * @param cullingVolume - Current view frustum.
+ * @param visibilityPlaneMask - Parent visibility mask optimization.
+ * @param clippingPlanes - Optional world-space planes applied to render content only.
+ * @returns Union visibility classification for the renderable content.
+ */
+export declare function getContentVisibility(contentVolumes: any[], fallbackVolume: any, cullingVolume: CullingVolume, visibilityPlaneMask: number | undefined, clippingPlanes?: any[]): CullingResult;
 /**
  * @param tileset - Tileset3D instance
  * @param header - tile header - JSON loaded from a dataset
@@ -19,6 +37,8 @@ export type Tile3DProps = {
     parentHeader: Tile3D;
     extendedId: string;
 };
+/** Lifecycle of a source-managed lazy child-header group. */
+export type TileChildrenState = 'unloaded' | 'loading' | 'ready' | 'failed';
 /**
  * A Tile3DHeader represents a tile as Tileset3D. When a tile is first created, its content is not loaded;
  * the content is loaded on-demand when needed based on the view.
@@ -33,6 +53,8 @@ export declare class Tile3D {
     refine: TILE_REFINEMENT;
     type: string;
     contentUrl: string;
+    /** Resolved render-content URLs in source order; empty for contentless tiles. */
+    contentUrls: string[];
     /** Different refinement algorithms used by I3S and 3D tiles */
     lodMetricType: string;
     /**
@@ -52,10 +74,23 @@ export declare class Tile3D {
      * not the content's metadata in the tileset JSON file.
      */
     content: any;
+    /** Loaded payloads in the same order as {@link contentUrls}; `content` remains the primary payload. */
+    contents: any[];
+    /**
+     * Metadata entity attached to this tile in the source tileset, if present.
+     *
+     * This is the raw 3D Tiles metadata reference. The generic tiles runtime preserves it without
+     * decoding schema classes or binary property tables.
+     */
+    metadata: Record<string, any> | null;
+    /** Raw metadata entities attached to tile contents, in content source order. */
+    contentMetadata: Array<Record<string, any> | null>;
     contentState: number;
     gpuMemoryUsageInBytes: number;
     /** The tile's children - an array of Tile3D objects. */
     children: Tile3D[];
+    /** Current lifecycle state for a lazy implicit subtree rooted at this tile. */
+    childrenState: TileChildrenState;
     depth: number;
     viewportIds: any[];
     transform: Matrix4;
@@ -73,14 +108,33 @@ export declare class Tile3D {
     private _frameNumber;
     private _expireDate;
     private _expiredContent;
+    /** In-flight source request shared by repeated traversal frames. */
+    private _childrenPromise;
     private _boundingBox?;
     /** updated every frame for tree traversal and rendering optimizations: */
     _distanceToCamera: number;
     _screenSpaceError: number;
+    /** SSE calculated at the reduced viewport height used to prioritize coarse coverage. */
+    _screenSpaceErrorProgressiveResolution: number;
+    /** Whether this tile should be promoted into the progressive-resolution request pass. */
+    _priorityProgressiveResolution: boolean;
+    /** Angular distance from the camera view axis used to prioritize center tiles. */
+    _foveatedFactor: number;
+    /** Whether this peripheral request is currently inside the camera-motion deferral window. */
+    priorityDeferred: boolean;
     private _visibilityPlaneMask;
     private _visible;
     private _contentBoundingVolume;
+    private _contentBoundingVolumes;
+    /** Source content-volume headers retained after render content is unloaded. */
+    private _contentBoundingVolumeHeaders;
     private _viewerRequestVolume;
+    /** Bounding volume used to cull the tile's first renderable content entry. */
+    get contentBoundingVolume(): any;
+    /** All transformed render-content bounding volumes, including tile-volume fallbacks. */
+    get contentBoundingVolumes(): any[];
+    /** Bounding volume that limits when this tile may be requested, when declared. */
+    get viewerRequestVolume(): any;
     _initialTransform: Matrix4;
     _priority: number;
     _selectedFrame: number;
@@ -121,6 +175,10 @@ export declare class Tile3D {
     get hasRenderContent(): boolean;
     /** Returns true if tile has children */
     get hasChildren(): any;
+    /** Returns whether traversal may request an unresolved lazy child-header group. */
+    get hasUnloadedChildren(): boolean;
+    /** Returns whether a lazy child-header request is currently in flight. */
+    get childrenLoading(): boolean;
     /**
      * Determines if the tile's content is ready. This is automatically `true` for
      * tiles with empty content.
@@ -157,8 +215,18 @@ export declare class Tile3D {
      * @returns [min, max] each in [longitude, latitude, altitude]
      */
     get boundingBox(): CartographicBounds;
-    /** Get the tile's screen space error. */
-    getScreenSpaceError(frameState: any, useParentLodMetric: any): number;
+    /**
+     * Gets the tile's screen-space error for normal refinement or a reduced-height priority pass.
+     *
+     * I3S already supplies a screen-oriented LOD metric and intentionally ignores the optional 3D
+     * Tiles progressive-resolution height fraction.
+     *
+     * @param frameState - Current camera and viewport measurements.
+     * @param useParentLodMetric - Whether to substitute the parent LOD metric.
+     * @param viewportHeightFraction - Fraction of viewport height represented by the priority pass.
+     * @returns Screen-space LOD error for the current tileset format.
+     */
+    getScreenSpaceError(frameState: any, useParentLodMetric: any, viewportHeightFraction?: number): number;
     /**
      * Make tile unselected than means it won't be shown
      * but it can be still loaded in memory
@@ -168,12 +236,62 @@ export declare class Tile3D {
      * Memory usage of tile on GPU
      */
     _getGpuMemoryUsageInBytes(): number;
+    /**
+     * Returns scheduler priority for render-content requests.
+     *
+     * @returns Numeric priority, or a negative value when the queued request should be cancelled.
+     */
     _getPriority(): number;
+    /**
+     * Returns scheduler priority for lazy child-header requests.
+     *
+     * Contentless implicit placeholders intentionally retain `UNLOADED` content state, so metadata
+     * scheduling skips only that render-content cancellation check and preserves every visibility,
+     * recency, progressive, foveated, and motion-deferral rule.
+     *
+     * @returns Numeric priority, or a negative value when the queued request should be cancelled.
+     */
+    private _getChildrenPriority;
+    /**
+     * Calculates the common scheduler priority for content or hierarchy metadata.
+     *
+     * @param allowUnloadedContent - Whether an empty placeholder may request child metadata.
+     * @returns Numeric priority, or a negative value when the queued request should be cancelled.
+     */
+    private _calculateRequestPriority;
     /**
      *  Requests the tile's content.
      * The request may not be made if the Request Scheduler can't prioritize it.
      */
     loadContent(): Promise<TileContentLoadResult>;
+    /**
+     * Requests and installs this tile's lazy child-header group through its source.
+     *
+     * The same request scheduler and SSE/foveated priority value used for render content are reused
+     * for subtree metadata. Repeated traversal frames share one promise, and scheduler cancellation
+     * restores the unloaded state so a later frame can retry.
+     *
+     * @param frameState - View state that made the subtree eligible for refinement.
+     * @returns Source load result, or an unloaded result if scheduling was cancelled.
+     */
+    loadChildren(frameState: FrameState): Promise<TileChildrenLoadResult>;
+    /**
+     * Runs one lazy child-header load after obtaining a scheduler token.
+     *
+     * @param frameState - View state forwarded to the source implementation.
+     * @returns Source load result.
+     */
+    private _loadChildrenWithScheduler;
+    /**
+     * Replaces a contentless implicit placeholder with its materialized subtree-root header.
+     *
+     * Transform state is intentionally preserved: the placeholder already owns the composed
+     * transform, and reapplying the root transform here would double-transform bounds and geometric
+     * error. Content and raw geometric error are reinitialized from the newly available header.
+     *
+     * @param materializedHeader - Available root header produced from one subtree resource.
+     */
+    applyImplicitSubtreeHeader(materializedHeader: Record<string, any>): void;
     unloadContent(): boolean;
     /**
      * Update the tile's visibility
@@ -182,8 +300,26 @@ export declare class Tile3D {
      * @return {void}
      */
     updateVisibility(frameState: any, viewportIds: any): void;
+    /**
+     * Updates progressive-resolution and foveated request metrics for a 3D Tiles traversal frame.
+     *
+     * I3S retains its format-specific screen-threshold ordering and is explicitly isolated from
+     * geometric-error scheduling. Orthographic viewports still receive progressive coverage, but
+     * angular foveation is disabled because an orthographic frustum has no perspective field of view.
+     *
+     * @param frameState - Current camera and viewport measurements.
+     */
+    _updateRequestPriorityMetrics(frameState: FrameState): void;
     visibility(frameState: any, parentVisibilityPlaneMask: any): any;
-    contentVisibility(): boolean;
+    /**
+     * Determines whether renderable content intersects the view and configured clipping planes.
+     *
+     * Clipping planes are render-only constraints; traversal continues to use the tile volume.
+     *
+     * @param frameState Current camera, culling, and optional clipping-plane state.
+     * @returns The content visibility classification.
+     */
+    contentVisibility(frameState: FrameState): CullingResult;
     /**
      * Computes the (potentially approximate) distance from the closest point of the tile's bounding volume to the camera.
      * @param frameState The frame state.
@@ -227,6 +363,13 @@ export declare class Tile3D {
     _initializeContent(tileHeader: any): void;
     _initializeRenderingState(header: any): void;
     _getRefine(refine: any): any;
+    /**
+     * Returns whether loaded content is an external tileset.
+     *
+     * Parsed shape is authoritative because valid external resources may be extensionless, signed,
+     * or use a misleading filename. This method is called only after source loading has populated
+     * `content`.
+     */
     _isTileset(): boolean;
     _onContentLoaded(): void;
     _updateBoundingVolume(header: any): void;