Implement support for KHR_gaussian_splatting and KHR_gaussian_splatting_compression_spz_2

CHANGES.md

@@ -13,6 +13,11 @@
 - Added `Uri::ensureTrailingSlash`, which is helpful when the `Uri` represents a base URL.
 - Added `GltfModifier`, which can be used to modify tile glTFs as they load, as well as apply new modifications to them later.
 
+##### Additions :tada:
+
+- Added support for the `KHR_gaussian_splatting` extension.
+  - SPZ payloads for `KHR_guassian_splatting` using the `KHR_gaussian_splatting_compression_spz_2` extension will now be decoded.
+
 ##### Fixes :wrench:
 
 - Fixed a bug in `GoogleMapTilesRasterOverlay` that tried to parse credits from an erroneous viewport service response.

CMakeLists.txt

@@ -100,7 +100,7 @@ set(PACKAGES_PUBLIC asyncplusplus expected-lite fmt glm rapidjson spdlog stb ada
 set(PACKAGES_PRIVATE
     abseil draco ktx modp-base64 meshoptimizer openssl s2geometry
     libjpeg-turbo sqlite3 tinyxml2 libwebp zlib-ng picosha2
-    earcut-hpp cpp-httplib[core] libmorton zstd
+    earcut-hpp cpp-httplib[core] libmorton zstd spz zlib
 )
 
 # asmjit needed by blend2d on non-iOS platforms (iOS doesn't support JIT)
@@ -124,7 +124,7 @@ if(CESIUM_USE_EZVCPKG)
     list(APPEND PACKAGES_ALL ${PACKAGES_TEST})
 
     ezvcpkg_fetch(
-        COMMIT 2025.09.17
+        COMMIT d80785c4ee1df22a4119a3451452f59e978e06aa
         PACKAGES ${PACKAGES_ALL}
         # Clean the build trees after building, so that we don't use a ton a disk space on the CI cache
         CLEAN_BUILDTREES
@@ -326,6 +326,7 @@ find_package(meshoptimizer CONFIG REQUIRED)
 find_package(OpenSSL REQUIRED)
 find_package(s2 CONFIG REQUIRED)
 find_package(spdlog CONFIG REQUIRED)
+find_package(spz CONFIG REQUIRED)
 find_package(tinyxml2 CONFIG REQUIRED)
 find_package(unofficial-sqlite3 CONFIG REQUIRED)
 find_package(WebP CONFIG REQUIRED)

CesiumGltf/generated/include/CesiumGltf/ExtensionKhrGaussianSplatting.h

@@ -0,0 +1,121 @@
+// This file was generated by generate-classes.
+// DO NOT EDIT THIS FILE!
+#pragma once
+
+#include <CesiumGltf/Library.h>
+#include <CesiumUtility/ExtensibleObject.h>
+
+#include <string>
+
+namespace CesiumGltf {
+/**
+ * @brief Data defining a 3D Gaussian Splat primitive.
+ */
+struct CESIUMGLTF_API ExtensionKhrGaussianSplatting final
+    : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
+  static constexpr const char* TypeName = "ExtensionKhrGaussianSplatting";
+  /** @brief The official name of the extension. This should be the same as its
+   * key in the `extensions` object. */
+  static constexpr const char* ExtensionName = "KHR_gaussian_splatting";
+
+  /**
+   * @brief Known values for Optional property specifying how to project the
+   * Gaussians to achieve a perspective correct value. This property defaults to
+   * perspective.
+   */
+  struct Projection {
+    /** @brief `perspective` */
+    inline static const std::string perspective = "perspective";
+
+    /** @brief `orthographic` */
+    inline static const std::string orthographic = "orthographic";
+  };
+
+  /**
+   * @brief Known values for Optional property specifying how to sort the
+   * Gaussians during rendering. This property defaults to cameraDistance.
+   */
+  struct SortingMethod {
+    /** @brief `cameraDistance` */
+    inline static const std::string cameraDistance = "cameraDistance";
+
+    /** @brief `zDepth` */
+    inline static const std::string zDepth = "zDepth";
+  };
+
+  /**
+   * @brief Known values for Optional property specifying the color space of the
+   * spherical harmonics. This property defaults to BT.709.
+   */
+  struct ColorSpace {
+    /** @brief `BT.709` */
+    inline static const std::string BT_709 = "BT.709";
+
+    /** @brief `BT.2020-ITU` */
+    inline static const std::string BT_2020_ITU = "BT.2020-ITU";
+
+    /** @brief `BT.2020-HLG` */
+    inline static const std::string BT_2020_HLG = "BT.2020-HLG";
+
+    /** @brief `BT.2020-PQ` */
+    inline static const std::string BT_2020_PQ = "BT.2020-PQ";
+
+    /** @brief `Display-P3` */
+    inline static const std::string Display_P3 = "Display-P3";
+
+    /** @brief `linear` */
+    inline static const std::string linear = "linear";
+  };
+
+  /**
+   * @brief Optional property specifying parameters regarding the kernel used to
+   * generate the Gaussians. This property defaults to ellipse.
+   */
+  std::string kernel = "ellipse";
+
+  /**
+   * @brief Optional property specifying how to project the Gaussians to achieve
+   * a perspective correct value. This property defaults to perspective.
+   *
+   * Known values are defined in {@link Projection}.
+   *
+   */
+  std::string projection = Projection::perspective;
+
+  /**
+   * @brief Optional property specifying how to sort the Gaussians during
+   * rendering. This property defaults to cameraDistance.
+   *
+   * Known values are defined in {@link SortingMethod}.
+   *
+   */
+  std::string sortingMethod = SortingMethod::cameraDistance;
+
+  /**
+   * @brief Optional property specifying the color space of the spherical
+   * harmonics. This property defaults to BT.709.
+   *
+   * Known values are defined in {@link ColorSpace}.
+   *
+   */
+  std::string colorSpace = ColorSpace::BT_709;
+
+  /**
+   * @brief Calculates the size in bytes of this object, including the contents
+   * of all collections, pointers, and strings. This will NOT include the size
+   * of any extensions attached to the object. Calling this method may be slow
+   * as it requires traversing the object's entire structure.
+   */
+  int64_t getSizeBytes() const {
+    int64_t accum = 0;
+    accum += int64_t(sizeof(ExtensionKhrGaussianSplatting));
+    accum += CesiumUtility::ExtensibleObject::getSizeBytes() -
+             int64_t(sizeof(CesiumUtility::ExtensibleObject));
+    accum += int64_t(this->kernel.capacity() * sizeof(char));
+    return accum;
+  }
+};
+} // namespace CesiumGltf

CesiumGltf/generated/include/CesiumGltf/ExtensionKhrGaussianSplattingCompressionSpz2.h

@@ -0,0 +1,46 @@
+// This file was generated by generate-classes.
+// DO NOT EDIT THIS FILE!
+#pragma once
+
+#include <CesiumGltf/Library.h>
+#include <CesiumUtility/ExtensibleObject.h>
+
+#include <cstdint>
+
+namespace CesiumGltf {
+/**
+ * @brief Compressed data for SPZ v2 primitive.
+ */
+struct CESIUMGLTF_API ExtensionKhrGaussianSplattingCompressionSpz2 final
+    : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
+  static constexpr const char* TypeName =
+      "ExtensionKhrGaussianSplattingCompressionSpz2";
+  /** @brief The official name of the extension. This should be the same as its
+   * key in the `extensions` object. */
+  static constexpr const char* ExtensionName =
+      "KHR_gaussian_splatting_compression_spz_2";
+
+  /**
+   * @brief The index of the bufferView.
+   */
+  int32_t bufferView = -1;
+
+  /**
+   * @brief Calculates the size in bytes of this object, including the contents
+   * of all collections, pointers, and strings. This will NOT include the size
+   * of any extensions attached to the object. Calling this method may be slow
+   * as it requires traversing the object's entire structure.
+   */
+  int64_t getSizeBytes() const {
+    int64_t accum = 0;
+    accum += int64_t(sizeof(ExtensionKhrGaussianSplattingCompressionSpz2));
+    accum += CesiumUtility::ExtensibleObject::getSizeBytes() -
+             int64_t(sizeof(CesiumUtility::ExtensibleObject));
+
+    return accum;
+  }
+};
+} // namespace CesiumGltf

