Allow access to Tileset-level metadata (schema, schemaUri, groups, metadata)

CHANGES.md

@@ -7,13 +7,19 @@
 - Renamed `ExtensionReaderContext` to `JsonReaderOptions`, and the `getExtensions` method on various JSON reader classes to `getOptions`.
 - `IExtensionJsonHandler` no longer derives from `IJsonHandler`. Instead, it has a new pure virtual method, `getHandler`, that must be implemented to allow clients to obtain the `IJsonHandler`. In almost all implementations, this should simply return `*this`.
 - In `SubtreeReader`, `SchemaReader`, and `TilesetReader`, the `readSubtree`, `readSchema`, and `readTileset` methods (respectively) have been renamed to `readFromJson` and return a templated `ReadJsonResult` instead of a bespoke result class.
+- `TileExternalContent` is now heap allocated and stored in `TileContent` with a `std::unique_ptr`.
+- The root `Tile` of a `Cesium3DTilesSelection::Tileset` now represents the tileset.json itself, and the `root` tile specified in the tileset.json is its only child. This makes the shape of the tile tree consistent between a standard top-level tileset and an external tileset embedded elsewhere in the tree. In both cases, the "tile" that represents the tileset.json itself has content of type `TileExternalContent`.
 
 ##### Additions :tada:
 
 - Unknown properties in objects read with a `JsonReader` are now stored in the `unknownProperties` property on `ExtensibleObject` by default. To ignore them, as was done in previous versions, call `setCaptureUnknownProperties` on `JsonReaderOptions`.
 - Added `ValueType` type alias to `ArrayJsonHandler`, for consistency with other JSON handlers.
 - Added an overload of `JsonReader::readJson` that takes a `rapidjson::Value` instead of a byte buffer. This allows a subtree of a `rapidjson::Document` to be easily and efficiently converted into statically-typed classes via `IJsonHandler`.
 - Added `*Reader` classes to `CesiumGltfReader` and `Cesium3DTilesReader` to allow each of the classes to be individually read from JSON.
+- Added `getExternalContent` method to the `TileContent` class.
+- `TileExternalContent` now holds the metadata (`schema`, `schemaUri`, `metadata`, and `groups`) stored in the tileset.json.
+- Added `loadMetadata` and `getMetadata` methods to `Cesium3DTilesSelection::Tileset`. They provide access to `TilesetMetadata` instance representing the metadata associated with a tileset.json.
+- Added `MetadataQuery` class to make it easier to find properties with specific semantics in `TilesetMetadata`.
 
 ### v0.27.0 - 2023-09-01
 

Cesium3DTiles/include/Cesium3DTiles/MetadataQuery.h

@@ -0,0 +1,74 @@
+#pragma once
+
+#include <Cesium3DTiles/MetadataEntity.h>
+#include <Cesium3DTiles/Schema.h>
+#include <CesiumUtility/JsonValue.h>
+
+#include <string>
+#include <unordered_map>
+
+namespace Cesium3DTiles {
+
+/**
+ * @brief Holds the details of a found property in a {@link MetadataEntity}.
+ *
+ * Because this structure holds _references_ to the original {@link Schema} and
+ * {@link MetadataEntity} instances, it will be invalided if either are
+ * destroyed or modified. Continuing to access this result in that scenario will
+ * result in undefined behavior.
+ */
+struct CESIUM3DTILES_API FoundMetadataProperty {
+  /**
+   * @brief A reference to the identifier of the class that contains the found
+   * property within the {@link Schema}.
+   */
+  const std::string& classIdentifier;
+
+  /**
+   * @brief A reference to the {@link Class} that contains the found property
+   * within the {@link Schema}.
+   */
+  const Class& classDefinition;
+
+  /**
+   * @brief A reference to the identifier of the found property within the
+   * {@link Schema}.
+   */
+  const std::string& propertyIdentifier;
+
+  /**
+   * @brief A reference to the {@link ClassProperty} describing the found
+   * property within the {@lnik Schema}.
+   */
+  const ClassProperty& propertyDefinition;
+
+  /**
+   * @brief A reference to the value of the found property within the
+   * {@link MetadataEntity}.
+   */
+  const CesiumUtility::JsonValue& propertyValue;
+};
+
+/**
+ * @brief Convenience functions for querying {@link MetadataEntity} instances.
+ */
+class CESIUM3DTILES_API MetadataQuery {
+public:
+  /**
+   * @brief Gets the first property with a given
+   * {@link ClassProperty::semantic}.
+   *
+   * @param schema The schema to use to look up semantics.
+   * @param entity The metadata entity to search for a property with the
+   * semantic.
+   * @param semantic The semantic to find.
+   * @return The details of the found property, or `std::nullopt` if a property
+   * with the given semantic does not exist.
+   */
+  static std::optional<FoundMetadataProperty> findFirstPropertyWithSemantic(
+      const Schema& schema,
+      const MetadataEntity& entity,
+      const std::string& semantic);
+};
+
+} // namespace Cesium3DTiles

