@loaders.gl/3d-tiles 4.0.0-alpha.12 → 4.0.0-alpha.13

package/src/lib/parsers/helpers/parse-3d-implicit-tiles.ts

@@ -1,6 +1,7 @@
 import type {Availability, Tile3DBoundingVolume, Subtree} from '../../../types';
 import {Tile3DSubtreeLoader} from '../../../tile-3d-subtree-loader';
 import {load} from '@loaders.gl/core';
+import {default as log} from '@probe.gl/log';
 
 import {getS2CellIdFromToken, getS2ChildCellId, getS2TokenFromCellId} from '../../utils/s2/index';
 import type {S2VolumeInfo} from '../../utils/obb/s2-corners-to-obb';
@@ -122,9 +123,10 @@ export async function parseImplicitTiles(params: {
 
   const childrenPerTile = SUBDIVISION_COUNT_MAP[subdivisionScheme];
 
-  const childX = childIndex & 0b01;
-  const childY = (childIndex >> 1) & 0b01;
-  const childZ = (childIndex >> 2) & 0b01;
+  // childIndex is in range [0, 7]
+  const childX = childIndex & 0b01; // Get first bit for X
+  const childY = (childIndex >> 1) & 0b01; // Get second bit for Y
+  const childZ = (childIndex >> 2) & 0b01; // Get third bit for Z
 
   const levelOffset = (childrenPerTile ** level - 1) / (childrenPerTile - 1);
   let childTileMortonIndex = concatBits(parentData.mortonIndex, childIndex);
@@ -224,13 +226,37 @@ export async function parseImplicitTiles(params: {
   return tile;
 }
 
-function getAvailabilityResult(availabilityData: Availability, index: number): boolean {
-  if ('constant' in availabilityData) {
-    return Boolean(availabilityData.constant);
+/**
+ * Check tile availability in the bitstream array
+ * @param availabilityData - tileAvailability / contentAvailability / childSubtreeAvailability object
+ * @param index - index in the bitstream array
+ * @returns
+ */
+function getAvailabilityResult(
+  availabilityData: Availability | Availability[],
+  index: number
+): boolean {
+  let availabilityObject: Availability;
+  if (Array.isArray(availabilityData)) {
+    /** TODO: we don't support `3DTILES_multiple_contents` extension at the moment.
+     * https://github.com/CesiumGS/3d-tiles/blob/main/extensions/3DTILES_implicit_tiling/README.md#multiple-contents
+     * Take first item in the array
+     */
+    availabilityObject = availabilityData[0];
+    if (availabilityData.length > 1) {
+      // eslint-disable-next-line no-console
+      log.once('Not supported extension "3DTILES_multiple_contents" has been detected');
+    }
+  } else {
+    availabilityObject = availabilityData;
+  }
+
+  if ('constant' in availabilityObject) {
+    return Boolean(availabilityObject.constant);
   }
 
-  if (availabilityData.explicitBitstream) {
-    return getBooleanValueFromBitstream(index, availabilityData.explicitBitstream);
+  if (availabilityObject.explicitBitstream) {
+    return getBooleanValueFromBitstream(index, availabilityObject.explicitBitstream);
   }
 
   return false;

package/src/lib/parsers/helpers/parse-3d-tile-subtree.ts

@@ -1,4 +1,4 @@
-import type {Subtree, ExplicitBitstream} from '../../../types';
+import type {Subtree, Availability} from '../../../types';
 import type {LoaderContext, LoaderOptions} from '@loaders.gl/loader-utils';
 
 const SUBTREE_FILE_MAGIC = 0x74627573;
@@ -42,53 +42,54 @@ export default async function parse3DTilesSubtree(
     internalBinaryBuffer = data.slice(24 + jsonByteLength);
   }
 
-  if ('bufferView' in subtree.tileAvailability) {
-    subtree.tileAvailability.explicitBitstream = await getExplicitBitstream(
+  await loadExplicitBitstream(subtree, subtree.tileAvailability, internalBinaryBuffer, context);
+  if (Array.isArray(subtree.contentAvailability)) {
+    for (const contentAvailability of subtree.contentAvailability) {
+      await loadExplicitBitstream(subtree, contentAvailability, internalBinaryBuffer, context);
+    }
+  } else {
+    await loadExplicitBitstream(
       subtree,
-      'tileAvailability',
-      internalBinaryBuffer,
-      context
-    );
-  }
-
-  if ('bufferView' in subtree.contentAvailability) {
-    subtree.contentAvailability.explicitBitstream = await getExplicitBitstream(
-      subtree,
-      'contentAvailability',
-      internalBinaryBuffer,
-      context
-    );
-  }
-
-  if ('bufferView' in subtree.childSubtreeAvailability) {
-    subtree.childSubtreeAvailability.explicitBitstream = await getExplicitBitstream(
-      subtree,
-      'childSubtreeAvailability',
+      subtree.contentAvailability,
       internalBinaryBuffer,
       context
     );
   }
+  await loadExplicitBitstream(
+    subtree,
+    subtree.childSubtreeAvailability,
+    internalBinaryBuffer,
+    context
+  );
 
   return subtree;
 }
 
 /**
- * Get explicit bitstream for subtree availability data.
- * @param subtree
- * @param name
- * @param internalBinaryBuffer
+ * Load explicit bitstream for subtree availability data.
+ * @param subtree - subtree data
+ * @param availabilityObject - tileAvailability / contentAvailability / childSubtreeAvailability object
+ * @param internalBinaryBuffer - subtree binary buffer
+ * @param context - loaders.gl context
  */
-async function getExplicitBitstream(
+async function loadExplicitBitstream(
   subtree: Subtree,
-  name: string,
+  availabilityObject: Availability,
   internalBinaryBuffer: ArrayBuffer,
   context: LoaderContext | undefined
-): Promise<ExplicitBitstream> {
-  const bufferViewIndex = subtree[name].bufferView;
+): Promise<void> {
+  const bufferViewIndex = Number.isFinite(availabilityObject.bitstream)
+    ? availabilityObject.bitstream
+    : availabilityObject.bufferView;
+
+  if (typeof bufferViewIndex !== 'number') {
+    return;
+  }
+
   const bufferView = subtree.bufferViews[bufferViewIndex];
   const buffer = subtree.buffers[bufferView.buffer];
 
-  if (!context?.url || !context.fetch) {
+  if (!context?.baseUrl) {
     throw new Error('Url is not provided');
   }
 
@@ -101,11 +102,18 @@ async function getExplicitBitstream(
     const bufferUri = `${context?.baseUrl || ''}/${buffer.uri}`;
     const response = await context.fetch(bufferUri);
     const data = await response.arrayBuffer();
-    // Return view of bitstream.
-    return new Uint8Array(data, bufferView.byteOffset, bufferView.byteLength);
+    availabilityObject.explicitBitstream = new Uint8Array(
+      data,
+      bufferView.byteOffset,
+      bufferView.byteLength
+    );
+    return;
   }
-  // Return view of bitstream.
-  return new Uint8Array(internalBinaryBuffer, bufferView.byteOffset, bufferView.byteLength);
+  availabilityObject.explicitBitstream = new Uint8Array(
+    internalBinaryBuffer,
+    bufferView.byteOffset,
+    bufferView.byteLength
+  );
 }
 
 /**

package/src/types.ts

@@ -294,20 +294,57 @@ export type Tiles3DTileContent = {
 
 /**
  * 3DTILES_implicit_tiling types
- * Spec - https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_implicit_tiling#subtree-file-format
+ * Spec - https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_implicit_tiling
+ * JSON Schema v1.1 https://github.com/CesiumGS/3d-tiles/blob/8e5e67e078850cc8ce15bd1873fe54f11bbee02f/specification/schema/Subtree/subtree.schema.json
+ * JSON Schema vNext https://github.com/CesiumGS/3d-tiles/blob/8e5e67e078850cc8ce15bd1873fe54f11bbee02f/extensions/3DTILES_implicit_tiling/schema/subtree/subtree.schema.json
  */
 export type Subtree = {
+  /** An array of buffers. */
   buffers: Buffer[];
+  /** An array of buffer views. */
   bufferViews: BufferView[];
+  /** The availability of tiles in the subtree. The availability bitstream is a 1D boolean array where tiles are ordered by their level in the subtree and Morton index
+   * within that level. A tile's availability is determined by a single bit, 1 meaning a tile exists at that spatial index, and 0 meaning it does not.
+   * The number of elements in the array is `(N^subtreeLevels - 1)/(N - 1)` where N is 4 for subdivision scheme `QUADTREE` and 8 for `OCTREE`.
+   * Availability may be stored in a buffer view or as a constant value that applies to all tiles. If a non-root tile's availability is 1 its parent
+   * tile's availability shall also be 1. `tileAvailability.constant: 0` is disallowed, as subtrees shall have at least one tile.
+   */
   tileAvailability: Availability;
-  contentAvailability: Availability;
+  /** It is array by spec but there are tiles that has a single object
+   * An array of content availability objects. If the tile has a single content this array will have one element; if the tile has multiple contents -
+   * as supported by 3DTILES_multiple_contents and 3D Tiles 1.1 - this array will have multiple elements.
+   */
+  contentAvailability: Availability | Availability[];
+  /** The availability of children subtrees. The availability bitstream is a 1D boolean array where subtrees are ordered by their Morton index in the level of the tree
+   * immediately below the bottom row of the subtree. A child subtree's availability is determined by a single bit, 1 meaning a subtree exists at that spatial index,
+   * and 0 meaning it does not. The number of elements in the array is `N^subtreeLevels` where N is 4 for subdivision scheme `QUADTREE` and 8 for `OCTREE`.
+   * Availability may be stored in a buffer view or as a constant value that applies to all child subtrees. If availability is 0 for all child subtrees,
+   * then the tileset does not subdivide further.
+   */
   childSubtreeAvailability: Availability;
+  // TODO: These are unused properties. Improve types when they are required
+  propertyTables: unknown;
+  tileMetadata: unknown;
+  contentMetadata: unknown;
+  subtreeMetadata: unknown;
 };
 
 export type Availability = {
+  /** Integer indicating whether all of the elements are available (1) or all are unavailable (0). */
   constant?: 0 | 1;
+  /** Index of a buffer view that indicates whether each element is available. The bitstream conforms to the boolean array encoding described
+   * in the 3D Metadata specification. If an element is available, its bit is 1, and if it is unavailable, its bit is 0. */
+  bitstream?: number;
+  /**
+   * v1.1 https://github.com/CesiumGS/3d-tiles/blob/8e5e67e078850cc8ce15bd1873fe54f11bbee02f/specification/schema/Subtree/availability.schema.json
+   * vNext https://github.com/CesiumGS/3d-tiles/blob/8e5e67e078850cc8ce15bd1873fe54f11bbee02f/extensions/3DTILES_implicit_tiling/schema/subtree/availability.schema.json
+   * The schemas of vNext and 1.1 are same but there are tiles with `bufferView` property instead of `bitstream`
+   */
   bufferView?: number;
-  // Internal bitstream type
+  /**
+   * Postprocessing property
+   * contain availability bits loaded from the bufferView
+   */
   explicitBitstream?: ExplicitBitstream;
 };
 
@@ -324,7 +361,8 @@ type Buffer = {
   byteLength: number;
 };
 
-type BufferView = {
+/** Subtree buffer view */
+export type BufferView = {
   buffer: number;
   byteOffset: number;
   byteLength: number;