Add height-query function to Tileset

CHANGES.md

@@ -4,10 +4,19 @@
 
 ##### Breaking Changes :mega:
 
+- Renamed `shouldContentContinueUpdating` to `getMightHaveLatentChildren` and `setContentShouldContinueUpdating` to `setMightHaveLatentChildren` on the `Tile` class.
 - `LoadedRasterOverlayImage` now has a single `errorList` property instead of separate `errors` and `warnings` properties.
 
+##### Additions :tada:
+
+- Added `sampleHeightMostDetailed` method to `Tileset`.
+- `AxisAlignedBox` now has `constexpr` constructors.
+
 ##### Fixes :wrench:
 
+- Fixed a bug that prevented use of `Tileset` with a nullptr `IPrepareRendererResources`.
+- Fixed a bug in `IntersectionTests::rayOBBParametric` that could cause incorrect results for some oriented bounding boxes.
+- `GltfUtilities::intersectRayGltfModel` now reports a warning when given a model it can't compute the intersection with because it uses required extensions that are not supported.
 - Errors while loading raster overlays are now logged. Previously, they were silently ignored in many cases.
 - A raster overlay image failing to load will no longer completely prevent the geometry tile to which it is attached from rendering. Instead, once the raster overlay fails, the geometry tile will be shown without the raster overlay.
 

Cesium3DTilesSelection/include/Cesium3DTilesSelection/SampleHeightResult.h

@@ -0,0 +1,42 @@
+#pragma once
+
+#include <CesiumGeospatial/Cartographic.h>
+
+#include <string>
+#include <vector>
+
+namespace Cesium3DTilesSelection {
+
+/**
+ * @brief The result of sampling heights with
+ * {@link Tileset::sampleHeightMostDetailed}.
+ */
+struct SampleHeightResult {
+  /**
+   * @brief The positions and sampled heights.
+   *
+   * The longitudes and latitudes will match the values at the same index in the
+   * original input positions. Each height will either be the height sampled
+   * from the tileset at that position, or the original input height if the
+   * height could not be sampled. To determine which, look at the value of
+   * {@link SampleHeightResult::heightSampled} at the same index.
+   */
+  std::vector<CesiumGeospatial::Cartographic> positions;
+
+  /**
+   * @brief Specifies whether the height for the position at this index was
+   * sampled successfully. If true, {@link SampleHeightResult::positions} has
+   * a valid height sampled from the tileset at this index. If false, the height
+   * could not be sampled for the position at this index, and so the height in
+   * {@link SampleHeightResult::positions} is unchanged from the original input
+   * height.
+   */
+  std::vector<bool> heightSampled;
+
+  /**
+   * @brief Any warnings that occurred while sampling heights.
+   */
+  std::vector<std::string> warnings;
+};
+
+} // namespace Cesium3DTilesSelection

Cesium3DTilesSelection/include/Cesium3DTilesSelection/Tile.h