Cesium3DTiles/src/MetadataQuery.cpp

@@ -0,0 +1,38 @@
+#include <Cesium3DTiles/MetadataQuery.h>
+
+namespace Cesium3DTiles {
+
+std::optional<FoundMetadataProperty>
+MetadataQuery::findFirstPropertyWithSemantic(
+    const Schema& schema,
+    const MetadataEntity& entity,
+    const std::string& semantic) {
+  auto classIt = schema.classes.find(entity.classProperty);
+  if (classIt == schema.classes.end()) {
+    return std::nullopt;
+  }
+
+  const Cesium3DTiles::Class& klass = classIt->second;
+
+  for (auto it = entity.properties.begin(); it != entity.properties.end();
+       ++it) {
+    const std::pair<std::string, CesiumUtility::JsonValue>& property = *it;
+    auto propertyIt = klass.properties.find(property.first);
+    if (propertyIt == klass.properties.end())
+      continue;
+
+    const ClassProperty& classProperty = propertyIt->second;
+    if (classProperty.semantic == semantic) {
+      return FoundMetadataProperty{
+          classIt->first,
+          classIt->second,
+          it->first,
+          propertyIt->second,
+          it->second};
+    }
+  }
+
+  return std::nullopt;
+}
+
+} // namespace Cesium3DTiles

Cesium3DTiles/test/TestMetadataQuery.cpp

@@ -0,0 +1,55 @@
+#include <Cesium3DTiles/MetadataQuery.h>
+
+#include <catch2/catch.hpp>
+
+using namespace Cesium3DTiles;
+using namespace CesiumUtility;
+
+TEST_CASE("MetadataQuery") {
+  SECTION("findFirstPropertyWithSemantic") {
+    Schema schema{};
+    Class& classDefinition =
+        schema.classes.emplace("someClass", Class()).first->second;
+
+    ClassProperty& classProperty1 =
+        classDefinition.properties.emplace("someProperty", ClassProperty())
+            .first->second;
+    classProperty1.type = ClassProperty::Type::SCALAR;
+    classProperty1.componentType = ClassProperty::ComponentType::FLOAT64;
+
+    ClassProperty& classProperty2 =
+        classDefinition.properties
+            .emplace("somePropertyWithSemantic", ClassProperty())
+            .first->second;
+    classProperty2.type = ClassProperty::Type::STRING;
+    classProperty2.semantic = "SOME_SEMANTIC";
+
+    MetadataEntity withoutSemantic;
+    withoutSemantic.classProperty = "someClass";
+    withoutSemantic.properties.emplace("someProperty", JsonValue(3.0));
+
+    MetadataEntity withSemantic = withoutSemantic;
+    withSemantic.properties.emplace(
+        "somePropertyWithSemantic",
+        JsonValue("the value"));
+
+    std::optional<FoundMetadataProperty> foundProperty1 =
+        MetadataQuery::findFirstPropertyWithSemantic(
+            schema,
+            withoutSemantic,
+            "SOME_SEMANTIC");
+    CHECK(!foundProperty1);
+
+    std::optional<FoundMetadataProperty> foundProperty2 =
+        MetadataQuery::findFirstPropertyWithSemantic(
+            schema,
+            withSemantic,
+            "SOME_SEMANTIC");
+    REQUIRE(foundProperty2);
+    CHECK(foundProperty2->classIdentifier == "someClass");
+    CHECK(&foundProperty2->classDefinition == &classDefinition);
+    CHECK(foundProperty2->propertyIdentifier == "somePropertyWithSemantic");
+    CHECK(&foundProperty2->propertyDefinition == &classProperty2);
+    CHECK(foundProperty2->propertyValue.getStringOrDefault("") == "the value");
+  }
+}

