Merge pull request #658 from CesiumGS/exclude-tiles-not-in-polygon

Bypass loading of clipped tiles

CHANGES.md

@@ -8,6 +8,7 @@
 * Fixed crash when updating tilesets shader inputs.
 * Fixed crash when setting certain `/Cesium` debug options at runtime.
 * Fixed crash when disabling and re-enabling the extension.
+* Added ability to bypass downloading of tiles clipped by a cartographic polygon raster overlay.
 * Fixed a bug where save stage dialog would appear when reloading Fabric stage at startup.
 * Fixed crash when removing USD prims in certain order.
 * Fixed issue where Cesium ion session would not resume on reload.

exts/cesium.usd.plugins/schemas/cesium_schemas.usda

@@ -525,6 +525,14 @@ class CesiumPolygonRasterOverlayPrim "CesiumPolygonRasterOverlayPrim" (
         doc = "Whether to invert the selection specified by the polygons. If this is true, only the areas outside of the polygons will be rasterized."
     )
 
+    bool cesium:excludeSelectedTiles = true (
+        customData = {
+            string apiName = "excludeSelectedTiles"
+        }
+        displayName = "Exclude Selected Tiles"
+        doc = "Whether tiles that fall entirely within the rasterized selection should be excluded from loading and rendering. For better performance, this should be enabled when this overlay will be used for clipping. But when this overlay is used for other effects, this option should be disabled to avoid missing tiles. Note that if InvertSelection is true, this will cull tiles that are outside of all the polygons. If it is false, this will cull tiles that are completely inside at least one polygon."
+    )
+
     uniform token cesium:overlayRenderMethod = "clip"
 }
 

src/core/include/cesium/omniverse/OmniPolygonRasterOverlay.h

@@ -2,6 +2,7 @@
 
 #include "cesium/omniverse/OmniRasterOverlay.h"
 
+#include <Cesium3DTilesSelection/RasterizedPolygonsTileExcluder.h>
 #include <CesiumRasterOverlays/RasterizedPolygonsOverlay.h>
 #include <CesiumUtility/IntrusivePointer.h>
 
@@ -19,9 +20,12 @@ class OmniPolygonRasterOverlay final : public OmniRasterOverlay {
     [[nodiscard]] std::vector<pxr::SdfPath> getCartographicPolygonPaths() const;
     [[nodiscard]] CesiumRasterOverlays::RasterOverlay* getRasterOverlay() const override;
     [[nodiscard]] bool getInvertSelection() const;
+    [[nodiscard]] bool getExcludeSelectedTiles() const;
+    [[nodiscard]] std::shared_ptr<Cesium3DTilesSelection::RasterizedPolygonsTileExcluder> getExcluder();
     void reload() override;
 
   private:
     CesiumUtility::IntrusivePointer<CesiumRasterOverlays::RasterizedPolygonsOverlay> _pPolygonRasterOverlay;
+    std::shared_ptr<Cesium3DTilesSelection::RasterizedPolygonsTileExcluder> _pExcluder;
 };
 } // namespace cesium::omniverse

src/core/src/OmniPolygonRasterOverlay.cpp

@@ -45,6 +45,17 @@ bool OmniPolygonRasterOverlay::getInvertSelection() const {
     return invertSelection;
 }
 
+bool OmniPolygonRasterOverlay::getExcludeSelectedTiles() const {
+    auto cesiumPolygonRasterOverlay = UsdUtil::getCesiumPolygonRasterOverlay(_pContext->getUsdStage(), _path);
+    bool val;
+    cesiumPolygonRasterOverlay.GetExcludeSelectedTilesAttr().Get(&val);
+    return val;
+}
+
+std::shared_ptr<Cesium3DTilesSelection::RasterizedPolygonsTileExcluder> OmniPolygonRasterOverlay::getExcluder() {
+    return _pExcluder;
+}
+
 void OmniPolygonRasterOverlay::reload() {
     const auto rasterOverlayName = UsdUtil::getName(_pContext->getUsdStage(), _path);
 
@@ -109,6 +120,11 @@ void OmniPolygonRasterOverlay::reload() {
 
     _pPolygonRasterOverlay = new CesiumRasterOverlays::RasterizedPolygonsOverlay(
         rasterOverlayName, polygons, getInvertSelection(), *pEllipsoid, projection, options);
+
+    if (getExcludeSelectedTiles()) {
+        auto pPolygons = _pPolygonRasterOverlay.get();
+        _pExcluder = std::make_shared<Cesium3DTilesSelection::RasterizedPolygonsTileExcluder>(pPolygons);
+    }
 }
 
 } // namespace cesium::omniverse

src/core/src/OmniTileset.cpp

@@ -17,6 +17,7 @@
 #include "cesium/omniverse/OmniGeoreference.h"
 #include "cesium/omniverse/OmniGlobeAnchor.h"
 #include "cesium/omniverse/OmniIonServer.h"
+#include "cesium/omniverse/OmniPolygonRasterOverlay.h"
 #include "cesium/omniverse/OmniRasterOverlay.h"
 #include "cesium/omniverse/TaskProcessor.h"
 #include "cesium/omniverse/TilesetStatistics.h"