@@ -501,10 +501,24 @@ class CESIUM3DTILESSELECTION_API Tile final {
 
   void setState(TileLoadState state) noexcept;
 
-  bool shouldContentContinueUpdating() const noexcept;
+  /**
+   * @brief Gets a flag indicating whether this tile might have latent children.
+   * Latent children don't exist in the `_children` property, but can be created
+   * by the {@link TilesetContentLoader}.
+   *
+   * When true, this tile might have children that can be created by the
+   * TilesetContentLoader but that aren't reflected in the `_children` property
+   * yet. For example, in implicit tiling, we save memory by only creating
+   * explicit Tile instances from implicit availability as those instances are
+   * needed. When this flag is true, that creation of explicit instances hasn't
+   * been done yet for this tile.
+   *
+   * If this flag is false, the children have already been created, if they
+   * exist. The tile may still have no children because it is a leaf node.
+   */
+  bool getMightHaveLatentChildren() const noexcept;
 
-  void
-  setContentShouldContinueUpdating(bool shouldContentContinueUpdating) noexcept;
+  void setMightHaveLatentChildren(bool mightHaveLatentChildren) noexcept;
 
   // Position in bounding-volume hierarchy.
   Tile* _pParent;
@@ -528,7 +542,7 @@ class CESIUM3DTILESSELECTION_API Tile final {
   TileContent _content;
   TilesetContentLoader* _pLoader;
   TileLoadState _loadState;
-  bool _shouldContentContinueUpdating;
+  bool _mightHaveLatentChildren;
 
   // mapped raster overlay
   std::vector<RasterMappedTo3DTile> _rasterTiles;

Cesium3DTilesSelection/include/Cesium3DTilesSelection/Tileset.h

@@ -2,6 +2,7 @@
 
 #include "Library.h"
 #include "RasterOverlayCollection.h"
+#include "SampleHeightResult.h"
 #include "Tile.h"
 #include "TilesetContentLoader.h"
 #include "TilesetExternals.h"
@@ -15,6 +16,7 @@
 
 #include <rapidjson/fwd.h>
 
+#include <list>
 #include <memory>
 #include <optional>
 #include <string>
@@ -23,6 +25,8 @@
 namespace Cesium3DTilesSelection {
 class TilesetContentManager;
 class TilesetMetadata;
+class TilesetHeightQuery;
+class TilesetHeightRequest;
 
 /**
  * @brief A <a
@@ -270,6 +274,27 @@ class CESIUM3DTILESSELECTION_API Tileset final {
    */
   CesiumAsync::Future<const TilesetMetadata*> loadMetadata();
 
+  /**
+   * @brief Initiates an asynchronous query for the height of this tileset at a
+   * list of positions, expressed as longitude and latitude. The most detailed
+   * available tiles are used to determine each height.
+   *
+   * The height of the input positions is ignored. On output, the height is
+   * expressed in meters above the ellipsoid (usually WGS84), which should not
+   * be confused with a height above mean sea level.
+   *
+   * Note that {@link Tileset::updateView} must be called periodically, or else
+   * the returned `Future` will never resolve. If you are not using this tileset
+   * for visualization, you can call `updateView` with an empty list of
+   * frustums.
+   *
+   * @param positions The positions for which to sample heights.
+   * @return A future that asynchronously resolves to the result of the height
+   * query.
+   */
+  CesiumAsync::Future<SampleHeightResult> sampleHeightMostDetailed(
+      const std::vector<CesiumGeospatial::Cartographic>& positions);
+
 private:
   /**
    * @brief The result of traversing one branch of the tile hierarchy.
@@ -495,6 +520,7 @@ class CESIUM3DTILESSELECTION_API Tileset final {
 
   std::vector<TileLoadTask> _mainThreadLoadQueue;
   std::vector<TileLoadTask> _workerThreadLoadQueue;
+  std::vector<Tile*> _heightQueryLoadQueue;
 
   Tile::LoadedLinkedList _loadedTiles;
 
@@ -509,6 +535,8 @@ class CESIUM3DTILESSELECTION_API Tileset final {
   CesiumUtility::IntrusivePointer<TilesetContentManager>
       _pTilesetContentManager;
 
+  std::list<TilesetHeightRequest> _heightRequests;
+
   void addTileToLoadQueue(
       Tile& tile,
       TileLoadPriorityGroup priorityGroup,

Cesium3DTilesSelection/src/Tile.cpp

@@ -57,7 +57,7 @@ Tile::Tile(
       _content{std::forward<TileContentArgs>(args)...},
       _pLoader{pLoader},
       _loadState{loadState},
-      _shouldContentContinueUpdating{true} {}
+      _mightHaveLatentChildren{true} {}
 
 Tile::Tile(Tile&& rhs) noexcept
     : _pParent(rhs._pParent),
@@ -74,7 +74,7 @@ Tile::Tile(Tile&& rhs) noexcept
       _content(std::move(rhs._content)),
       _pLoader{rhs._pLoader},
       _loadState{rhs._loadState},
-      _shouldContentContinueUpdating{rhs._shouldContentContinueUpdating} {
+      _mightHaveLatentChildren{rhs._mightHaveLatentChildren} {
   // since children of rhs will have the parent pointed to rhs,
   // we will reparent them to this tile as rhs will be destroyed after this
   for (Tile& tile : this->_children) {
@@ -105,7 +105,7 @@ Tile& Tile::operator=(Tile&& rhs) noexcept {
     this->_content = std::move(rhs._content);
     this->_pLoader = rhs._pLoader;
     this->_loadState = rhs._loadState;
-    this->_shouldContentContinueUpdating = rhs._shouldContentContinueUpdating;
+    this->_mightHaveLatentChildren = rhs._mightHaveLatentChildren;
   }
 
   return *this;
@@ -227,12 +227,12 @@ void Tile::setParent(Tile* pParent) noexcept { this->_pParent = pParent; }
 
 void Tile::setState(TileLoadState state) noexcept { this->_loadState = state; }
 
-bool Tile::shouldContentContinueUpdating() const noexcept {
-  return this->_shouldContentContinueUpdating;
+bool Tile::getMightHaveLatentChildren() const noexcept {
+  return this->_mightHaveLatentChildren;
 }
 
-void Tile::setContentShouldContinueUpdating(
-    bool shouldContentContinueUpdating) noexcept {
-  this->_shouldContentContinueUpdating = shouldContentContinueUpdating;
+void Tile::setMightHaveLatentChildren(bool mightHaveLatentChildren) noexcept {
+  this->_mightHaveLatentChildren = mightHaveLatentChildren;
 }
+
 } // namespace Cesium3DTilesSelection

Cesium3DTilesSelection/src/Tileset.cpp

@@ -1,5 +1,6 @@
 #include "TileUtilities.h"
 #include "TilesetContentManager.h"
+#include "TilesetHeightQuery.h"
 
 #include <Cesium3DTilesSelection/ITileExcluder.h>
 #include <Cesium3DTilesSelection/TileID.h>
@@ -45,13 +46,18 @@ Tileset::Tileset(
       _previousFrameNumber(0),
       _distances(),
       _childOcclusionProxies(),
-      _pTilesetContentManager{new TilesetContentManager(
-          _externals,
-          _options,
-          RasterOverlayCollection{_loadedTiles, externals, options.ellipsoid},
-          std::vector<CesiumAsync::IAssetAccessor::THeader>{},
-          std::move(pCustomLoader),
-          std::move(pRootTile))} {}
+      _pTilesetContentManager{
+          new TilesetContentManager(
+              _externals,
+              _options,
+              RasterOverlayCollection{
+                  _loadedTiles,
+                  externals,
+                  options.ellipsoid},
+              std::vector<CesiumAsync::IAssetAccessor::THeader>{},
+              std::move(pCustomLoader),
+              std::move(pRootTile)),
+      } {}
 
 Tileset::Tileset(
     const TilesetExternals& externals,
@@ -63,11 +69,16 @@ Tileset::Tileset(
       _previousFrameNumber(0),
       _distances(),
       _childOcclusionProxies(),
-      _pTilesetContentManager{new TilesetContentManager(
-          _externals,
-          _options,
-          RasterOverlayCollection{_loadedTiles, externals, options.ellipsoid},
-          url)} {}
+      _pTilesetContentManager{
+          new TilesetContentManager(
+              _externals,
+              _options,
+              RasterOverlayCollection{
+                  _loadedTiles,
+                  externals,
+                  options.ellipsoid},
+              url),
+      } {}
 
 Tileset::Tileset(
     const TilesetExternals& externals,
@@ -325,6 +336,15 @@ Tileset::updateView(const std::vector<ViewState>& frustums, float deltaTime) {
 
   Tile* pRootTile = this->getRootTile();
   if (!pRootTile) {
+    // If the root tile is already supposed to be ready, but it's not, it means
+    // the tileset couldn't load. Fail any outstanding height requests.
+    if (!this->_heightRequests.empty() && this->_pTilesetContentManager &&
+        this->_pTilesetContentManager->getRootTileAvailableEvent().isReady()) {
+      TilesetHeightRequest::failHeightRequests(
+          this->_heightRequests,
+          "Height requests could not complete because the tileset failed to "
+          "load.");
+    }
     return result;
   }
 
@@ -358,6 +378,13 @@ Tileset::updateView(const std::vector<ViewState>& frustums, float deltaTime) {
     result = ViewUpdateResult();
   }
 
+  TilesetHeightRequest::processHeightRequests(
+      *this->_pTilesetContentManager,
+      this->_options,
+      this->_loadedTiles,
+      this->_heightRequests,
+      this->_heightQueryLoadQueue);
+
   result.workerThreadTileLoadQueueLength =
       static_cast<int32_t>(this->_workerThreadLoadQueue.size());
   result.mainThreadTileLoadQueueLength =
@@ -525,6 +552,27 @@ CesiumAsync::Future<const TilesetMetadata*> Tileset::loadMetadata() {
       });
 }
 
+CesiumAsync::Future<SampleHeightResult>
+Tileset::sampleHeightMostDetailed(const std::vector<Cartographic>& positions) {
+  if (positions.empty()) {
+    return this->_asyncSystem.createResolvedFuture<SampleHeightResult>({});
+  }
+
+  Promise promise = this->_asyncSystem.createPromise<SampleHeightResult>();
+
+  std::vector<TilesetHeightQuery> queries;
+  queries.reserve(positions.size());
+
+  for (const CesiumGeospatial::Cartographic& position : positions) {
+    queries.emplace_back(position, this->_options.ellipsoid);
+  }
+
+  this->_heightRequests.emplace_back(
+      TilesetHeightRequest{std::move(queries), promise});
+
+  return promise.getFuture();
+}
+
 static void markTileNonRendered(
     TileSelectionState::Result lastResult,
     Tile& tile,
@@ -1427,17 +1475,52 @@ void Tileset::_processWorkerThreadLoadQueue() {
     return;
   }
 
-  std::vector<TileLoadTask>& queue = this->_workerThreadLoadQueue;
-  std::sort(queue.begin(), queue.end());
+  std::sort(
+      this->_workerThreadLoadQueue.begin(),
+      this->_workerThreadLoadQueue.end());
 
-  for (TileLoadTask& task : queue) {
-    this->_pTilesetContentManager->loadTileContent(*task.pTile, _options);
-    if (this->_pTilesetContentManager->getNumberOfTilesLoading() >=
-        maximumSimultaneousTileLoads) {
+  // Select tiles alternately from the two queues. Each frame, switch which
+  // queue we pull the first tile from. The goal is to schedule both height
+  // query and visualization tile loads fairly.
+  auto visIt = this->_workerThreadLoadQueue.begin();
+  auto queryIt = this->_heightQueryLoadQueue.begin();
+
+  bool nextIsVis = (this->_previousFrameNumber % 2) == 0;
+
+  while (this->_pTilesetContentManager->getNumberOfTilesLoading() <
+         maximumSimultaneousTileLoads) {
+    // Tell tiles from the current queue to load until one of them actually
+    // does. Calling loadTileContent might not actually start the loading
+    // process
+    int32_t originalNumberOfTilesLoading =
+        this->_pTilesetContentManager->getNumberOfTilesLoading();
+    if (nextIsVis) {
+      while (visIt != this->_workerThreadLoadQueue.end() &&
+             originalNumberOfTilesLoading ==
+                 this->_pTilesetContentManager->getNumberOfTilesLoading()) {
+        this->_pTilesetContentManager->loadTileContent(*visIt->pTile, _options);
+        ++visIt;
+      }
+    } else {
+      while (queryIt != this->_heightQueryLoadQueue.end() &&
+             originalNumberOfTilesLoading ==
+                 this->_pTilesetContentManager->getNumberOfTilesLoading()) {
+        this->_pTilesetContentManager->loadTileContent(**queryIt, _options);
+        ++queryIt;
+      }
+    }
+
+    if (visIt == this->_workerThreadLoadQueue.end() &&
+        queryIt == this->_heightQueryLoadQueue.end()) {
+      // No more work in either queue
       break;
     }
+
+    // Get the next tile from the other queue.
+    nextIsVis = !nextIsVis;
   }
 }
+
 void Tileset::_processMainThreadLoadQueue() {
   CESIUM_TRACE("Tileset::_processMainThreadLoadQueue");
   // Process deferred main-thread load tasks with a time budget.