CesiumGltf/generated/include/CesiumGltf/ExtensionKhrGaussianSplattingHintsValue.h

@@ -0,0 +1,53 @@
+// This file was generated by generate-classes.
+// DO NOT EDIT THIS FILE!
+#pragma once
+
+#include <CesiumGltf/Library.h>
+#include <CesiumUtility/ExtensibleObject.h>
+
+#include <string>
+
+namespace CesiumGltf {
+/**
+ * @brief Optional rendering hints for rendering the 3D Gaussian splats.
+ * Renderers are free to ignore any of these.
+ */
+struct CESIUMGLTF_API ExtensionKhrGaussianSplattingHintsValue final
+    : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
+  static constexpr const char* TypeName =
+      "ExtensionKhrGaussianSplattingHintsValue";
+
+  /**
+   * @brief Provides a hint specifying how to project the Gaussians to achieve a
+   * perspective correct value. This is a freeform field that defaults to
+   * perspective. See the extension specification for further known types.
+   */
+  std::string projection = "perspective";
+
+  /**
+   * @brief Provides a hint specifying how to sort the Gaussians during
+   * rendering. This is a freeform field defaulting to cameraDistance. See the
+   * extension specification for further known types.
+   */
+  std::string sortingMethod = "cameraDistance";
+
+  /**
+   * @brief Calculates the size in bytes of this object, including the contents
+   * of all collections, pointers, and strings. This will NOT include the size
+   * of any extensions attached to the object. Calling this method may be slow
+   * as it requires traversing the object's entire structure.
+   */
+  int64_t getSizeBytes() const {
+    int64_t accum = 0;
+    accum += int64_t(sizeof(ExtensionKhrGaussianSplattingHintsValue));
+    accum += CesiumUtility::ExtensibleObject::getSizeBytes() -
+             int64_t(sizeof(CesiumUtility::ExtensibleObject));
+    accum += int64_t(this->projection.capacity() * sizeof(char));
+    accum += int64_t(this->sortingMethod.capacity() * sizeof(char));
+    return accum;
+  }
+};
+} // namespace CesiumGltf

