cesiumkit

Build CesiumJS 3D globe visualizations entirely in Python.

cesiumkit gives you a Pythonic, object-oriented API for CesiumJS -- the leading open-source JavaScript library for 3D globes and maps. Define entities, materials, camera views, terrain, imagery, and time-dynamic animations in pure Python, then render them in the browser with a single call.

import cesiumkit

viewer = cesiumkit.Viewer(title="Hello Globe")
viewer.add_entity(
    cesiumkit.Entity(
        name="New York",
        position=cesiumkit.Cartesian3.from_degrees(-74.006, 40.7128, 400),
        point=cesiumkit.PointGraphics(pixel_size=12, color=cesiumkit.Color.RED),
    )
)
viewer.show()  # opens in your browser

That's it -- 6 lines from Python to a 3D globe in the browser.

Gallery

		More →

Install

pip install cesiumkit

Requires Python 3.10+. No external binary dependencies.

For GeoPandas / Shapely support:

pip install cesiumkit[gis]

Offline use

By default the generated pages load CesiumJS from the CDN. To run fully offline (air-gapped machines, CI, headless servers), vendor the Cesium build once and show() will serve it locally, including the NaturalEarthII fallback imagery:

python scripts/fetch_cesium.py   # downloads the CesiumJS 1.144 release (~120 MB)

The wheel built by the PyPI publish workflow includes the vendored build, so pip install cesiumkit works offline out of the box after that point. Static HTML export and Jupyter embedding still load from the CDN.

Features

GeoPandas / Shapely integration

Drop a GeoDataFrame onto the globe in one call. Auto-reprojects to WGS84, handles mixed geometry types, supports per-feature styling from columns.

import geopandas as gpd
import cesiumkit

gdf = gpd.read_file("countries.geojson")
viewer = cesiumkit.Viewer()
viewer.add_geodataframe(
    gdf,
    name_column="NAME",
    color_column="color_hex",
    extruded_height_column="gdp",  # polygons become 3D prisms
    fill_alpha=0.5,
)
viewer.show()

Shapely geometries are also auto-converted anywhere cesiumkit expects positions — pass a shapely.Point directly to Entity(position=...) or a shapely.Polygon to PolygonGraphics(hierarchy=...).

Entities with rich graphics

Points, billboards, labels, polygons, polylines, boxes, cylinders, ellipses, ellipsoids, corridors, walls, rectangles, paths, polyline volumes, and 3D models -- all as clean Python objects.

viewer.add_entity(
    cesiumkit.Entity(
        name="Headquarters",
        position=cesiumkit.Cartesian3.from_degrees(-77.0369, 38.9072, 0),
        polygon=cesiumkit.PolygonGraphics(
            hierarchy=[
                cesiumkit.Cartesian3.from_degrees(-77.04, 38.91),
                cesiumkit.Cartesian3.from_degrees(-77.03, 38.91),
                cesiumkit.Cartesian3.from_degrees(-77.035, 38.905),
            ],
            material=cesiumkit.Color.CORNFLOWERBLUE.with_alpha(0.6),
            extruded_height=200,
        ),
    )
)

Materials

Solid colors, images, grids, stripes, checkerboards, and polyline-specific materials (glow, arrow, dash, outline).

cesiumkit.StripeMaterial(
    orientation=cesiumkit.StripeOrientation.HORIZONTAL,
    even_color=cesiumkit.Color.WHITE,
    odd_color=cesiumkit.Color.BLUE,
    repeat=5,
)

Time-dynamic animation

Animate entities along paths using sampled position properties with configurable interpolation.

prop = cesiumkit.SampledPositionProperty(interpolation_degree=2)
prop.add_sample(
    cesiumkit.JulianDate.from_iso8601("2024-01-01T00:00:00Z"), cesiumkit.Cartesian3.from_degrees(-122.4, 37.8, 10000)
)
prop.add_sample(
    cesiumkit.JulianDate.from_iso8601("2024-01-01T01:00:00Z"), cesiumkit.Cartesian3.from_degrees(-73.9, 40.7, 10000)
)
entity = cesiumkit.Entity(
    name="Flight", position=prop, path=cesiumkit.PathGraphics(width=2, material=cesiumkit.Color.YELLOW)
)

Live runtime control

Control a running viewer from Python: update the clock and data sources, select or pick entities, receive click callbacks, and capture screenshots.

viewer.set_time("2026-07-14T18:00:00Z")
viewer.set_multiplier(60)
viewer.animate(True)
viewer.on_click(lambda entity_id: print("clicked", entity_id))

See the runtime control guide for the server lifecycle and complete examples.