Cesium3DTilesSelection/CMakeLists.txt

@@ -43,6 +43,8 @@ target_include_directories(
 
 target_link_libraries(Cesium3DTilesSelection
     PUBLIC
+        Cesium3DTiles
+        Cesium3DTilesReader
         CesiumAsync
         CesiumGeospatial
         CesiumGeometry

Cesium3DTilesSelection/include/Cesium3DTilesSelection/Tile.h

@@ -115,7 +115,7 @@ class CESIUM3DTILESSELECTION_API Tile final {
    */
   Tile(
       TilesetContentLoader* pLoader,
-      TileExternalContent externalContent) noexcept;
+      std::unique_ptr<TileExternalContent>&& externalContent) noexcept;
 
   /**
    * @brief Construct a tile with an empty content and a loader that is

Cesium3DTilesSelection/include/Cesium3DTilesSelection/TileContent.h

@@ -3,12 +3,14 @@
 #include "CreditSystem.h"
 #include "Library.h"
 #include "RasterOverlayDetails.h"
+#include "TilesetMetadata.h"
 
 #include <CesiumGeospatial/Projection.h>
 #include <CesiumGltf/Model.h>
 
 #include <memory>
 #include <variant>
+#include <vector>
 
 namespace Cesium3DTilesSelection {
 /**
@@ -47,7 +49,12 @@ struct CESIUM3DTILESSELECTION_API TileEmptyContent {};
  * external tileset. When this tile is loaded, all the tiles in the
  * external tileset will become children of this external content tile
  */
-struct CESIUM3DTILESSELECTION_API TileExternalContent {};
+struct CESIUM3DTILESSELECTION_API TileExternalContent {
+  /**
+   * @brief The metadata associated with this tileset.
+   */
+  TilesetMetadata metadata;
+};
 
 /**
  * @brief A content tag that indicates a tile has a glTF model content and
@@ -198,7 +205,7 @@ class CESIUM3DTILESSELECTION_API TileContent {
   using TileContentKindImpl = std::variant<
       TileUnknownContent,
       TileEmptyContent,
-      TileExternalContent,
+      std::unique_ptr<TileExternalContent>,
       std::unique_ptr<TileRenderContent>>;
 
 public:
@@ -218,7 +225,7 @@ class CESIUM3DTILESSELECTION_API TileContent {
    * @brief Construct an external content for a tile whose content
    * points to an external tileset
    */
-  TileContent(TileExternalContent content);
+  TileContent(std::unique_ptr<TileExternalContent>&& content);
 
   /**
    * @brief Set an unknown content tag for a tile. This constructor
@@ -236,7 +243,7 @@ class CESIUM3DTILESSELECTION_API TileContent {
    * @brief Set an external content for a tile whose content
    * points to an external tileset
    */
-  void setContentKind(TileExternalContent content);
+  void setContentKind(std::unique_ptr<TileExternalContent>&& content);
 
   /**
    * @brief Set a glTF model content for a tile
@@ -267,21 +274,27 @@ class CESIUM3DTILESSELECTION_API TileContent {
   /**
    * @brief Get the {@link TileRenderContent} which stores the glTF model
    * and render resources of the tile
-   *
-   * @return The {@link TileRenderContent} which stores the glTF model
-   * and render resources of the tile
    */
   const TileRenderContent* getRenderContent() const noexcept;
 
   /**
    * @brief Get the {@link TileRenderContent} which stores the glTF model
    * and render resources of the tile
-   *
-   * @return The {@link TileRenderContent} which stores the glTF model
-   * and render resources of the tile
    */
   TileRenderContent* getRenderContent() noexcept;
 
+  /**
+   * @brief Get the {@link TileExternalContent} which stores the details of
+   * the external tileset.
+   */
+  const TileExternalContent* getExternalContent() const noexcept;
+
+  /**
+   * @brief Get the {@link TileExternalContent} which stores the details of
+   * the external tileset.
+   */
+  TileExternalContent* getExternalContent() noexcept;
+
 private:
   TileContentKindImpl _contentKind;
 };

Cesium3DTilesSelection/include/Cesium3DTilesSelection/Tileset.h

@@ -22,6 +22,7 @@
 
 namespace Cesium3DTilesSelection {
 class TilesetContentManager;
+class TilesetMetadata;
 
 /**
  * @brief A <a
@@ -74,13 +75,6 @@ class CESIUM3DTILESSELECTION_API Tileset final {
       const TilesetOptions& options = TilesetOptions(),
       const std::string& ionAssetEndpointUrl = "https://api.cesium.com/");
 
-  /**
-   * @brief A future that resolves when this Tileset has been destroyed (i.e.
-   * its destructor has been called) and all async operations that it was
-   * executing have completed.
-   */
-  CesiumAsync::SharedFuture<void>& getAsyncDestructionCompleteEvent();
-
   /**
    * @brief Destroys this tileset.
    *
@@ -93,6 +87,20 @@ class CESIUM3DTILESSELECTION_API Tileset final {
    */
   ~Tileset() noexcept;
 
+  /**
+   * @brief A future that resolves when this Tileset has been destroyed (i.e.
+   * its destructor has been called) and all async operations that it was
+   * executing have completed.
+   */
+  CesiumAsync::SharedFuture<void>& getAsyncDestructionCompleteEvent();
+
+  /**
+   * @brief A future that resolves when the details of the root tile of this
+   * tileset are available. The root tile's content (e.g., 3D model), however,
+   * will not necessarily be loaded yet.
+   */
+  CesiumAsync::SharedFuture<void>& getRootTileAvailableEvent();
+
   /**
    * @brief Get tileset credits.
    */
@@ -207,6 +215,49 @@ class CESIUM3DTILESSELECTION_API Tileset final {
    */
   int64_t getTotalDataBytes() const noexcept;
 
+  /**
+   * @brief Gets the {@link TilesetMetadata} associated with the main or
+   * external tileset.json that contains a given tile. If the metadata is not
+   * yet loaded, this method returns nullptr.
+   *
+   * If this tileset's root tile is not yet available, this method returns
+   * nullptr.
+   *
+   * If the tileset has a {@link TilesetMetadata::schemaUri}, it will not
+   * necessarily have been loaded yet.
+   *
+   * If the provided tile is not the root tile of a tileset.json, this method
+   * walks up the {@link Tile::getParent} chain until it finds the closest
+   * root and then returns the metadata associated with the corresponding
+   * tileset.json.
+   *
+   * Consider calling {@link loadMetadata} instead, which will return a future
+   * that only resolves after the root tile is loaded and the `schemaUri`, if
+   * any, has been resolved.
+   *
+   * @param pTile The tile. If this parameter is nullptr, the metadata for the
+   * main tileset.json is returned.
+   * @return The found metadata, or nullptr if the root tile is not yet loaded.
+   */
+  const TilesetMetadata* getMetadata(const Tile* pTile = nullptr) const;
+
+  /**
+   * @brief Asynchronously loads the metadata associated with the main
+   * tileset.json.
+   *
+   * Before the returned future resolves, the root tile of this tileset will be
+   * loaded and the {@link TilesetMetadata::schemaUri} will be loaded if one
+   * has been specified.
+   *
+   * If the tileset or `schemaUri` fail to load, the returned future will
+   * reject.
+   *
+   * @return A shared future that resolves to the loaded metadata. Once this
+   * future resolves, {@link findMetadata} can be used to synchronously obtain
+   * the same metadata instance.
+   */
+  CesiumAsync::Future<const TilesetMetadata*> loadMetadata();
+
 private:
   /**
    * @brief The result of traversing one branch of the tile hierarchy.