How to display rasters and large point data¶

How-to. Target: a local GeoTIFF as the base imagery layer, and millions of points aggregated into one tile layer instead of thousands of entities.

Both features serve tiles through the local show() server, so they need a running server — they do not work in static HTML export or the notebook widget.

1. Install the extras¶

pip install "cesiumkit[raster]"     # rio-tiler / rasterio / xarray
pip install "cesiumkit[datashader]" # point aggregation; includes raster/GIS deps

2. Add a raster as the base layer¶

add_raster accepts a file path or a georeferenced xarray.DataArray, and sets it as the base imagery layer.

From a fileFrom an xarray.DataArray

import cesiumkit

viewer = cesiumkit.Viewer()
viewer.add_raster("elevation.tif")  # any path rasterio can open
viewer.show()

import xarray as xr

da = xr.open_dataarray("elevation.nc")  # must be georeferenced
viewer = cesiumkit.Viewer()
viewer.add_raster(da)
viewer.show()

Tiles are served from /raster/<id>/{z}/{x}/{y}.png in Web Mercator, matching Cesium's default tiling scheme.

3. Stack layers and tune their opacity¶

The first raster becomes the base layer; each raster you add after that stacks on top of it. Every layer takes its own opacity (0.0 to 1.0) and an optional maximum zoom level:

viewer.add_raster("elevation.tif", opacity=0.6)
viewer.add_raster("landcover.tif", name="landcover", opacity=0.8, maximum_level=16)

Remote WMTS services (many national map portals expose one) stack the same way with add_wmts_layer:

viewer.add_wmts_layer(
    "https://example.com/wmts",
    layer="topo",
    style="default",
    tile_matrix_set="EPSG:3857",
    opacity=0.7,
)

4. Aggregate a huge point set with datashader¶

With aggregation=True (the default) the points are rasterized with datashader, which stays responsive for millions of points. colormap controls the shading ramp, plot_width/plot_height the aggregation canvas:

viewer.add_points(
    gdf,
    colormap=["#000000", "#440154", "#fde725"],
    plot_width=1024,
    plot_height=512,
)

Pass aggregation=False to fall back to one entity per point.

5. Stream a GeoDataFrame as CZML instead¶

For moderate-size vector data you can stream batches to the live viewer without aggregating:

packets = cesiumkit.geodataframe_to_czml_packets(gdf, batch_size=500, color_column="color_hex")
viewer.stream_czml(packets, interval=1.0)

API reference¶

raster ¶

Local raster tile serving for :meth:cesiumkit.Viewer.add_raster.

Dependencies (rio-tiler / rasterio / xarray) live in the [raster] extra and are imported lazily so the core package stays dependency-light. The tile endpoint serves Web Mercator XYZ tiles, matching Cesium's default WebMercatorTilingScheme.

Classes:

Name	Description
`RasterRenderError`	A raster backend failed while rendering a tile.
`RasterSource`	A raster served as Web Mercator tiles by the local viewer server.

Functions:

Name	Description
`aggregate_points_to_raster`	Aggregate a point GeoDataFrame with datashader into a temp GeoTIFF.

RasterRenderError ¶

Bases: RuntimeError

A raster backend failed while rendering a tile.

RasterSource ¶

RasterSource(
    source: str | PathLike[str] | Any,
    *,
    name: str | None = None,
    tile_cache_size: int = 512,
)

A raster served as Web Mercator tiles by the local viewer server.

Accepts either a file path (any format rasterio can open) or an xarray.DataArray with georeferencing. Rendered tiles are cached (LRU) so repeated requests avoid re-rendering.

Methods:

Name	Description
`tile`	Return a PNG tile, or None when out of range. Results are cached.
`clear_cache`	Drop all cached tiles.
`close`	Release cached data and remove a viewer-owned aggregate GeoTIFF.

Attributes:

Name	Type	Description
`cached_tiles`	`int`	Number of tiles currently held in the cache.

cached_tiles `property` ¶

cached_tiles: int

Number of tiles currently held in the cache.

tile ¶

tile(z: int, x: int, y: int) -> bytes | None

Return a PNG tile, or None when out of range. Results are cached.

clear_cache ¶

clear_cache() -> None

Drop all cached tiles.

close ¶

close() -> None

Release cached data and remove a viewer-owned aggregate GeoTIFF.

aggregate_points_to_raster ¶

aggregate_points_to_raster(
    gdf: Any,
    *,
    plot_width: int = 1024,
    plot_height: int = 512,
    colormap: list[str] | None = None,
) -> str

Aggregate a point GeoDataFrame with datashader into a temp GeoTIFF.

Returns the path to a temporary 3-band RGB GeoTIFF in EPSG:4326 covering the GeoDataFrame's bounds, ready for :class:RasterSource. The caller owns that path and must remove it when finished; :meth:Viewer.add_points handles this lifecycle automatically.

Parameters:

Name	Type	Description	Default
`gdf`	`Any`	Point GeoDataFrame to aggregate.	required
`plot_width`	`int`	Aggregation canvas width in pixels.	`1024`
`plot_height`	`int`	Aggregation canvas height in pixels.	`512`
`colormap`	`list[str] \| None`	List of CSS colors for the shading ramp; defaults to a dark-blue-to-red ramp.	`None`