@@ -553,6 +554,17 @@ void OmniTileset::reload() {
 
     options.contentOptions.ktx2TranscodeTargets = GltfUtil::getKtx2TranscodeTargets();
 
+    const auto rasterOverlayPaths = getRasterOverlayPaths();
+    for (const auto& rasterOverlayPath : rasterOverlayPaths) {
+        const auto pPolygonRasterOverlay = _pContext->getAssetRegistry().getPolygonRasterOverlay(rasterOverlayPath);
+        if (pPolygonRasterOverlay) {
+            const auto pExcluder = pPolygonRasterOverlay->getExcluder();
+            if (pExcluder) {
+                options.excluders.push_back(pExcluder);
+            }
+        }
+    }
+
     _pViewUpdateResult = nullptr;
     _extentSet = false;
     _activeLoading = false;

src/core/src/UsdNotificationHandler.cpp

@@ -394,7 +394,8 @@ void processCesiumPolygonRasterOverlayChanged(
 
     for (const auto& property : properties) {
         if (property == pxr::CesiumTokens->cesiumCartographicPolygonBinding ||
-            property == pxr::CesiumTokens->cesiumInvertSelection) {
+            property == pxr::CesiumTokens->cesiumInvertSelection ||
+            property == pxr::CesiumTokens->cesiumExcludeSelectedTiles) {
             reload = true;
             updateBindings = true;
         }

src/plugins/CesiumUsdSchemas/generatedSchema.usda.in

@@ -409,6 +409,10 @@ class CesiumPolygonRasterOverlayPrim "CesiumPolygonRasterOverlayPrim" (
         displayName = "Cartographic Polygon Binding"
         doc = "Specifies which Cartographic Polygons to use in the raster overlay"
     )
+    bool cesium:excludeSelectedTiles = 1 (
+        displayName = "Exclude Selected Tiles"
+        doc = "Whether tiles that fall entirely within the rasterized selection should be excluded from loading and rendering. For better performance, this should be enabled when this overlay will be used for clipping. But when this overlay is used for other effects, this option should be disabled to avoid missing tiles. Note that if InvertSelection is true, this will cull tiles that are outside of all the polygons. If it is false, this will cull tiles that are completely inside at least one polygon."
+    )
     bool cesium:invertSelection = 0 (
         displayName = "Invert Selection"
         doc = "Whether to invert the selection specified by the polygons. If this is true, only the areas outside of the polygons will be rasterized."

src/plugins/CesiumUsdSchemas/src/CesiumUsdSchemas/polygonRasterOverlay.cpp

@@ -97,6 +97,23 @@ CesiumPolygonRasterOverlay::CreateInvertSelectionAttr(VtValue const &defaultValu
                        writeSparsely);
 }
 
+UsdAttribute
+CesiumPolygonRasterOverlay::GetExcludeSelectedTilesAttr() const
+{
+    return GetPrim().GetAttribute(CesiumTokens->cesiumExcludeSelectedTiles);
+}
+
+UsdAttribute
+CesiumPolygonRasterOverlay::CreateExcludeSelectedTilesAttr(VtValue const &defaultValue, bool writeSparsely) const
+{
+    return UsdSchemaBase::_CreateAttr(CesiumTokens->cesiumExcludeSelectedTiles,
+                       SdfValueTypeNames->Bool,
+                       /* custom = */ false,
+                       SdfVariabilityVarying,
+                       defaultValue,
+                       writeSparsely);
+}
+
 UsdAttribute
 CesiumPolygonRasterOverlay::GetCesiumOverlayRenderMethodAttr() const
 {
@@ -145,6 +162,7 @@ CesiumPolygonRasterOverlay::GetSchemaAttributeNames(bool includeInherited)
 {
     static TfTokenVector localNames = {
         CesiumTokens->cesiumInvertSelection,
+        CesiumTokens->cesiumExcludeSelectedTiles,
         CesiumTokens->cesiumOverlayRenderMethod,
     };
     static TfTokenVector allNames =

src/plugins/CesiumUsdSchemas/src/CesiumUsdSchemas/polygonRasterOverlay.h

@@ -152,6 +152,28 @@ class CesiumPolygonRasterOverlay : public CesiumRasterOverlay
     CESIUMUSDSCHEMAS_API
     UsdAttribute CreateInvertSelectionAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
 
+public:
+    // --------------------------------------------------------------------- //
+    // EXCLUDESELECTEDTILES 
+    // --------------------------------------------------------------------- //
+    /// Whether tiles that fall entirely within the rasterized selection should be excluded from loading and rendering. For better performance, this should be enabled when this overlay will be used for clipping. But when this overlay is used for other effects, this option should be disabled to avoid missing tiles. Note that if InvertSelection is true, this will cull tiles that are outside of all the polygons. If it is false, this will cull tiles that are completely inside at least one polygon.
+    ///
+    /// | ||
+    /// | -- | -- |
+    /// | Declaration | `bool cesium:excludeSelectedTiles = 1` |
+    /// | C++ Type | bool |
+    /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Bool |
+    CESIUMUSDSCHEMAS_API
+    UsdAttribute GetExcludeSelectedTilesAttr() const;
+
+    /// See GetExcludeSelectedTilesAttr(), and also 
+    /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+    /// If specified, author \p defaultValue as the attribute's default,
+    /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+    /// the default for \p writeSparsely is \c false.
+    CESIUMUSDSCHEMAS_API
+    UsdAttribute CreateExcludeSelectedTilesAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
+
 public:
     // --------------------------------------------------------------------- //
     // CESIUMOVERLAYRENDERMETHOD 

src/plugins/CesiumUsdSchemas/src/CesiumUsdSchemas/tokens.cpp

@@ -29,6 +29,7 @@ CesiumTokensType::CesiumTokensType() :
     cesiumEnableFogCulling("cesium:enableFogCulling", TfToken::Immortal),
     cesiumEnableFrustumCulling("cesium:enableFrustumCulling", TfToken::Immortal),
     cesiumEnforceCulledScreenSpaceError("cesium:enforceCulledScreenSpaceError", TfToken::Immortal),
+    cesiumExcludeSelectedTiles("cesium:excludeSelectedTiles", TfToken::Immortal),
     cesiumForbidHoles("cesium:forbidHoles", TfToken::Immortal),
     cesiumGeoreferenceBinding("cesium:georeferenceBinding", TfToken::Immortal),
     cesiumGeoreferenceOriginHeight("cesium:georeferenceOrigin:height", TfToken::Immortal),
@@ -96,6 +97,7 @@ CesiumTokensType::CesiumTokensType() :
         cesiumEnableFogCulling,
         cesiumEnableFrustumCulling,
         cesiumEnforceCulledScreenSpaceError,
+        cesiumExcludeSelectedTiles,
         cesiumForbidHoles,
         cesiumGeoreferenceBinding,
         cesiumGeoreferenceOriginHeight,

src/plugins/CesiumUsdSchemas/src/CesiumUsdSchemas/tokens.h

@@ -143,6 +143,10 @@ struct CesiumTokensType {
     /// 
     /// CesiumTileset
     const TfToken cesiumEnforceCulledScreenSpaceError;
+    /// \brief "cesium:excludeSelectedTiles"
+    /// 
+    /// CesiumPolygonRasterOverlay
+    const TfToken cesiumExcludeSelectedTiles;
     /// \brief "cesium:forbidHoles"
     /// 
     /// CesiumTileset

src/plugins/CesiumUsdSchemas/src/CesiumUsdSchemas/wrapPolygonRasterOverlay.cpp

@@ -33,6 +33,13 @@ _CreateInvertSelectionAttr(CesiumPolygonRasterOverlay &self,
         UsdPythonToSdfType(defaultVal, SdfValueTypeNames->Bool), writeSparsely);
 }
 
+static UsdAttribute
+_CreateExcludeSelectedTilesAttr(CesiumPolygonRasterOverlay &self,
+                                      object defaultVal, bool writeSparsely) {
+    return self.CreateExcludeSelectedTilesAttr(
+        UsdPythonToSdfType(defaultVal, SdfValueTypeNames->Bool), writeSparsely);
+}
+
 static UsdAttribute
 _CreateCesiumOverlayRenderMethodAttr(CesiumPolygonRasterOverlay &self,
                                       object defaultVal, bool writeSparsely) {
@@ -89,6 +96,13 @@ void wrapCesiumPolygonRasterOverlay()
              (arg("defaultValue")=object(),
               arg("writeSparsely")=false))
 
+        .def("GetExcludeSelectedTilesAttr",
+             &This::GetExcludeSelectedTilesAttr)
+        .def("CreateExcludeSelectedTilesAttr",
+             &_CreateExcludeSelectedTilesAttr,
+             (arg("defaultValue")=object(),
+              arg("writeSparsely")=false))
+
         .def("GetCesiumOverlayRenderMethodAttr",
              &This::GetCesiumOverlayRenderMethodAttr)
         .def("CreateCesiumOverlayRenderMethodAttr",

src/plugins/CesiumUsdSchemas/src/CesiumUsdSchemas/wrapTokens.cpp

@@ -67,6 +67,7 @@ void wrapCesiumTokens()
     _AddToken(cls, "cesiumEnableFogCulling", CesiumTokens->cesiumEnableFogCulling);
     _AddToken(cls, "cesiumEnableFrustumCulling", CesiumTokens->cesiumEnableFrustumCulling);
     _AddToken(cls, "cesiumEnforceCulledScreenSpaceError", CesiumTokens->cesiumEnforceCulledScreenSpaceError);
+    _AddToken(cls, "cesiumExcludeSelectedTiles", CesiumTokens->cesiumExcludeSelectedTiles);
     _AddToken(cls, "cesiumForbidHoles", CesiumTokens->cesiumForbidHoles);
     _AddToken(cls, "cesiumGeoreferenceBinding", CesiumTokens->cesiumGeoreferenceBinding);
     _AddToken(cls, "cesiumGeoreferenceOriginHeight", CesiumTokens->cesiumGeoreferenceOriginHeight);