@loaders.gl/3d-tiles 4.3.0-alpha.6 → 4.3.0-alpha.8

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

@@ -79,47 +79,52 @@ function getChildS2VolumeBox(
  * Recursively parse implicit tiles tree
  * Spec - https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_implicit_tiling
  * TODO Check out do we able to use Tile3D class as return type here.
- * @param subtree
- * @param lodMetricValue
- * @param options
- * @param parentData
- * @param childIndex
- * @param level
- * @param globalData
+ *
+ * @param subtree - the current subtree. Subtrees contain availability data for <implicitOptions.subtreeLevels>.
+ *     Once we go deeper than that many levels, we will need load a child subtree to get further availability data.
+ * @param subtreeData - the coordinates of the current subtree, relative to the root of this implicit tiles tree.
+ * @param parentData - the coordinates of the parent tile, relative to the current subtree.
+ *     The overall coordinates of the current tile can be found by combining the coordinates of the current subtree, the parent tile,
+ *     and tje single-bit coordinates that can be calculated from the childIndex.
+ * @param childIndex - which child the current tile is of its parent. In the range 0-7 for OCTREE, 0-3 for QUADTREE.
+ * @param implicitOptions - options specified at the root of this implicit tile tree - numbers of levels, URL templates.
+ * @param loaderOptions - see Tiles3DLoaderOptions.
  */
 // eslint-disable-next-line max-statements
 export async function parseImplicitTiles(params: {
   subtree: Subtree;
-  implicitOptions: ImplicitOptions;
-  parentData?: {mortonIndex: number; x: number; y: number; z: number};
+  subtreeData?: {level: number; x: number; y: number; z: number};
+  parentData?: {
+    mortonIndex: number;
+    localLevel: number;
+    localX: number;
+    localY: number;
+    localZ: number;
+  };
   childIndex?: number;
-  level?: number;
-  globalData?: {level: number; mortonIndex: number; x: number; y: number; z: number};
-  s2VolumeBox?: S2VolumeBox;
+  implicitOptions: ImplicitOptions;
   loaderOptions: Tiles3DLoaderOptions;
+  s2VolumeBox?: S2VolumeBox;
 }) {
   const {
-    implicitOptions,
-    parentData = {
-      mortonIndex: 0,
-      x: 0,
-      y: 0,
-      z: 0
-    },
-    childIndex = 0,
-    s2VolumeBox,
-    loaderOptions
-  } = params;
-  let {
     subtree,
-    level = 0,
-    globalData = {
+    subtreeData = {
       level: 0,
-      mortonIndex: 0,
       x: 0,
       y: 0,
       z: 0
-    }
+    },
+    parentData = {
+      mortonIndex: 0,
+      localLevel: -1,
+      localX: 0,
+      localY: 0,
+      localZ: 0
+    },
+    childIndex = 0,
+    implicitOptions,
+    loaderOptions,
+    s2VolumeBox
   } = params;
   const {
     subdivisionScheme,
@@ -138,82 +143,88 @@ export async function parseImplicitTiles(params: {
     return tile;
   }
 
-  const lev = level + globalData.level;
-  if (lev > maximumLevel) {
+  // Local tile level - relative to the current subtree.
+  const localLevel = parentData.localLevel + 1;
+  // Global tile level - relative to the root tile of this implicit subdivision scheme.
+  const level = subtreeData.level + localLevel;
+
+  if (level > maximumLevel) {
     return tile;
   }
 
   const childrenPerTile = SUBDIVISION_COUNT_MAP[subdivisionScheme];
   const bitsPerTile = Math.log2(childrenPerTile);
 
-  // childIndex is in range [0,4] for quadtrees and [0, 7] for octrees
-  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
+  // childIndex is in range 0...3 for quadtrees and 0...7 for octrees
+  const lastBitX = childIndex & 0b01; // Get first bit for X
+  const lastBitY = (childIndex >> 1) & 0b01; // Get second bit for Y
+  const lastBitZ = (childIndex >> 2) & 0b01; // Get third bit for Z
 
-  const levelOffset = (childrenPerTile ** level - 1) / (childrenPerTile - 1);
-  let childTileMortonIndex = concatBits(parentData.mortonIndex, childIndex, bitsPerTile);
-  let tileAvailabilityIndex = levelOffset + childTileMortonIndex;
+  // Local tile coordinates - relative to the current subtree root.
+  const localX = concatBits(parentData.localX, lastBitX, 1);
+  const localY = concatBits(parentData.localY, lastBitY, 1);
+  const localZ = concatBits(parentData.localZ, lastBitZ, 1);
 
-  // Local tile coordinates
-  let childTileX = concatBits(parentData.x, childX, 1);
-  let childTileY = concatBits(parentData.y, childY, 1);
-  let childTileZ = concatBits(parentData.z, childZ, 1);
+  // Global tile coordinates - relative to the implicit-tile-tree root.
+  // Found by combining the local coordinates which are relative to the current subtree, with the subtree coordinates.
+  const x = concatBits(subtreeData.x, localX, localLevel);
+  const y = concatBits(subtreeData.y, localY, localLevel);
+  const z = concatBits(subtreeData.z, localZ, localLevel);
 
-  let isChildSubtreeAvailable = false;
+  const mortonIndex = concatBits(parentData.mortonIndex, childIndex, bitsPerTile);
 
-  if (level >= subtreeLevels) {
-    isChildSubtreeAvailable = getAvailabilityResult(
-      subtree.childSubtreeAvailability,
-      childTileMortonIndex
-    );
-  }
+  const isChildSubtreeAvailable =
+    localLevel === subtreeLevels &&
+    getAvailabilityResult(subtree.childSubtreeAvailability, mortonIndex);
 
-  const x = concatBits(globalData.x, childTileX, level);
-  const y = concatBits(globalData.y, childTileY, level);
-  const z = concatBits(globalData.z, childTileZ, level);
+  // Context to provide the next recursive call.
+  // This context is set up differently depending on whether its time to start a new subtree or not.
+  let nextSubtree;
+  let nextSubtreeData;
+  let nextParentData;
+  let tileAvailabilityIndex;
 
   if (isChildSubtreeAvailable) {
     const subtreePath = `${basePath}/${subtreesUriTemplate}`;
-    const childSubtreeUrl = replaceContentUrlTemplate(subtreePath, lev, x, y, z);
+    const childSubtreeUrl = replaceContentUrlTemplate(subtreePath, level, x, y, z);
     const childSubtree = await load(childSubtreeUrl, Tile3DSubtreeLoader, loaderOptions);
 
-    subtree = childSubtree;
-
-    globalData = {
-      mortonIndex: childTileMortonIndex,
-      x: childTileX,
-      y: childTileY,
-      z: childTileZ,
-      level
-    };
-
-    childTileMortonIndex = 0;
+    // The next subtree is the newly-loaded child subtree.
+    nextSubtree = childSubtree;
+    // The current tile is actually the root tile in the next subtree, so it has a tileAvailabilityIndex of 0.
     tileAvailabilityIndex = 0;
-    childTileX = 0;
-    childTileY = 0;
-    childTileZ = 0;
-    level = 0;
+    // The next subtree starts HERE - at the current tile.
+    nextSubtreeData = {level, x, y, z};
+    // The next parent is also the current tile - so it has local coordinates of 0 relative to the next subtree.
+    nextParentData = {mortonIndex: 0, localLevel: 0, localX: 0, localY: 0, localZ: 0};
+  } else {
+    // Continue on with the same subtree as we're using currently.
+    nextSubtree = subtree;
+    // Calculate a tileAvailabilityIndex for the current tile within the current subtree.
+    const levelOffset = (childrenPerTile ** localLevel - 1) / (childrenPerTile - 1);
+    tileAvailabilityIndex = levelOffset + mortonIndex;
+    // The next subtree is the same as the current subtree.
+    nextSubtreeData = subtreeData;
+    // The next parent is the current tile: it has the local coordinates we already calculated.
+    nextParentData = {mortonIndex, localLevel, localX, localY, localZ};
   }
 
-  const isTileAvailable = getAvailabilityResult(subtree.tileAvailability, tileAvailabilityIndex);
-
+  const isTileAvailable = getAvailabilityResult(
+    nextSubtree.tileAvailability,
+    tileAvailabilityIndex
+  );
   if (!isTileAvailable) {
     return tile;
   }
 
   const isContentAvailable = getAvailabilityResult(
-    subtree.contentAvailability,
+    nextSubtree.contentAvailability,
     tileAvailabilityIndex
   );
-
   if (isContentAvailable) {
-    tile.contentUrl = replaceContentUrlTemplate(contentUrlTemplate, lev, x, y, z);
+    tile.contentUrl = replaceContentUrlTemplate(contentUrlTemplate, level, x, y, z);
   }
 
-  const childTileLevel = level + 1;
-  const pData = {mortonIndex: childTileMortonIndex, x: childTileX, y: childTileY, z: childTileZ};
-
   for (let index = 0; index < childrenPerTile; index++) {
     const childS2VolumeBox: S2VolumeBox | undefined = getChildS2VolumeBox(
       s2VolumeBox,
@@ -222,32 +233,28 @@ export async function parseImplicitTiles(params: {
     );
 
     // Recursive calling...
-    const childTileParsed = await parseImplicitTiles({
-      subtree,
+    const childTile = await parseImplicitTiles({
+      subtree: nextSubtree,
+      subtreeData: nextSubtreeData,
+      parentData: nextParentData,
+      childIndex: index,
       implicitOptions,
       loaderOptions,
-      parentData: pData,
-      childIndex: index,
-      level: childTileLevel,
-      globalData: {...globalData},
       s2VolumeBox: childS2VolumeBox
     });
 
-    if (childTileParsed.contentUrl || childTileParsed.children.length) {
-      const globalLevel = lev + 1;
-      const childCoordinates = {childTileX, childTileY, childTileZ};
-      const formattedTile = formatTileData(
-        childTileParsed,
-        globalLevel,
-        childCoordinates,
-        implicitOptions,
-        s2VolumeBox
-      );
+    if (childTile.contentUrl || childTile.children.length) {
       // @ts-ignore
-      tile.children.push(formattedTile);
+      tile.children.push(childTile);
     }
   }
 
+  if (tile.contentUrl || tile.children.length) {
+    const coordinates = {level, x, y, z};
+    const formattedTile = formatTileData(tile, coordinates, implicitOptions, s2VolumeBox);
+    return formattedTile;
+  }
+
   return tile;
 }
 
@@ -290,15 +297,16 @@ function getAvailabilityResult(
 /**
  * Do formatting of implicit tile data.
  * TODO Check out do we able to use Tile3D class as type here.
- * @param tile
- * @param lodMetricValue
- * @param options
+ *
+ * @param tile - tile data to format.
+ * @param coordinates - global tile coordinates (relative to the root of the implicit tile tree).
+ * @param options - options specified at the root of this implicit tile tree - numbers of levels, URL templates.
+ * @param s2VolumeBox - the S2VolumeBox for this particular child, if available.
  * @returns
  */
 function formatTileData(
   tile,
-  level: number,
-  childCoordinates: {childTileX: number; childTileY: number; childTileZ: number},
+  coordinates: {level: number; x: number; y: number; z: number},
   options: ImplicitOptions,
   s2VolumeBox?: S2VolumeBox
 ) {
@@ -312,16 +320,16 @@ function formatTileData(
     rootBoundingVolume
   } = options;
   const uri = tile.contentUrl && tile.contentUrl.replace(`${basePath}/`, '');
-  const lodMetricValue = rootLodMetricValue / 2 ** level;
+  const lodMetricValue = rootLodMetricValue / 2 ** coordinates.level;
 
   const boundingVolume: Tile3DBoundingVolume = s2VolumeBox?.box
     ? {box: s2VolumeBox.box}
     : rootBoundingVolume;
 
   const boundingVolumeForChildTile = calculateBoundingVolumeForChildTile(
-    level,
     boundingVolume,
-    childCoordinates
+    coordinates,
+    options.subdivisionScheme
   );
 
   return {
@@ -342,37 +350,43 @@ function formatTileData(
 /**
  * Calculate child bounding volume.
  * Spec - https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_implicit_tiling#subdivision-rules
- * @param level
  * @param rootBoundingVolume
- * @param childCoordinates
+ * @param coordinates
+ * @param subdivisionScheme
  */
 function calculateBoundingVolumeForChildTile(
-  level: number,
   rootBoundingVolume: Tile3DBoundingVolume,
-  childCoordinates: {childTileX: number; childTileY: number; childTileZ: number}
+  coordinates: {level: number; x: number; y: number; z: number},
+  subdivisionScheme: string
 ): Tile3DBoundingVolume {
   if (rootBoundingVolume.region) {
-    const {childTileX, childTileY, childTileZ} = childCoordinates;
+    const {level, x, y, z} = coordinates;
     const [west, south, east, north, minimumHeight, maximumHeight] = rootBoundingVolume.region;
     const boundingVolumesCount = 2 ** level;
 
     const sizeX = (east - west) / boundingVolumesCount;
-    const sizeY = (north - south) / boundingVolumesCount;
+    const [childWest, childEast] = [west + sizeX * x, west + sizeX * (x + 1)];
 
-    // TODO : Why is the subdivisionScheme not being checked here?
+    const sizeY = (north - south) / boundingVolumesCount;
+    const [childSouth, childNorth] = [south + sizeY * y, south + sizeY * (y + 1)];
 
     // In case of QUADTREE the sizeZ should NOT be changed!
     // https://portal.ogc.org/files/102132
-    // A quadtree divides space only on the x and y dimensions. It divides each tile into 4 smaller tiles where the x and y dimensions are halved. The quadtree z minimum and maximum remain unchanged.
-
-    const sizeZ = (maximumHeight - minimumHeight) / boundingVolumesCount;
+    // A quadtree divides space only on the x and y dimensions.
+    // It divides each tile into 4 smaller tiles where the x and y dimensions are halved.
+    // The quadtree z minimum and maximum remain unchanged.
 
-    const [childWest, childEast] = [west + sizeX * childTileX, west + sizeX * (childTileX + 1)];
-    const [childSouth, childNorth] = [south + sizeY * childTileY, south + sizeY * (childTileY + 1)];
-    const [childMinimumHeight, childMaximumHeight] = [
-      minimumHeight + sizeZ * childTileZ,
-      minimumHeight + sizeZ * (childTileZ + 1)
-    ];
+    let childMinimumHeight: number;
+    let childMaximumHeight: number;
+    if (subdivisionScheme === 'OCTREE') {
+      const sizeZ = (maximumHeight - minimumHeight) / boundingVolumesCount;
+      [childMinimumHeight, childMaximumHeight] = [
+        minimumHeight + sizeZ * z,
+        minimumHeight + sizeZ * (z + 1)
+      ];
+    } else {
+      [childMinimumHeight, childMaximumHeight] = [minimumHeight, maximumHeight];
+    }
 
     return {
       region: [childWest, childSouth, childEast, childNorth, childMinimumHeight, childMaximumHeight]