Introducing efficient GeoJson Cutouts

hv_nico · June 16, 2026, 9:52am

Hi all!

It was great meeting many of you at the Cesium Conference last week!

While I was there, I took the opportunity to discuss some specific feature requirements I currently have with @janine.
Thank you again for nudging me in the right direction .

Since returning, I have started exploring the changes needed to introduce the functionality I’m looking for.

Here is my problem:

GeoJSON files can currently be used to clip parts of 3D Tiles using CesiumGeoJsonDocumentRasterOverlay.

However, this only hides the mesh by discarding the texture during rendering. The mesh itself and its textures are still loaded and cached, and if collisions are enabled, it also contributes to physics calculations.

In my specific use case, I use GeoJSON files to cut out the GoogleMaps 3D Tiles to replace with our own mesh for a city. As you can imagine this has tremendous performance implications.

Furthermore, CesiumGeoJsonDocumentRasterOverlay is currently broken on WebGL, as I reported here:

github.com/CesiumGS/cesium-unity

Setting CesiumGeoJsonDocument in WebGL causes MemoryAcessOutOfBounds

opened 04:43PM - 11 May 26 UTC

gojushin

bug needs triage

### What happened? Heya everyone, as the title describes setting `CesiumGeoJso…nDocument` for `CesiumGeoJsonDocumentRasterOverlay.document` during runtime, causes a _Uncaught RuntimeError: memory access out of bounds_ in the Browser for WebGL builds. The same is true when using `CesiumGeoJsonDocumentRasterOverlay.source = CesiumGeoJsonDocumentRasterOverlaySource.FromUrl`. Furthermore, adding a `CesiumGeoJsonDocumentRasterOverlay` Component to the GameObject of the 3D Tileset and setting `CesiumGeoJsonDocumentRasterOverlaySource.FromUrl` in the editor (and leaving away all runtime logic) does **NOT** mitigate this issue. I have tested this behaviour in multiple Browsers in a fresh Unity Project. Here is a minimal script that can be added to an empty GameObject in a minimal scene to trigger the bug: ```C# using CesiumForUnity; using UnityEngine; public class TestScript : MonoBehaviour { private const string ClippingKey = "Clipping"; // Test GeoJson authored in QGis private string geoJson = @" { ""type"": ""FeatureCollection"", ""name"": ""sm_beach_test"", ""crs"": { ""type"": ""name"", ""properties"": { ""name"": ""urn:ogc:def:crs:OGC:1.3:CRS84"" } }, ""features"": [ { ""type"": ""Feature"", ""properties"": { ""id"": null }, ""geometry"": { ""type"": ""MultiPolygon"", ""coordinates"": [ [ [ [ -118.502622339460956, 34.016051530590985 ], [ -118.502846531725368, 34.015883123181212 ], [ -118.503161802097196, 34.016161866299022 ], [ -118.503498090493878, 34.015917966120988 ], [ -118.503168808105499, 34.015662450897175 ], [ -118.503631204650844, 34.015337248590988 ], [ -118.504640069840818, 34.016219937666698 ], [ -118.504275757411122, 34.01648706544637 ], [ -118.504002523088829, 34.016643857447306 ], [ -118.50360318061783, 34.016678700074841 ], [ -118.503308928270769, 34.016655471658069 ], [ -118.502622339460956, 34.016051530590985 ] ] ] ] } }] } "; // A place somehwere at Santa Monica Beach private double lat = 34.0132d; private double lon = -118.5d; private double alt = 25d; public CesiumGeoreference geoRef; public Cesium3DTileset googleTileset; void Start() { geoRef.latitude = lat; geoRef.longitude = lon; geoRef.height = alt; CesiumGeoJsonDocument document = CesiumGeoJsonDocument.Parse(geoJson); CesiumGeoJsonDocumentRasterOverlay overlay = googleTileset.gameObject.AddComponent<CesiumGeoJsonDocumentRasterOverlay>(); overlay.source = CesiumGeoJsonDocumentRasterOverlaySource.FromDocument; overlay.materialKey = ClippingKey; overlay.document = document; // <--- Crash occurs when setting the document! } } ``` ### Environment Cesium for Unity version: 1.23.2 Unity Editor Version: 6000.4.4f1 Operating System: Win11 Browser: Chromium, Firefox ### Reproduction steps 1. Setup Cesium for Unity (for Web) following the [official guideline](https://cesium.com/learn/cesium-unity/ref-doc/supported-platforms.html) 2. Setup a scene with Light, Camera, CesiumGeoReference and Google Photorealistic 3D Tiles. 3. Add the script above as a Component to an empty GameObject and wire up the necessary references in the Editor. 4. Build for WebGL (using _Build & Run_ OR by _building & self-hosting_) 5. Launch Website and witness the crash. ### Supporting evidence _No response_

