@cesium/engine 2.0.0 → 2.2.0

package/Source/Scene/Cesium3DTilesetBaseTraversal.js

@@ -0,0 +1,301 @@
+import defined from "../Core/defined.js";
+import ManagedArray from "../Core/ManagedArray.js";
+import Cesium3DTileRefine from "./Cesium3DTileRefine.js";
+import Cesium3DTilesetTraversal from "./Cesium3DTilesetTraversal.js";
+
+/**
+ * Depth-first traversal that traverses all visible tiles and marks tiles for selection.
+ * A tile does not refine until all children are loaded.
+ * This is the traditional replacement refinement approach and is called the base traversal.
+ *
+ * @alias Cesium3DTilesetBaseTraversal
+ * @constructor
+ *
+ * @private
+ */
+function Cesium3DTilesetBaseTraversal() {}
+
+const traversal = {
+  stack: new ManagedArray(),
+  stackMaximumLength: 0,
+};
+
+const emptyTraversal = {
+  stack: new ManagedArray(),
+  stackMaximumLength: 0,
+};
+
+/**
+ * Traverses a {@link Cesium3DTileset} to determine which tiles to load and render.
+ *
+ * @private
+ * @param {Cesium3DTileset} tileset
+ * @param {FrameState} frameState
+ */
+Cesium3DTilesetBaseTraversal.selectTiles = function (tileset, frameState) {
+  tileset._requestedTiles.length = 0;
+
+  if (tileset.debugFreezeFrame) {
+    return;
+  }
+
+  tileset._selectedTiles.length = 0;
+  tileset._selectedTilesToStyle.length = 0;
+  tileset._emptyTiles.length = 0;
+  tileset.hasMixedContent = false;
+
+  const root = tileset.root;
+  Cesium3DTilesetTraversal.updateTile(root, frameState);
+
+  if (!root.isVisible) {
+    return;
+  }
+
+  if (
+    root.getScreenSpaceError(frameState, true) <=
+    tileset._maximumScreenSpaceError
+  ) {
+    return;
+  }
+
+  executeTraversal(root, frameState);
+
+  traversal.stack.trim(traversal.stackMaximumLength);
+  emptyTraversal.stack.trim(emptyTraversal.stackMaximumLength);
+
+  // Update the priority for any requests found during traversal
+  // Update after traversal so that min and max values can be used to normalize priority values
+  const requestedTiles = tileset._requestedTiles;
+  for (let i = 0; i < requestedTiles.length; ++i) {
+    requestedTiles[i].updatePriority();
+  }
+};
+
+/**
+ * Mark a tile as selected if it has content available.
+ *
+ * @private
+ * @param {Cesium3DTile} tile
+ * @param {FrameState} frameState
+ */
+function selectDesiredTile(tile, frameState) {
+  if (tile.contentAvailable) {
+    Cesium3DTilesetTraversal.selectTile(tile, frameState);
+  }
+}
+
+/**
+ * @private
+ * @param {Cesium3DTile} tile
+ * @param {ManagedArray} stack
+ * @param {FrameState} frameState
+ * @returns {boolean}
+ */
+function updateAndPushChildren(tile, stack, frameState) {
+  const replace = tile.refine === Cesium3DTileRefine.REPLACE;
+  const { tileset, children } = tile;
+  const { updateTile, loadTile, touchTile } = Cesium3DTilesetTraversal;
+
+  for (let i = 0; i < children.length; ++i) {
+    updateTile(children[i], frameState);
+  }
+
+  // Sort by distance to take advantage of early Z and reduce artifacts for skipLevelOfDetail
+  children.sort(Cesium3DTilesetTraversal.sortChildrenByDistanceToCamera);
+
+  // For traditional replacement refinement only refine if all children are loaded.
+  // Empty tiles are exempt since it looks better if children stream in as they are loaded to fill the empty space.
+  const checkRefines = replace && tile.hasRenderableContent;
+  let refines = true;
+
+  let anyChildrenVisible = false;
+
+  // Determining min child
+  let minIndex = -1;
+  let minimumPriority = Number.MAX_VALUE;
+
+  for (let i = 0; i < children.length; ++i) {
+    const child = children[i];
+    if (child.isVisible) {
+      stack.push(child);
+      if (child._foveatedFactor < minimumPriority) {
+        minIndex = i;
+        minimumPriority = child._foveatedFactor;
+      }
+      anyChildrenVisible = true;
+    } else if (checkRefines || tileset.loadSiblings) {
+      // Keep non-visible children loaded since they are still needed before the parent can refine.
+      // Or loadSiblings is true so always load tiles regardless of visibility.
+      if (child._foveatedFactor < minimumPriority) {
+        minIndex = i;
+        minimumPriority = child._foveatedFactor;
+      }
+      loadTile(child, frameState);
+      touchTile(child, frameState);
+    }
+    if (checkRefines) {
+      let childRefines;
+      if (!child._inRequestVolume) {
+        childRefines = false;
+      } else if (!child.hasRenderableContent) {
+        childRefines = executeEmptyTraversal(child, frameState);
+      } else {
+        childRefines = child.contentAvailable;
+      }
+      refines = refines && childRefines;
+    }
+  }
+
+  if (!anyChildrenVisible) {
+    refines = false;
+  }
+
+  if (minIndex !== -1 && replace) {
+    // An ancestor will hold the _foveatedFactor and _distanceToCamera for descendants between itself and its highest priority descendant. Siblings of a min children along the way use this ancestor as their priority holder as well.
+    // Priority of all tiles that refer to the _foveatedFactor and _distanceToCamera stored in the common ancestor will be differentiated based on their _depth.
+    const minPriorityChild = children[minIndex];
+    minPriorityChild._wasMinPriorityChild = true;
+    const priorityHolder =
+      (tile._wasMinPriorityChild || tile === tileset.root) &&
+      minimumPriority <= tile._priorityHolder._foveatedFactor
+        ? tile._priorityHolder
+        : tile; // This is where priority dependency chains are wired up or started anew.
+    priorityHolder._foveatedFactor = Math.min(
+      minPriorityChild._foveatedFactor,
+      priorityHolder._foveatedFactor
+    );
+    priorityHolder._distanceToCamera = Math.min(
+      minPriorityChild._distanceToCamera,
+      priorityHolder._distanceToCamera
+    );
+
+    for (let i = 0; i < children.length; ++i) {
+      children[i]._priorityHolder = priorityHolder;
+    }
+  }
+
+  return refines;
+}
+
+/**
+ * Depth-first traversal that traverses all visible tiles and marks tiles for selection.
+ * A tile does not refine until all children are loaded.
+ * This is the traditional replacement refinement approach and is called the base traversal.
+ *
+ * @private
+ * @param {Cesium3DTile} root
+ * @param {FrameState} frameState
+ */
+function executeTraversal(root, frameState) {
+  const { tileset } = root;
+
+  const {
+    canTraverse,
+    loadTile,
+    visitTile,
+    touchTile,
+  } = Cesium3DTilesetTraversal;
+  const stack = traversal.stack;
+  stack.push(root);
+
+  while (stack.length > 0) {
+    traversal.stackMaximumLength = Math.max(
+      traversal.stackMaximumLength,
+      stack.length
+    );
+
+    const tile = stack.pop();
+
+    const parent = tile.parent;
+    const parentRefines = !defined(parent) || parent._refines;
+
+    tile._refines = canTraverse(tile)
+      ? updateAndPushChildren(tile, stack, frameState) && parentRefines
+      : false;
+
+    const stoppedRefining = !tile._refines && parentRefines;
+
+    if (!tile.hasRenderableContent) {
+      // Add empty tile just to show its debug bounding volume
+      // If the tile has tileset content load the external tileset
+      tileset._emptyTiles.push(tile);
+      loadTile(tile, frameState);
+      if (stoppedRefining) {
+        selectDesiredTile(tile, frameState);
+      }
+    } else if (tile.refine === Cesium3DTileRefine.ADD) {
+      // Additive tiles are always loaded and selected
+      selectDesiredTile(tile, frameState);
+      loadTile(tile, frameState);
+    } else if (tile.refine === Cesium3DTileRefine.REPLACE) {
+      loadTile(tile, frameState);
+      if (stoppedRefining) {
+        selectDesiredTile(tile, frameState);
+      }
+    }
+
+    visitTile(tile, frameState);
+    touchTile(tile, frameState);
+  }
+}
+
+/**
+ * Depth-first traversal that checks if all nearest descendants with content are loaded.
+ * Ignores visibility.
+ *
+ * @private
+ * @param {Cesium3DTile} root
+ * @param {FrameState} frameState
+ * @returns {boolean}
+ */
+function executeEmptyTraversal(root, frameState) {
+  const {
+    canTraverse,
+    updateTile,
+    loadTile,
+    touchTile,
+  } = Cesium3DTilesetTraversal;
+  let allDescendantsLoaded = true;
+  const stack = emptyTraversal.stack;
+  stack.push(root);
+
+  while (stack.length > 0) {
+    emptyTraversal.stackMaximumLength = Math.max(
+      emptyTraversal.stackMaximumLength,
+      stack.length
+    );
+
+    const tile = stack.pop();
+    const children = tile.children;
+    const childrenLength = children.length;
+
+    // Only traverse if the tile is empty - traversal stops at descendants with content
+    const traverse = !tile.hasRenderableContent && canTraverse(tile);
+    const emptyLeaf = !tile.hasRenderableContent && tile.children.length === 0;
+
+    // Traversal stops but the tile does not have content yet
+    // There will be holes if the parent tries to refine to its children, so don't refine
+    // One exception: a parent may refine even if one of its descendants is an empty leaf
+    if (!traverse && !tile.contentAvailable && !emptyLeaf) {
+      allDescendantsLoaded = false;
+    }
+
+    updateTile(tile, frameState);
+    if (!tile.isVisible) {
+      // Load tiles that aren't visible since they are still needed for the parent to refine
+      loadTile(tile, frameState);
+      touchTile(tile, frameState);
+    }
+
+    if (traverse) {
+      for (let i = 0; i < childrenLength; ++i) {
+        const child = children[i];
+        stack.push(child);
+      }
+    }
+  }
+
+  return allDescendantsLoaded;
+}
+
+export default Cesium3DTilesetBaseTraversal;

