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

package/dist/tileset-3d/format-3d-tiles/implicit-tiling.js

@@ -0,0 +1,681 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+import { TILE_REFINEMENT, TILE_TYPE } from "../../constants.js";
+// TypeScript's legacy `node` resolution does not inspect package `exports`, but this public
+// subpath is resolved by the package at runtime and avoids loading unrelated DGGS decoders.
+// @ts-expect-error Conditional package subpath exports require a modern module resolver.
+import { getS2DescendantIndex, getS2IndexFromToken, getS2TokenFromIndex } from '@math.gl/dggs/s2';
+import { convertS2BoundingVolumeToOBB } from "../helpers/s2-bounding-volume.js";
+const QUADTREE_CHILD_COUNT = 4;
+const OCTREE_CHILD_COUNT = 8;
+const AVAILABILITY_RANK_CACHE = new WeakMap();
+/**
+ * Creates the lazy reference stored on an implicit subtree-root header.
+ *
+ * @param descriptor - Shared implicit hierarchy description.
+ * @param coordinates - Global coordinates of the subtree root.
+ * @returns Serializable reference with its concrete subtree URL.
+ */
+export function createImplicitSubtreeReference(descriptor, coordinates) {
+    return {
+        coordinates,
+        subtreeUrl: replaceImplicitUrlTemplate(descriptor.subtreesUrlTemplate, coordinates),
+        descriptor,
+        resource: findImplicitPackageResource(descriptor.resourceFiles, replaceImplicitUrlTemplate(descriptor.subtreesUrlTemplate, coordinates))
+    };
+}
+/**
+ * Materializes the available tiles described by one subtree file without performing I/O.
+ *
+ * The function deliberately stops at the subtree boundary. Available child subtrees become lazy
+ * references so traversal, SSE, request-volume checks, and the request scheduler decide when the
+ * next network request is useful.
+ *
+ * @param subtree - Parsed availability data for one subtree resource.
+ * @param reference - Coordinates and hierarchy description for the subtree root.
+ * @returns Materialized root and diagnostic counts.
+ * @throws If the subtree root is unavailable or the descriptor is invalid.
+ */
+export function materializeImplicitSubtree(subtree, reference) {
+    const { descriptor } = reference;
+    validateImplicitDescriptor(descriptor);
+    validateImplicitSubtree(subtree, descriptor);
+    const counters = { tileCount: 0, childSubtreeCount: 0 };
+    const root = materializeAvailableTile(subtree, reference, { localLevel: 0, mortonIndex: 0 }, reference.coordinates, counters);
+    if (!root) {
+        throw new Error(`Invalid 3D Tiles subtree: root tile is unavailable at ${reference.subtreeUrl}`);
+    }
+    return { root, ...counters };
+}
+/** Validates availability lengths and tightly packed draft attribute/property row counts. */
+function validateImplicitSubtree(subtree, descriptor) {
+    const childCount = getImplicitChildCount(descriptor.subdivisionScheme);
+    const tileElementCount = (childCount ** descriptor.subtreeLevels - 1) / (childCount - 1);
+    const childSubtreeElementCount = childCount ** descriptor.subtreeLevels;
+    validateAvailabilityLength(subtree.tileAvailability, tileElementCount, 'tile');
+    const contentAvailabilityStreams = Array.isArray(subtree.contentAvailability)
+        ? subtree.contentAvailability
+        : subtree.contentAvailability
+            ? [subtree.contentAvailability]
+            : [];
+    for (const contentAvailability of contentAvailabilityStreams) {
+        validateAvailabilityLength(contentAvailability, tileElementCount, 'content');
+    }
+    validateAvailabilityLength(subtree.childSubtreeAvailability, childSubtreeElementCount, 'child subtree');
+    const availableTileCount = countAvailableElements(subtree.tileAvailability, tileElementCount);
+    const availableContentCount = contentAvailabilityStreams[0]
+        ? countAvailableElements(contentAvailabilityStreams[0], tileElementCount)
+        : 0;
+    validateAttributeLengths(subtree.tileAttributes, availableTileCount, 'tile');
+    validateAttributeLengths(subtree.contentAttributes, availableContentCount, 'content');
+    if (subtree.tilePropertyRows && subtree.tilePropertyRows.length !== availableTileCount) {
+        throw new Error('3DTILES_subtree: tile property-table count does not match availability');
+    }
+    if (subtree.contentPropertyRows && subtree.contentPropertyRows.length !== availableContentCount) {
+        throw new Error('3DTILES_subtree: content property-table count does not match availability');
+    }
+}
+/** Verifies that a bitstream contains every bit required by its implicit subtree. */
+function validateAvailabilityLength(availability, elementCount, label) {
+    if (availability.constant === 0 || availability.constant === 1) {
+        return;
+    }
+    if (!availability.explicitBitstream ||
+        availability.explicitBitstream.byteLength * 8 < elementCount) {
+        throw new Error(`3DTILES_subtree: ${label} availability bitstream is too short`);
+    }
+}
+/** Counts available elements within the meaningful, unpadded part of an availability stream. */
+function countAvailableElements(availability, elementCount) {
+    if (availability.constant === 1) {
+        return elementCount;
+    }
+    if (availability.constant === 0) {
+        return 0;
+    }
+    let availableCount = 0;
+    for (let index = 0; index < elementCount; index++) {
+        if (getAvailabilityValue(availability, index)) {
+            availableCount++;
+        }
+    }
+    return availableCount;
+}
+/** Validates standard subtree attribute accessor counts after availability expansion. */
+function validateAttributeLengths(attributes, availableCount, label) {
+    const componentCounts = {
+        TILE_BOUNDING_BOX: 16,
+        TILE_BOUNDING_SPHERE: 4,
+        TILE_GEOMETRIC_ERROR: 1,
+        TILE_REFINE: 1,
+        TILE_TRANSFORM: 16,
+        CONTENT_BOUNDING_BOX: 16,
+        CONTENT_BOUNDING_SPHERE: 4
+    };
+    for (const [semantic, values] of Object.entries(attributes || {})) {
+        const componentCount = componentCounts[semantic];
+        if (componentCount && values.length !== availableCount * componentCount) {
+            throw new Error(`3DTILES_subtree: ${label} attribute ${semantic} count does not match availability`);
+        }
+    }
+}
+/**
+ * Replaces implicit coordinate placeholders in a content or subtree URL.
+ *
+ * @param templateUrl - URL containing level/x/y/z placeholders.
+ * @param coordinates - Global coordinates to insert.
+ * @returns URL with all coordinate placeholders replaced.
+ */
+export function replaceImplicitUrlTemplate(templateUrl, coordinates, properties = {}) {
+    const values = {
+        level: coordinates.level,
+        x: coordinates.x,
+        y: coordinates.y,
+        z: coordinates.z,
+        ...properties
+    };
+    return templateUrl.replace(/{([^{}]+)}/g, (match, propertyName) => {
+        const value = Object.hasOwn(values, propertyName)
+            ? values[propertyName]
+            : values[propertyName.toLowerCase()];
+        return value === undefined ? match : String(value);
+    });
+}
+/**
+ * Builds one available tile and recursively materializes descendants in the same subtree.
+ *
+ * @param subtree - Parsed availability declarations.
+ * @param reference - Current subtree reference.
+ * @param localCoordinates - Level and Morton index relative to the current subtree.
+ * @param globalCoordinates - Coordinates relative to the complete implicit hierarchy.
+ * @param counters - Mutable diagnostic counters owned by the public materializer call.
+ * @returns Header for an available tile, or `null` for a sparse unavailable position.
+ */
+function materializeAvailableTile(subtree, reference, localCoordinates, globalCoordinates, counters) {
+    const { descriptor } = reference;
+    const childCount = getImplicitChildCount(descriptor.subdivisionScheme);
+    const availabilityIndex = getLevelOffset(childCount, localCoordinates.localLevel) + localCoordinates.mortonIndex;
+    if (!getAvailabilityValue(subtree.tileAvailability, availabilityIndex)) {
+        return null;
+    }
+    counters.tileCount++;
+    const contentAvailability = getContentAvailability(subtree.contentAvailability, availabilityIndex);
+    const children = [];
+    if (globalCoordinates.level < descriptor.maximumLevel) {
+        if (localCoordinates.localLevel + 1 < descriptor.subtreeLevels) {
+            for (let childIndex = 0; childIndex < childCount; childIndex++) {
+                const childCoordinates = getChildCoordinates(globalCoordinates, childIndex, descriptor.subdivisionScheme);
+                const childHeader = materializeAvailableTile(subtree, reference, {
+                    localLevel: localCoordinates.localLevel + 1,
+                    mortonIndex: localCoordinates.mortonIndex * childCount + childIndex
+                }, childCoordinates, counters);
+                if (childHeader) {
+                    children.push(childHeader);
+                }
+            }
+        }
+        else {
+            for (let childIndex = 0; childIndex < childCount; childIndex++) {
+                const childSubtreeIndex = localCoordinates.mortonIndex * childCount + childIndex;
+                if (getAvailabilityValue(subtree.childSubtreeAvailability, childSubtreeIndex)) {
+                    const childCoordinates = getChildCoordinates(globalCoordinates, childIndex, descriptor.subdivisionScheme);
+                    children.push(createLazyImplicitTileHeader(subtree, descriptor, childCoordinates));
+                    counters.childSubtreeCount++;
+                }
+            }
+        }
+    }
+    return formatImplicitTileHeader(subtree, descriptor, reference, globalCoordinates, availabilityIndex, contentAvailability, children);
+}
+/**
+ * Creates a contentless placeholder for an available child subtree.
+ *
+ * @param descriptor - Shared implicit hierarchy description.
+ * @param coordinates - Global coordinates of the child subtree root.
+ * @returns Header that participates in culling and SSE before its subtree is requested.
+ */
+function createLazyImplicitTileHeader(subtree, descriptor, coordinates) {
+    const resourceFiles = mergeImplicitPackageFiles(descriptor.resourceFiles, subtree.resourceFiles);
+    const childDescriptor = resourceFiles ? { ...descriptor, resourceFiles } : descriptor;
+    const reference = createImplicitSubtreeReference(childDescriptor, coordinates);
+    return {
+        id: getImplicitTileId(reference, coordinates),
+        children: [],
+        implicitSubtree: reference,
+        boundingVolume: calculateImplicitBoundingVolume(descriptor.rootBoundingVolume, coordinates, descriptor.subdivisionScheme),
+        geometricError: descriptor.rootLodMetricValue / 2 ** coordinates.level,
+        lodMetricType: descriptor.lodMetricType,
+        lodMetricValue: descriptor.rootLodMetricValue / 2 ** coordinates.level,
+        refine: descriptor.refine,
+        type: TILE_TYPE.EMPTY,
+        implicitMetadata: getImplicitSubtreeMetadata(subtree),
+        _scaleGeometricError: descriptor.scaleGeometricError !== false
+    };
+}
+/** Decodes supported standard subtree attributes for one tightly packed available row. */
+function getSubtreeAttributeOverrides(attributes, rowIndex, scope) {
+    if (!attributes || rowIndex < 0) {
+        return {};
+    }
+    const box = getAttributeComponents(attributes[scope === 'tile' ? 'TILE_BOUNDING_BOX' : 'CONTENT_BOUNDING_BOX'], rowIndex, 16);
+    const sphere = getAttributeComponents(attributes[scope === 'tile' ? 'TILE_BOUNDING_SPHERE' : 'CONTENT_BOUNDING_SPHERE'], rowIndex, 4);
+    const boundingVolume = box
+        ? {
+            box: [
+                box[12],
+                box[13],
+                box[14],
+                box[0] / 2,
+                box[1] / 2,
+                box[2] / 2,
+                box[4] / 2,
+                box[5] / 2,
+                box[6] / 2,
+                box[8] / 2,
+                box[9] / 2,
+                box[10] / 2
+            ]
+        }
+        : sphere
+            ? { sphere }
+            : undefined;
+    if (scope === 'content') {
+        return { boundingVolume };
+    }
+    const geometricError = getAttributeComponents(attributes.TILE_GEOMETRIC_ERROR, rowIndex, 1)?.[0];
+    if (geometricError !== undefined && (!Number.isFinite(geometricError) || geometricError < 0)) {
+        throw new Error('3DTILES_subtree: TILE_GEOMETRIC_ERROR must be nonnegative');
+    }
+    const refineValue = getAttributeComponents(attributes.TILE_REFINE, rowIndex, 1)?.[0];
+    if (refineValue !== undefined && refineValue !== 0 && refineValue !== 1) {
+        throw new Error('3DTILES_subtree: TILE_REFINE must be 0 or 1');
+    }
+    return {
+        boundingVolume,
+        geometricError,
+        refine: refineValue === undefined
+            ? undefined
+            : refineValue === 0
+                ? TILE_REFINEMENT.ADD
+                : TILE_REFINEMENT.REPLACE,
+        transform: getAttributeComponents(attributes.TILE_TRANSFORM, rowIndex, 16)
+    };
+}
+/** Copies one logical accessor element and validates its available-row count. */
+function getAttributeComponents(values, rowIndex, componentCount) {
+    if (!values) {
+        return undefined;
+    }
+    const offset = rowIndex * componentCount;
+    if (offset + componentCount > values.length) {
+        throw new Error('3DTILES_subtree: attribute accessor is shorter than availability');
+    }
+    return Array.from({ length: componentCount }, (_unused, componentIndex) => Number(values[offset + componentIndex]));
+}
+/** Returns the tightly packed property/attribute row index for an available element. */
+function getAvailabilityRank(availability, index) {
+    if (availability.constant === 1) {
+        return index;
+    }
+    if (availability.constant === 0) {
+        return 0;
+    }
+    let ranks = AVAILABILITY_RANK_CACHE.get(availability);
+    if (!ranks) {
+        const bitCount = (availability.explicitBitstream?.byteLength || 0) * 8;
+        ranks = new Uint32Array(bitCount + 1);
+        for (let candidateIndex = 0; candidateIndex < bitCount; candidateIndex++) {
+            ranks[candidateIndex + 1] =
+                ranks[candidateIndex] + Number(getAvailabilityValue(availability, candidateIndex));
+        }
+        AVAILABILITY_RANK_CACHE.set(availability, ranks);
+    }
+    return ranks[index];
+}
+/** Locates a concrete generated URI in a retained glTF package. */
+function findImplicitPackageResource(files, resourceUrl) {
+    if (!files?.length) {
+        return undefined;
+    }
+    const urlWithoutQuery = resourceUrl.split('?')[0];
+    const packageRelativePath = /^gltf-package:\/\/[^/]+\/(.*)$/.exec(urlWithoutQuery)?.[1];
+    const exactFileIndex = files.findIndex(file => {
+        const reference = file.originalUri || file.name;
+        return (file.uri === urlWithoutQuery ||
+            Boolean(reference && (urlWithoutQuery === reference || packageRelativePath === reference)));
+    });
+    if (exactFileIndex >= 0) {
+        return { fileIndex: exactFileIndex, files };
+    }
+    const fileIndex = files.findIndex(file => {
+        const reference = file.originalUri || file.name;
+        return Boolean(reference &&
+            (urlWithoutQuery.endsWith(`/${reference}`) || urlWithoutQuery.endsWith(`:${reference}`)));
+    });
+    return fileIndex < 0 ? undefined : { fileIndex, files };
+}
+/** Layers files declared by a child package over inherited parent-package files. */
+function mergeImplicitPackageFiles(parentFiles, childFiles) {
+    if (!childFiles?.length) {
+        return parentFiles;
+    }
+    if (!parentFiles?.length) {
+        return childFiles;
+    }
+    const childReferences = new Set(childFiles.flatMap(file => [file.uri, file.originalUri, file.name].filter(Boolean)));
+    return [
+        ...childFiles,
+        ...parentFiles.filter(file => ![file.uri, file.originalUri, file.name].some(reference => reference && childReferences.has(reference)))
+    ];
+}
+/**
+ * Formats an available implicit tile as a runtime header.
+ *
+ * @param descriptor - Shared implicit hierarchy description.
+ * @param reference - Current subtree reference used to build stable IDs.
+ * @param coordinates - Global tile coordinates.
+ * @param contentAvailability - Availability for each content stream in source order.
+ * @param children - Materialized or lazy child headers.
+ * @returns Runtime tile header.
+ */
+function formatImplicitTileHeader(subtree, descriptor, reference, coordinates, availabilityIndex, contentAvailability, children) {
+    const tilePropertyIndex = getAvailabilityRank(subtree.tileAvailability, availabilityIndex);
+    const tileProperties = subtree.tilePropertyRows?.[tilePropertyIndex];
+    const primaryContentAvailability = Array.isArray(subtree.contentAvailability)
+        ? subtree.contentAvailability[0]
+        : subtree.contentAvailability;
+    const contentPropertyIndex = primaryContentAvailability &&
+        getAvailabilityValue(primaryContentAvailability, availabilityIndex)
+        ? getAvailabilityRank(primaryContentAvailability, availabilityIndex)
+        : -1;
+    const contentProperties = subtree.contentPropertyRows?.[contentPropertyIndex];
+    const tileTemplateProperties = subtree.tileTemplatePropertyRows?.[tilePropertyIndex] || tileProperties;
+    const contentTemplateProperties = subtree.contentTemplatePropertyRows?.[contentPropertyIndex] || contentProperties;
+    const templateProperties = { ...tileTemplateProperties, ...contentTemplateProperties };
+    const tileAttributes = getSubtreeAttributeOverrides(subtree.tileAttributes, tilePropertyIndex, 'tile');
+    const contentAttributes = getSubtreeAttributeOverrides(subtree.contentAttributes, contentPropertyIndex, 'content');
+    const contentUrlTemplates = descriptor.contentUrlTemplates?.length
+        ? descriptor.contentUrlTemplates
+        : [descriptor.contentUrlTemplate];
+    const contentEntries = contentUrlTemplates
+        .map((templateUrl, contentIndex) => {
+        if (!contentAvailability[contentIndex] || !templateUrl) {
+            return null;
+        }
+        const contentUrl = replaceImplicitUrlTemplate(templateUrl, coordinates, templateProperties);
+        if (/{[^{}]+}/.test(contentUrl)) {
+            throw new Error(`Implicit content URI has unresolved template values: ${contentUrl}`);
+        }
+        return {
+            contentIndex,
+            contentUrl
+        };
+    })
+        .filter((entry) => Boolean(entry));
+    const availableContentUrls = contentEntries.map(entry => entry.contentUrl);
+    const resourceFiles = mergeImplicitPackageFiles(descriptor.resourceFiles, subtree.resourceFiles);
+    const content = contentEntries.map(({ contentIndex, contentUrl }) => {
+        const packageResource = findImplicitPackageResource(resourceFiles, contentUrl);
+        return {
+            ...(descriptor.contentHeaders?.[contentIndex] ||
+                (contentIndex === 0 ? descriptor.contentHeader : {}) ||
+                {}),
+            ...contentAttributes,
+            uri: contentUrl,
+            ...(contentProperties ? { metadata: { properties: contentProperties } } : {}),
+            ...(packageResource ? { _resource: packageResource } : {})
+        };
+    });
+    const contentUrl = availableContentUrls[0];
+    const computedLodMetricValue = descriptor.rootLodMetricValue / 2 ** coordinates.level;
+    const lodMetricValue = tileAttributes.geometricError ?? computedLodMetricValue;
+    const computedBoundingVolume = calculateImplicitBoundingVolume(descriptor.rootBoundingVolume, coordinates, descriptor.subdivisionScheme);
+    return {
+        id: getImplicitTileId(reference, coordinates),
+        children,
+        contentUrl,
+        content: content.length > 1 ? content : content[0],
+        contents: descriptor.useCanonicalContents && content.length ? content : undefined,
+        contentUrls: availableContentUrls,
+        refine: tileAttributes.refine || descriptor.refine,
+        type: getImplicitTileType(contentUrl),
+        lodMetricType: descriptor.lodMetricType,
+        lodMetricValue,
+        geometricError: lodMetricValue,
+        boundingVolume: tileAttributes.boundingVolume || computedBoundingVolume,
+        transform: tileAttributes.transform,
+        transformMatrix: tileAttributes.transform,
+        metadata: tileProperties ? { properties: tileProperties } : undefined,
+        implicitMetadata: getImplicitSubtreeMetadata(subtree, tileProperties, contentProperties),
+        _scaleGeometricError: descriptor.scaleGeometricError !== false
+    };
+}
+/**
+ * Copies subtree metadata references without interpreting property-table schemas.
+ *
+ * Keeping the references on generated headers makes metadata available to applications while
+ * avoiding a false promise that the runtime has already decoded classes, enums, or values.
+ *
+ * @param subtree - Parsed subtree containing optional metadata declarations.
+ * @returns Metadata references, or `undefined` when the subtree declares none.
+ */
+function getImplicitSubtreeMetadata(subtree, tileProperties, contentProperties) {
+    if (!subtree.propertyTables &&
+        subtree.tileMetadata === undefined &&
+        !subtree.contentMetadata &&
+        subtree.subtreeMetadata === undefined &&
+        !tileProperties &&
+        !contentProperties) {
+        return undefined;
+    }
+    return {
+        propertyTables: subtree.propertyTables,
+        tileMetadata: subtree.tileMetadata,
+        contentMetadata: subtree.contentMetadata,
+        subtreeMetadata: subtree.subtreeMetadata,
+        tileProperties,
+        contentProperties
+    };
+}
+/**
+ * Returns a stable identity for contentless and content-bearing implicit tiles.
+ *
+ * @param reference - Owning subtree reference.
+ * @param coordinates - Global tile coordinates.
+ * @returns Stable source identity independent of content availability.
+ */
+function getImplicitTileId(reference, coordinates) {
+    return `${reference.subtreeUrl}#implicit=${coordinates.level}/${coordinates.x}/${coordinates.y}/${coordinates.z}`;
+}
+/**
+ * Reads an availability bit without assuming 32-bit coordinate or Morton arithmetic.
+ *
+ * @param availability - Constant or expanded bitstream availability.
+ * @param index - Zero-based availability index.
+ * @returns Whether the addressed tile, content, or child subtree exists.
+ */
+function getAvailabilityValue(availability, index) {
+    if (typeof availability?.constant === 'number') {
+        return Boolean(availability.constant);
+    }
+    const bitstream = availability?.explicitBitstream;
+    if (!bitstream) {
+        return false;
+    }
+    const byteIndex = Math.floor(index / 8);
+    const bitIndex = index % 8;
+    return Boolean((bitstream[byteIndex] >> bitIndex) & 1);
+}
+/**
+ * Reads every content availability stream for one tile in descriptor/source order.
+ *
+ * @param availability - Single or multiple-content availability declaration.
+ * @returns Availability flags aligned with the content URL templates.
+ */
+function getContentAvailability(availability, index) {
+    const streams = Array.isArray(availability) ? availability : [availability];
+    return streams.map(stream => getAvailabilityValue(stream || { constant: 0 }, index));
+}
+/**
+ * Calculates the breadth-first availability offset for a local subtree level.
+ *
+ * @param childCount - Branching factor of the subdivision scheme.
+ * @param localLevel - Level relative to the subtree root.
+ * @returns First availability index for the requested level.
+ */
+function getLevelOffset(childCount, localLevel) {
+    return (childCount ** localLevel - 1) / (childCount - 1);
+}
+/**
+ * Calculates one child's global implicit coordinates.
+ *
+ * @param parent - Global parent coordinates.
+ * @param childIndex - Morton-ordered child index.
+ * @param subdivisionScheme - Quadtree or octree subdivision.
+ * @returns Global child coordinates.
+ */
+function getChildCoordinates(parent, childIndex, subdivisionScheme) {
+    return {
+        level: parent.level + 1,
+        x: parent.x * 2 + (childIndex & 1),
+        y: parent.y * 2 + ((childIndex >> 1) & 1),
+        z: subdivisionScheme === 'OCTREE' ? parent.z * 2 + ((childIndex >> 2) & 1) : 0
+    };
+}
+/**
+ * Returns the branching factor for a supported implicit subdivision scheme.
+ *
+ * @param subdivisionScheme - Quadtree or octree subdivision.
+ * @returns Four for quadtrees or eight for octrees.
+ */
+function getImplicitChildCount(subdivisionScheme) {
+    return subdivisionScheme === 'OCTREE' ? OCTREE_CHILD_COUNT : QUADTREE_CHILD_COUNT;
+}
+/**
+ * Calculates the bounding volume for global implicit coordinates.
+ *
+ * Region volumes are divided in longitude/latitude and, for octrees, height. Oriented boxes are
+ * divided along their half-axis vectors. S2 roots use math.gl's Hilbert-aware descendant indexing
+ * to produce the exact child token and a corresponding geospatial oriented box.
+ *
+ * @param rootBoundingVolume - Bounding volume of the complete implicit hierarchy.
+ * @param coordinates - Global tile coordinates.
+ * @param subdivisionScheme - Quadtree or octree subdivision.
+ * @returns Bounding volume for the addressed tile.
+ */
+function calculateImplicitBoundingVolume(rootBoundingVolume, coordinates, subdivisionScheme) {
+    if (rootBoundingVolume.region) {
+        const [west, south, east, north, minimumHeight, maximumHeight] = rootBoundingVolume.region;
+        const divisionCount = 2 ** coordinates.level;
+        const longitudeSpan = east >= west ? east - west : east + 2 * Math.PI - west;
+        const longitudeSize = longitudeSpan / divisionCount;
+        const latitudeSize = (north - south) / divisionCount;
+        const childWest = normalizeRegionLongitude(west + longitudeSize * coordinates.x);
+        const childEast = normalizeRegionLongitude(west + longitudeSize * (coordinates.x + 1));
+        const childSouth = south + latitudeSize * coordinates.y;
+        let childMinimumHeight = minimumHeight;
+        let childMaximumHeight = maximumHeight;
+        if (subdivisionScheme === 'OCTREE') {
+            const heightSize = (maximumHeight - minimumHeight) / divisionCount;
+            childMinimumHeight = minimumHeight + heightSize * coordinates.z;
+            childMaximumHeight = childMinimumHeight + heightSize;
+        }
+        return {
+            region: [
+                childWest,
+                childSouth,
+                childEast,
+                childSouth + latitudeSize,
+                childMinimumHeight,
+                childMaximumHeight
+            ]
+        };
+    }
+    if (rootBoundingVolume.box) {
+        if (rootBoundingVolume.s2VolumeInfo) {
+            return calculateS2ImplicitBoundingVolume(rootBoundingVolume, coordinates, subdivisionScheme);
+        }
+        if (rootBoundingVolume.extensions?.['3DTILES_shape_cylinder_region']) {
+            return {
+                ...rootBoundingVolume,
+                box: [...rootBoundingVolume.box]
+            };
+        }
+        const box = rootBoundingVolume.box;
+        const divisionCount = 2 ** coordinates.level;
+        const xOffset = -1 + (2 * coordinates.x + 1) / divisionCount;
+        const yOffset = -1 + (2 * coordinates.y + 1) / divisionCount;
+        const zOffset = -1 + (2 * coordinates.z + 1) / divisionCount;
+        const divideHeight = subdivisionScheme === 'OCTREE';
+        const center = [
+            box[0] + box[3] * xOffset + box[6] * yOffset + (divideHeight ? box[9] * zOffset : 0),
+            box[1] + box[4] * xOffset + box[7] * yOffset + (divideHeight ? box[10] * zOffset : 0),
+            box[2] + box[5] * xOffset + box[8] * yOffset + (divideHeight ? box[11] * zOffset : 0)
+        ];
+        return {
+            box: [
+                ...center,
+                box[3] / divisionCount,
+                box[4] / divisionCount,
+                box[5] / divisionCount,
+                box[6] / divisionCount,
+                box[7] / divisionCount,
+                box[8] / divisionCount,
+                divideHeight ? box[9] / divisionCount : box[9],
+                divideHeight ? box[10] / divisionCount : box[10],
+                divideHeight ? box[11] / divisionCount : box[11]
+            ]
+        };
+    }
+    throw new Error(`Unsupported implicit 3D Tiles bounding volume: ${JSON.stringify(rootBoundingVolume)}`);
+}
+/**
+ * Calculates an implicit descendant of an S2 root using math.gl's canonical Hilbert hierarchy.
+ *
+ * @param rootBoundingVolume - Normalized S2 root volume.
+ * @param coordinates - Global implicit tile coordinates.
+ * @param subdivisionScheme - Quadtree or octree subdivision.
+ * @returns Child volume with updated S2 metadata and oriented box.
+ */
+function calculateS2ImplicitBoundingVolume(rootBoundingVolume, coordinates, subdivisionScheme) {
+    const rootS2VolumeInfo = rootBoundingVolume.s2VolumeInfo;
+    const rootIndex = getS2IndexFromToken(rootS2VolumeInfo.token);
+    const descendantIndex = getS2DescendantIndex(rootIndex, coordinates.level, coordinates.x, coordinates.y);
+    const divisionCount = 2 ** coordinates.level;
+    const heightSize = (rootS2VolumeInfo.maximumHeight - rootS2VolumeInfo.minimumHeight) / divisionCount;
+    const childS2VolumeInfo = {
+        token: getS2TokenFromIndex(descendantIndex),
+        minimumHeight: rootS2VolumeInfo.minimumHeight +
+            (subdivisionScheme === 'OCTREE' ? heightSize * coordinates.z : 0),
+        maximumHeight: rootS2VolumeInfo.minimumHeight +
+            (subdivisionScheme === 'OCTREE'
+                ? heightSize * (coordinates.z + 1)
+                : heightSize * divisionCount)
+    };
+    const extensions = rootBoundingVolume.extensions ? { ...rootBoundingVolume.extensions } : undefined;
+    if (extensions?.['3DTILES_bounding_volume_S2']) {
+        extensions['3DTILES_bounding_volume_S2'] = childS2VolumeInfo;
+    }
+    if (extensions?.['3DTILES_shape_s2']) {
+        extensions['3DTILES_shape_s2'] = childS2VolumeInfo;
+    }
+    return {
+        ...rootBoundingVolume,
+        ...(extensions ? { extensions } : {}),
+        s2VolumeInfo: childS2VolumeInfo,
+        box: convertS2BoundingVolumeToOBB(childS2VolumeInfo)
+    };
+}
+/** Normalize a longitude while preserving the positive pi boundary for non-wrapped regions. */
+function normalizeRegionLongitude(longitude) {
+    let normalizedLongitude = longitude;
+    while (normalizedLongitude > Math.PI) {
+        normalizedLongitude -= 2 * Math.PI;
+    }
+    while (normalizedLongitude < -Math.PI) {
+        normalizedLongitude += 2 * Math.PI;
+    }
+    return normalizedLongitude;
+}
+/**
+ * Detects the runtime tile category from an available content URL.
+ *
+ * @param contentUrl - Concrete content URL, if content is available.
+ * @returns Runtime tile category.
+ */
+function getImplicitTileType(contentUrl) {
+    if (!contentUrl) {
+        return TILE_TYPE.EMPTY;
+    }
+    const extension = contentUrl.split('?')[0].split('.').pop()?.toLowerCase();
+    switch (extension) {
+        case 'pnts':
+            return TILE_TYPE.POINTCLOUD;
+        case 'i3dm':
+        case 'b3dm':
+        case 'glb':
+        case 'gltf':
+            return TILE_TYPE.SCENEGRAPH;
+        default:
+            return extension || TILE_TYPE.EMPTY;
+    }
+}
+/**
+ * Validates descriptor invariants before allocating a runtime subtree.
+ *
+ * @param descriptor - Serializable implicit hierarchy description.
+ * @throws If levels, scheme, or maximum-level semantics are invalid.
+ */
+function validateImplicitDescriptor(descriptor) {
+    if (descriptor.subdivisionScheme !== 'QUADTREE' && descriptor.subdivisionScheme !== 'OCTREE') {
+        throw new Error(`Unsupported implicit subdivision scheme: ${descriptor.subdivisionScheme}`);
+    }
+    if (!Number.isInteger(descriptor.subtreeLevels) || descriptor.subtreeLevels < 1) {
+        throw new Error('Implicit subtreeLevels must be a positive integer');
+    }
+    if (!Number.isInteger(descriptor.maximumLevel) || descriptor.maximumLevel < 0) {
+        throw new Error('Implicit availableLevels must describe at least the root level');
+    }
+}
+//# sourceMappingURL=implicit-tiling.js.map