(I also hope my new class would function as a workaround to this GitHub-Issue~)

Cesium already has a very clever workaround for this, which is used by CesiumPolygonRasterOverlay. In this approach, the polygon becomes a RasterizedPolygonsTileExcluder, causing tiles entirely inside the polygon to not be loaded at all.

To address this, I started implementing a new class that acts as an abstraction of CesiumCartographicPolygon and uses the existing CesiumGeoJsonDocument to enable efficient GeoJSON-based cutouts.

I already have a working prototype up and running and am now looking into a proper implementation for a pull-request.

For this, I have two questions:

Architecture

CesiumCartographicPolygon was clearly not designed to be inherited for such a use case. Furthermore, CesiumPolygonRasterOverlay currently requires objects of this type to function:

github.com/CesiumGS/cesium-unity

Source/Runtime/CesiumPolygonRasterOverlay.cs

main


      
          public List<CesiumCartographicPolygon> polygons

The two options I see are:

1) Inherit from CesiumCartographicPolygon

This would work, but it would also inherit the following requirements:

[RequireComponent(typeof(SplineContainer))]
cesium-unity/Source/Runtime/CesiumCartographicPolygon.cs at main · CesiumGS/cesium-unity · GitHub
[RequireComponent(typeof(CesiumGlobeAnchor))] cesium-unity/Source/Runtime/CesiumCartographicPolygon.cs at main · CesiumGS/cesium-unity · GitHub

These components are entirely unnecessary for the new class using GeoJson as they neither require Splines or a CesiumGlobeAnchor as the GeoJson already contains the required cartographicPoints in the correct format.

2) Create an abstract base class

Both CesiumCartographicPolygon and the new GeoJSON-based class would inherit from this base class.

While this would introduce architectural changes, it should retain backward compatibility as CesiumCartographicPolygon may continue to be used as is.

Support for Holes

Currently, CesiumCartographicPolygon does not support additional rings for holes.

Likewise, the new GeoJSON cutout class would not support holes, since the current cesium-native implementation does not allow for them.

The triangulation library being used, mapbox::earcut:

github.com/CesiumGS/cesium-native

CesiumGeospatial/src/CartographicPolygon.cpp

main


      
          localPolygons.emplace_back(std::move(localPolygon));
          
          indices = mapbox::earcut<uint32_t>(localPolygons);
          return indices;

does however support holes according to their documentation:

github.com/mapbox/earcut.hpp

README.md

master


      
          // Create array
          using Point = std::array<Coord, 2>;
          std::vector<std::vector<Point>> polygon;
          
          // Fill polygon structure with actual data. Any winding order works.
          // The first polyline defines the main polygon.
          polygon.push_back({{100, 0}, {100, 100}, {0, 100}, {0, 0}});
          // Following polylines define holes.
          polygon.push_back({{75, 25}, {75, 75}, {25, 75}, {25, 25}});
          
          // Run tessellation
          // Returns array of indices that refer to the vertices of the input polygon.
          // e.g: the index 6 would refer to {25, 75} in this example.
          // Three subsequent indices form a triangle. Output triangles are clockwise.
          std::vector<N> indices = mapbox::earcut<N>(polygon);

CartographicPolygon.cpp currently only accepts a single std::vector<glm::dvec2>, which prevents support for additional rings.

Extending this to support an arbitrary number of rings would allow polygons to contain any number of holes.

From what I can tell, this would only require overloading the function here:

github.com/CesiumGS/cesium-native

CesiumGeospatial/src/CartographicPolygon.cpp