package/Source/Scene/Cesium3DTilesetHeatmap.js

@@ -15,7 +15,7 @@ function Cesium3DTilesetHeatmap(tilePropertyName) {
    * The tile variable to track for heatmap colorization.
    * Tile's will be colorized relative to the other visible tile's values for this variable.
    *
-   * @type {String}
+   * @type {string}
    */
   this.tilePropertyName = tilePropertyName;
 
@@ -50,9 +50,9 @@ function getHeatmapValue(tileValue, tilePropertyName) {
 /**
  * Sets the reference minimum and maximum for the variable name. Converted to numbers before they are stored.
  *
- * @param {Object} minimum The minimum reference value.
- * @param {Object} maximum The maximum reference value.
- * @param {String} tilePropertyName The tile variable that will use these reference values when it is colorized.
+ * @param {object} minimum The minimum reference value.
+ * @param {object} maximum The maximum reference value.
+ * @param {string} tilePropertyName The tile variable that will use these reference values when it is colorized.
  */
 Cesium3DTilesetHeatmap.prototype.setReferenceMinimumMaximum = function (
   minimum,

package/Source/Scene/Cesium3DTilesetMetadata.js

@@ -14,8 +14,8 @@ import TilesetMetadata from "./TilesetMetadata.js";
  * the schema ({@link MetadataSchema}), tileset metadata ({@link TilesetMetadata}), group metadata (dictionary of {@link GroupMetadata}), and metadata statistics (dictionary)
  * </p>
  *
- * @param {Object} options Object with the following properties:
- * @param {Object} options.metadataJson Either the tileset JSON (3D Tiles 1.1) or the <code>3DTILES_metadata</code> extension object that contains the tileset metadata.
+ * @param {object} options Object with the following properties:
+ * @param {object} options.metadataJson Either the tileset JSON (3D Tiles 1.1) or the <code>3DTILES_metadata</code> extension object that contains the tileset metadata.
  * @param {MetadataSchema} options.schema The parsed schema.
  *
  * @alias Cesium3DTilesetMetadata
@@ -125,7 +125,7 @@ Object.defineProperties(Cesium3DTilesetMetadata.prototype, {
    * Only populated if using the legacy schema.
    *
    * @memberof Cesium3DTilesetMetadata.prototype
-   * @type {String[]}
+   * @type {}
    * @readonly
    * @private
    */
@@ -157,7 +157,7 @@ Object.defineProperties(Cesium3DTilesetMetadata.prototype, {
    * </p>
    *
    * @memberof Cesium3DTilesetMetadata.prototype
-   * @type {Object}
+   * @type {object}
    * @readonly
    * @private
    */
@@ -185,7 +185,7 @@ Object.defineProperties(Cesium3DTilesetMetadata.prototype, {
    * An object containing extensions.
    *
    * @memberof Cesium3DTilesetMetadata.prototype
-   * @type {Object}
+   * @type {object}
    * @readonly
    * @private
    */

package/Source/Scene/Cesium3DTilesetMostDetailedTraversal.js

@@ -1,11 +1,15 @@
 import Intersect from "../Core/Intersect.js";
 import ManagedArray from "../Core/ManagedArray.js";
 import Cesium3DTileRefine from "./Cesium3DTileRefine.js";
+import Cesium3DTilesetTraversal from "./Cesium3DTilesetTraversal.js";
 
 /**
  * Traversal that loads all leaves that intersect the camera frustum.
  * Used to determine ray-tileset intersections during a pickFromRayMostDetailed call.
  *
+ * @alias Cesium3DTilesetMostDetailedTraversal
+ * @constructor
+ *
  * @private
  */
 function Cesium3DTilesetMostDetailedTraversal() {}
@@ -15,25 +19,35 @@ const traversal = {
   stackMaximumLength: 0,
 };
 
+/**
+ * Traverses a {@link Cesium3DTileset} to determine which tiles to load and render.
+ *
+ * @private
+ * @param {Cesium3DTileset} tileset
+ * @param {FrameState} frameState
+ * @returns {boolean} Whether the appropriate tile is ready for picking
+ */
 Cesium3DTilesetMostDetailedTraversal.selectTiles = function (
   tileset,
   frameState
 ) {
   tileset._selectedTiles.length = 0;
   tileset._requestedTiles.length = 0;
-  tileset._hasMixedContent = false;
+  tileset.hasMixedContent = false;
 
   let ready = true;
 
   const root = tileset.root;
   root.updateVisibility(frameState);
 
-  if (!isVisible(root)) {
+  if (!root.isVisible) {
     return ready;
   }
 
+  const { touchTile, visitTile } = Cesium3DTilesetTraversal;
+
   const stack = traversal.stack;
-  stack.push(tileset.root);
+  stack.push(root);
 
   while (stack.length > 0) {
     traversal.stackMaximumLength = Math.max(
@@ -44,23 +58,23 @@ Cesium3DTilesetMostDetailedTraversal.selectTiles = function (
     const tile = stack.pop();
     const add = tile.refine === Cesium3DTileRefine.ADD;
     const replace = tile.refine === Cesium3DTileRefine.REPLACE;
-    const traverse = canTraverse(tileset, tile);
+    const traverse = canTraverse(tile);
 
     if (traverse) {
-      updateAndPushChildren(tileset, tile, stack, frameState);
+      updateAndPushChildren(tile, stack, frameState);
     }
 
     if (add || (replace && !traverse)) {
       loadTile(tileset, tile);
-      touchTile(tileset, tile, frameState);
-      selectDesiredTile(tileset, tile, frameState);
+      touchTile(tile, frameState);
+      selectDesiredTile(tile, frameState);
 
-      if (!hasEmptyContent(tile) && !tile.contentAvailable) {
+      if (tile.hasRenderableContent && !tile.contentAvailable) {
         ready = false;
       }
     }
 
-    visitTile(tileset);
+    visitTile(tile, frameState);
   }
 
   traversal.stack.trim(traversal.stackMaximumLength);
@@ -68,21 +82,7 @@ Cesium3DTilesetMostDetailedTraversal.selectTiles = function (
   return ready;
 };
 
-function isVisible(tile) {
-  return tile._visible && tile._inRequestVolume;
-}
-
-function hasEmptyContent(tile) {
-  return (
-    tile.hasEmptyContent || tile.hasTilesetContent || tile.hasImplicitContent
-  );
-}
-
-function hasUnloadedContent(tile) {
-  return !hasEmptyContent(tile) && tile.contentUnloaded;
-}
-
-function canTraverse(tileset, tile) {
+function canTraverse(tile) {
   if (tile.children.length === 0) {
     return false;
   }
@@ -97,48 +97,35 @@ function canTraverse(tileset, tile) {
     return true;
   }
 
-  return true; // Keep traversing until a leave is hit
+  return true; // Keep traversing until a leaf is hit
 }
 
-function updateAndPushChildren(tileset, tile, stack, frameState) {
-  const children = tile.children;
-  const length = children.length;
+function updateAndPushChildren(tile, stack, frameState) {
+  const { children } = tile;
 
-  for (let i = 0; i < length; ++i) {
+  for (let i = 0; i < children.length; ++i) {
     const child = children[i];
     child.updateVisibility(frameState);
-    if (isVisible(child)) {
+    if (child.isVisible) {
       stack.push(child);
     }
   }
 }
 
 function loadTile(tileset, tile) {
-  if (hasUnloadedContent(tile) || tile.contentExpired) {
+  if (tile.hasUnloadedRenderableContent || tile.contentExpired) {
     tile._priority = 0.0; // Highest priority
     tileset._requestedTiles.push(tile);
   }
 }
 
-function touchTile(tileset, tile, frameState) {
-  if (tile._touchedFrame === frameState.frameNumber) {
-    // Prevents another pass from touching the frame again
-    return;
-  }
-  tileset._cache.touch(tile);
-  tile._touchedFrame = frameState.frameNumber;
-}
-
-function visitTile(tileset) {
-  ++tileset.statistics.visited;
-}
-
-function selectDesiredTile(tileset, tile, frameState) {
+function selectDesiredTile(tile, frameState) {
   if (
     tile.contentAvailable &&
     tile.contentVisibility(frameState) !== Intersect.OUTSIDE
   ) {
-    tileset._selectedTiles.push(tile);
+    tile.tileset._selectedTiles.push(tile);
   }
 }
+
 export default Cesium3DTilesetMostDetailedTraversal;