Data sources

Load GeoJSON, CZML, and KML directly.

viewer.add_data_source(
    cesiumkit.GeoJsonDataSource(
        url="https://example.com/data.geojson",
        stroke=cesiumkit.Color.RED,
        fill=cesiumkit.Color.RED.with_alpha(0.3),
    )
)

Camera control

Fly to locations, set fixed viewpoints, or lock the camera to a target.

viewer.fly_to(
    cesiumkit.Cartesian3.from_degrees(2.2945, 48.8584, 1000),
    orientation=cesiumkit.HeadingPitchRoll(heading=0.3, pitch=-0.4, roll=0),
    duration=3.0,
)

CZML export

Build visualizations in Python and export to CZML for use in any CesiumJS application.

czml_string = viewer.to_czml_string(indent=2)
viewer.save_czml("output.czml")

Imagery and terrain providers

8 imagery providers (Bing, OpenStreetMap, SingleTile, WMTS, WMS, URL template, Ion, TileMapService) and terrain providers for Cesium Ion, Cesium terrain servers, ellipsoid, and encoded WMS/WMTS heightmaps.

Cesium Ion integration

cesiumkit.Ion.set_default_token("your-token-here")
viewer.add_tileset(ion_asset_id=75343)  # e.g., NYC 3D buildings

Interactive events

Add click handlers and custom JavaScript for full interactivity.

viewer.on(
    cesiumkit.ScreenSpaceEventType.LEFT_CLICK,
    cesiumkit.JsCode("""function(click) {
        var picked = viewer.scene.pick(click.position);
        if (Cesium.defined(picked)) viewer.selectedEntity = picked.id;
    }"""),
)

Full feature list

• 17 entity graphics types: point, billboard, label, polygon, polyline, box, cylinder, ellipse, ellipsoid, model, corridor, wall, rectangle, path, plane, polyline volume, tileset
• Particle systems: validated scene primitives for smoke, fire, weather, and engine trails
• 9 material types: solid color, image, grid, stripe, checkerboard, polyline glow/arrow/dash/outline
• 149 named colors with .with_alpha() support
• Time-dynamic properties: SampledPositionProperty, SampledProperty, ConstantProperty, TimeIntervalCollectionProperty, ReferenceProperty, CompositeProperty
• Data sources: GeoJSON, CZML, KML, custom
• Imagery providers: Bing, OSM, SingleTile, WMTS, WMS, URL template, Ion, TMS
• Terrain providers: Ion world terrain, Ion asset, Cesium terrain server, ellipsoid, encoded WMS/WMTS heightmaps
• Camera operations: fly_to, set_view, look_at, fly_to_entities, fly_to_bounding_sphere
• Entity clustering: EntityClusterConfig groups nearby points, billboards, and labels
• 3D Tiles styling: Cesium3DTileStyle per-feature color, show, and point-size conditions
• CZML export: to_czml_string(), save_czml(), CzmlDocument
• Local rasters: add_raster displays GeoTIFF/COG files or xarray DataArrays as Web Mercator tiles
• Large point data: add_points aggregates millions of points via datashader into an imagery layer
• Cesium Ion: token management, 3D Tilesets, terrain
• Scene/Globe configuration: fog, lighting, depth test, atmosphere, post-processing, terrain exaggeration
• Runtime control: clock, live CZML/GeoJSON, selection, picking, screenshots, and Python click callbacks
• Event handling: ScreenSpaceEventHandler with custom JS or Python callbacks
• Custom JavaScript injection: add_script() for arbitrary JS
• Local HTTP server: show() launches a server and opens the browser; serves a bundled offline Cesium build when present
• Jupyter widget: viewer.to_widget() renders in a notebook with live clock control, click events, and screenshots ([widget] extra)
• Headless render testing: cesiumkit.testing renders and screenshots viewers in CI without a display (playwright)
• Works without Ion token: falls back to the bundled NaturalEarthII imagery (offline when vendored)
• Pydantic v2 models: full validation on all inputs
• Type-checked: PEP 561 py.typed marker ships in the wheel; the public API is pyright-clean

API overview

Examples

The examples/ directory contains 11 runnable scripts:

Run any example:

python examples/01_basic_point.py
# Opens in browser -- Ctrl+C to stop the server

Cesium Ion token

Many examples work without a token (using bundled offline imagery). For full functionality (Bing imagery, world terrain, 3D Tilesets), get a free token at cesium.com/ion and set it:

cesiumkit.Ion.set_default_token("your-token-here")

Contributing

See CONTRIBUTING.md for development setup, testing, and how to add new entity types.

License

MIT