main


      
          #include <optional>
          #include <utility>
          #include <vector>
          
          using namespace CesiumGeometry;
          
          namespace CesiumGeospatial {
          
          namespace {
          std::vector<uint32_t>
          triangulatePolygon(const std::vector<glm::dvec2>& polygon) {
            std::vector<uint32_t> indices;
            const size_t vertexCount = polygon.size();
          
            if (vertexCount < 3) {
              return indices;
            }
          
            const glm::dvec2& point0 = polygon[0];
          
            using Point = std::array<double, 2>;

to accept a std::vector<std::vector<glm::dvec2>>.

I do wonder whether there are any reasons I’m overlooking as to why this hasn’t been implemented already. I figured it would be worth asking before I attempt the impossible .

I am grateful for all further guidance!

Best,
Nico

hv_nico · June 17, 2026, 9:19am

While I have by now implemented CesiumCartographicGeoJsonPolygon, I am still looking for feedback on the Support for Holes part .

Regardless of the code now already existing, I am still open to changes in methodology if someone has input.

janine · June 17, 2026, 3:34pm

Hi @hv_nico,

It was great to meet you at DevCon! Thanks for posting on the community forum

For reference, I’m sharing the approach we did in Unreal. We added a function that takes an array of points and constructs the spline from it; in this way, you can take the points of a GeoJSON polygon and plug them into the polygon at runtime:

github.com/CesiumGS/cesium-unreal

Set Cartographic Polygon spline points from LLH array (#1786)

main ← points-to-polygon

opened 08:09PM - 14 Jan 26 UTC

david-lively

+81 -4

## Description Adds a Blueprint-callable function, `ACesiumCartographicPolygo…n::SetPolygonPoints` to set polygon spline points based on an array of longitude/latitude/height or ECEF triplets. This can be used to generate polygons from GeoJSON data. <img width="2137" height="892" alt="image" src="https://github.com/user-attachments/assets/886dd7bd-88d0-43cb-9303-8ba7ad0069ab" /> ## Issue number or link https://github.com/CesiumGS/cesium-unreal/issues/1438 ## Author checklist - [ ] I have submitted a [Contributor License Agreement](https://github.com/CesiumGS/community/tree/main/CLAs) (only needed once). - [x] I have done a full self-review of my code. - [x] I have updated `CHANGES.md` with a short summary of my change (for user-facing changes). - [ ] I have added or updated unit tests to ensure consistent code coverage as necessary. - [x] I have updated the documentation as necessary. ## Testing plan Tested by adding the above BluePrint to the 01_CesiumWorld level, using Cesium Ion asset 2533131 . Add a CesiumRasterOverlay to CesiumWorldTerrain, and a CesiumCarographicPolygon. Connect that polygon in the BluePrint. Run the scene, and observe the clipped region. <img width="1504" height="819" alt="image" src="https://github.com/user-attachments/assets/4a838b38-b015-4311-970a-52a8211fc409" />

Now, it would be nice to just set a GeoJSON asset on the polygon so it would automatically assume its shape. My first instinct would be to make the normal CesiumCartographicPolygon consume the GeoJSON and automatically move its spline points based on the input polygon. This would allow for both Editor and Runtime visualization of the polygon, and potentially allows for fine-tune editing if you “save” the shape of the polygon in the Editor. But we’d be open to other ideas, since we haven’t fully tried this out from a UI/UX perspective.

RE: support for holes – that’s a limitation we just haven’t tackled yet, so it’d be great to get a community contribution for a solution! I believe we handle polygon rings when we rasterize GeoJSONs in cesium-native, so we just have to add similar capability in CartographicPolygon.

Excited to see where this goes – keep us updated!

hv_nico · June 17, 2026, 5:02pm

Thanks for your reply, @janine!

While I think the ability to convert to Spline Points is great for further fine-tuning, it also introduces some unnecessary overhead to the application. Also, in my opinion, modifying the loaded GeoJSON somewhat defeats its purpose in a geospatial workflow. At that point, one might as well use Splines directly from the start.

My current implementation focuses heavily on reusing existing logic and providing the same flexibility as similar overlays, allowing them to be used via code, URL, and Ion.

That said, I think it would make a lot of sense to support converting a GeoJSON polygon into a spline-based polygon as an additional workflow.

In my implementation, this should be fairly straightforward, since both the spline-based and GeoJSON-based cutouts now inherit from the same base class .

My plan would be to add a function like:

List<double2> GetPolygonRing()

to expose the polygon ring from the new GeoJSON-based class, and a corresponding

FromRing(List<double2>)

factory/helper on CesiumCartographicPolygon.

With those pieces in place, converting a GeoJSON polygon into a spline-based polygon at runtime becomes as trivial as in Unreal.

On top of that, I could add a button to CesiumPolygonRasterOverlayEditor that creates a new CesiumCartographicPolygon with splines generated from the GeoJSON geometry In-Editor.

Lastly - Editor visualization should not be a problem.

My idea would be to submit an initial PR with this functionality (+any changes to them) first, and then follow up with support for holes in the future ^^.

How does that sound?

Also: Feel free to try the changes I added to get a feel for the UI/UX ^^ I have added a package to my fork here.

janine · June 18, 2026, 4:07pm

Hi @hv_nico,

I appreciate your thoughts on this! Let me take a step back, because I’m worried we’ll go too narrow with implementation details.

Currently, Cesium for Unity provides two existing overlays that can handle polygons:

CesiumPolygonRasterOverlay, which consumes the CesiumCartographicPolygon splines
CesiumGeoJsonRasterOverlay, which rasterizes the GeoJSON and also allows for styling.

The concern with adding a CesiumGeoJsonPolygonRasterOverlay is it would be an ad-hoc in-between of our two existing solutions. And what CesiumGeoJsonPolygonRasterOverlay does is technically already possible with CesiumGeoJsonDocumentRasterOverlay. One could import a GeoJSON doc, style the polygons with a masking color, and modify the tileset material to consume it as a clipping overlay. (Perhaps it would even work if you set the material key to Clipping, though I can’t remember if we allow that in the Unity UI.)

With this in mind, it seems like the major friction would be:

Fine-grained control over which polygons in the GeoJSON document are used for clipping
Requiring less user changes to the material/overlay to enable this workflow

Rather than creating a third, unique overlay, we should be able to expand on CesiumPolygonRasterOverlay/CesiumCartographicPolygon or CesiumGeoJsonRasterOverlay to enable the two points above. Or both! That’s why I proposed making a way to turn a GeoJSON polygon into a CesiumCartographicPolygon, since that connection to the clipping code in the material already exists.

But let me know if I’m missing something here!

hv_nico · June 18, 2026, 4:50pm

You are absolutely right @janine.

However, when using a CesiumGeoJsonDocumentRasterOverlay with “Clipping”, this comes with the huge downside that this is purely styling.

From my original post:

However, this only hides the mesh by discarding the texture during rendering. The mesh itself and its textures are still loaded and cached, and if collisions are enabled, it also contributes to physics calculations.

Since CesiumGeoJsonDocumentRasterOverlay’s use case seem to be purely styling, I don’t know if it would be the correct choice to add RasterizedPolygonsTileExclude to it.

It would be entirely possible to forgo a new class and instead extend CesiumCartographicPolygon.

This, however, carries the drawback that every CesiumCartographicPolygon comes with the overhead of two additional components: SplineContainer and CesiumGlobeAnchor, which are technically unnecessary in this context.

I personally think that the proposed class represents a distinctly different use case, which in my view justifies introducing a new class. Especially since all existing functionality remains as is, and my last proposal would cover ALL of the methodologies we talked about so far.
(Besides choosing, which polygons of the the GeoJSON are used - but since Multipolygons are not currently supported I did not so far concern with that).

In the project I am working on, I operate under extremely tight performance constraints, and squeezing out every last bit of performance is of the highest importance. I may therefore be over-optimizing compared to a more general use case.

If that is the case, I could simply extend CesiumCartographicPolygon and devise another class in my own repository to address the issue I am encountering with this approach locally.

hv_nico · June 26, 2026, 11:12am

@janine Sorry to ping you again. Do you have input towards my last post ?

I would love to open a PR with an implementation once we have agreed on the best methodology !

Topic		Replies	Views
Clipping a geojson file CesiumJS	3	82	October 23, 2025
Cesium Cartographic Polygon Cesium for Unreal	18	8472	February 2, 2024
Google Photorealistic 3D Tiles: jagged Cesium Cartographic Polygon cutout Cesium for Unreal	3	99	December 2, 2024
How to cut a hole in Unity just like "ClippingPlaneCollection" in CesiumJS Cesium for Unity	9	1282	July 24, 2024
Cesiumforue多边形裁剪 Cesium for Unreal	4	120	January 22, 2025

Architecture

1) Inherit from CesiumCartographicPolygon

2) Create an abstract base class

Support for Holes

Related topics