CesiumGltf/generated/include/CesiumGltf/ExtensionTextureWebp.h

@@ -22,7 +22,7 @@ struct CESIUMGLTF_API ExtensionTextureWebp final
   static constexpr const char* ExtensionName = "EXT_texture_webp";
 
   /**
-   * @brief The index of the images node which points to a WebP image.
+   * @brief The index of the WebP image.
    */
   int32_t source = -1;
 

CesiumGltf/src/Model.cpp

@@ -45,6 +45,10 @@
 #include <glm/ext/vector_float3.hpp>
 #include <glm/geometric.hpp>
 #include <glm/gtx/norm.hpp>
+// Despite what clang-tidy will say, we *do* actually need this include or we'll
+// get a "missing mat4_cast" error.
+// NOLINTNEXTLINE
+#include <glm/gtc/quaternion.hpp>
 
 #include <algorithm>
 #include <array>

CesiumGltfReader/CMakeLists.txt

@@ -62,6 +62,7 @@ target_link_libraries(CesiumGltfReader
         meshoptimizer::meshoptimizer
         modp_b64::modp_b64
         KTX::ktx
+        spz::spz
         WebP::webp WebP::webpdecoder
         $<IF:$<TARGET_EXISTS:libjpeg-turbo::turbojpeg>,libjpeg-turbo::turbojpeg,libjpeg-turbo::turbojpeg-static>
 )

CesiumGltfReader/generated/include/CesiumGltfReader/ExtensionKhrGaussianSplattingCompressionSpz2Reader.h

@@ -0,0 +1,79 @@
+// This file was generated by generate-classes.
+// DO NOT EDIT THIS FILE!
+#pragma once
+
+#include <CesiumGltf/ExtensionKhrGaussianSplattingCompressionSpz2.h>
+#include <CesiumGltfReader/Library.h>
+#include <CesiumJsonReader/JsonReader.h>
+#include <CesiumJsonReader/JsonReaderOptions.h>
+
+#include <rapidjson/fwd.h>
+
+#include <span>
+#include <vector>
+
+namespace CesiumGltf {
+struct ExtensionKhrGaussianSplattingCompressionSpz2;
+} // namespace CesiumGltf
+
+namespace CesiumGltfReader {
+
+/**
+ * @brief Reads \ref CesiumGltf::ExtensionKhrGaussianSplattingCompressionSpz2
+ * "ExtensionKhrGaussianSplattingCompressionSpz2" instances from JSON.
+ */
+class CESIUMGLTFREADER_API ExtensionKhrGaussianSplattingCompressionSpz2Reader {
+public:
+  /**
+   * @brief Constructs a new instance.
+   */
+  ExtensionKhrGaussianSplattingCompressionSpz2Reader();
+
+  /**
+   * @brief Gets the options controlling how the JSON is read.
+   */
+  CesiumJsonReader::JsonReaderOptions& getOptions();
+
+  /**
+   * @brief Gets the options controlling how the JSON is read.
+   */
+  const CesiumJsonReader::JsonReaderOptions& getOptions() const;
+
+  /**
+   * @brief Reads an instance of ExtensionKhrGaussianSplattingCompressionSpz2
+   * from a byte buffer.
+   *
+   * @param data The buffer from which to read the instance.
+   * @return The result of reading the instance.
+   */
+  CesiumJsonReader::ReadJsonResult<
+      CesiumGltf::ExtensionKhrGaussianSplattingCompressionSpz2>
+  readFromJson(const std::span<const std::byte>& data) const;
+
+  /**
+   * @brief Reads an instance of ExtensionKhrGaussianSplattingCompressionSpz2
+   * from a rapidJson::Value.
+   *
+   * @param value The value from which to read the instance.
+   * @return The result of reading the instance.
+   */
+  CesiumJsonReader::ReadJsonResult<
+      CesiumGltf::ExtensionKhrGaussianSplattingCompressionSpz2>
+  readFromJson(const rapidjson::Value& value) const;
+
+  /**
+   * @brief Reads an array of instances of
+   * ExtensionKhrGaussianSplattingCompressionSpz2 from a rapidJson::Value.
+   *
+   * @param value The value from which to read the array of instances.
+   * @return The result of reading the array of instances.
+   */
+  CesiumJsonReader::ReadJsonResult<
+      std::vector<CesiumGltf::ExtensionKhrGaussianSplattingCompressionSpz2>>
+  readArrayFromJson(const rapidjson::Value& value) const;
+
+private:
+  CesiumJsonReader::JsonReaderOptions _options;
+};
+
+} // namespace CesiumGltfReader