Raster overlays and clipping

Add overlay components on the same entity as the tileset (or route them through material slots / layer keys explicitly). Overlays refine with their own SSE budget, independently of geometry tiles.

Shared overlay options

Every overlay type embeds CesiumRasterOverlayOptions:

Field	Default	Purpose
Maximum screen space error	`2.0`	Overlay LOD (usually tighter than geometry)
Maximum texture size	`2048`	Max texel edge; larger tiles downsample
Maximum simultaneous tile loads	`20`	Concurrent raster loads
Sub-tile cache bytes	16 MB	Cache of unattached sub-tiles
Show credits on screen	off	Force this overlay’s attribution on screen
Material slot	`0`	Slot `0`–`3` on `CesiumTileDefault`
Material layer key	empty	Named overlay group; falls back to numeric slot
Filter	Trilinear	Sampler filter (Clamp addressing)
Use mipmaps	on	Off saves ~33% memory but can shimmer

On the StandardPBR fallback only slots 0 and 1 render. Polygon clip overlays hide the material slot field (they always use the dedicated clip channel).

Overlay types

Component	Typical source	Key fields
Cesium Ion Raster Overlay	ion imagery	Asset ID (default `0` = unset; `2` Bing Aerial, `3` with labels), token, server asset, asset options JSON
Bing Maps Raster Overlay	Bing API key	Key, style (`Aerial`, `RoadOnDemand`, …), culture, base URL
TMS Raster Overlay	Tile Map Service / gdal2tiles	URL (supports `file:///`), file extension, optional zoom range, headers
WMS Raster Overlay	OGC WMS	Base URL, layers, version (`1.3.0`), format, tile size, zoom, headers
WMTS Raster Overlay	OGC WMTS	Base URL / REST template, layer, style, format, TileMatrixSet ID/labels/prefix, projection, tiling scheme, zoom
URL Template Raster Overlay	XYZ / templated CDN	`{x}/{y}/{z}` (also reverse / projected placeholders), projection, tiling scheme, zoom, headers
Google Map Tiles Raster Overlay	Google API	API key, map type, language / region, scale, layers, styles JSON
Azure Maps Raster Overlay	Azure subscription	Subscription key, tileset preset
GeoJSON Raster Overlay	URL / file / ion / document	Source enum, style (line / fill / point), mip levels, headers
Vector Tiles Raster Overlay	URL / ion	Endpoint + vector style
Polygon Raster Overlay	Cartographic polygons	Polygon entity IDs, invert selection, exclude selected tiles
Debug Colorize Tiles	none	Random solid colors for LOD debug

Ion overlay note

Fresh Ion Raster Overlay components default to asset ID 0 and stream nothing until you pick an ID. Common imagery IDs: 2 (Bing Aerial via ion), 3 (with labels)—subscription-dependent.

GeoJSON / vector styling (essentials)

Default style: 1 px white lines, filled opaque-white polygons without outline, 1 px filled points. Per-feature style overrides are available through the GeoJSON object model bus when using CesiumGeoJsonDocumentComponent. Mip levels (0–8) reduces thin-line aliasing at extra memory cost.

Polygon clipping workflow

Author one or more entities with CesiumCartographicPolygonComponent (vertices in LLH). Editor Component Mode supports viewport vertex edit (select / drag / insert / delete).
On the tileset entity, add Polygon Raster Overlay.
List the polygon entity IDs.
Tune:

Field	Default	Meaning
Invert selection	off	Off = clip inside polygons; on = clip outside
Exclude selected tiles	on	Skip loading tiles entirely inside (or outside when inverted) via TileExcluder

Custom C++ excluders can subclass CesiumTileExcluderComponentBase and implement ShouldExcludeTileEx on CesiumTileExcluderBus (tile handle + geometric error).

Material routing tips

Prefer CesiumTileDefault-based materials if you need overlays, clipping, or water mask.
Use Material layer key when a custom material declares named overlay groups (cesiumOverlay<Key> / Overlay<N> aliases).
Call RefreshOverlays on the tileset after programmatic overlay changes.

Overlay load failures surface on tileset notification buses (OnRasterOverlayLoadFailure). GeoJSON overlays also emit OnGeoJsonRasterOverlayDocumentLoaded when the document is ready.

Next steps

Anchors and navigation — fly and place content.
Environment, metadata, and bridges — GeoJSON documents and metadata picking.
Recipes — offline TMS and clip examples.