Viewer¶
The main entry point for building CesiumJS visualizations.
viewer
¶
The main Viewer class — primary entry point for cesiumkit.
Viewer
¶
The main cesiumkit object. Corresponds to Cesium.Viewer.
This is the primary entry point for building CesiumJS visualizations. Add entities, data sources, configure the camera, and render to HTML.
entity_count
property
¶
Number of entities currently in the viewer.
selected_entity
property
¶
Return the selected local entity, or None if it is not local.
add_entity(entity=None, **kwargs)
¶
Add an entity. Can pass an Entity instance or keyword args.
remove_entity(entity)
¶
Remove an entity from the viewer.
Returns True if the entity was found and removed.
remove_entity_by_id(entity_id)
¶
Remove an entity by its ID.
Returns True if the entity was found and removed.
clear_entities()
¶
Remove all entities from the viewer.
get_entity(entity_id)
¶
Get an entity by its ID, or None if not found.
add_geodataframe(gdf, **options)
¶
Add all features from a geopandas.GeoDataFrame to this Viewer.
This is a one-line shortcut for the most common geospatial workflow:
load a GeoDataFrame, drop it on the globe. The GeoDataFrame is
auto-reprojected to WGS84 (EPSG:4326) if needed. All keyword arguments
are forwarded to cesiumkit.gis.geodataframe_to_entities.
Returns the list of created entities so they can be further customized.
add_dataframe(df, lon_col, lat_col, **options)
¶
Add point entities from a plain pandas.DataFrame with lon/lat columns.
Shortcut for cesiumkit.gis.dataframe_to_entities that also attaches
each entity to the viewer. Returns the list of created entities.
add_data_source(data_source)
¶
Add a data source.
load_czml(url=None, data=None)
¶
Load CZML data.
load_geojson(url=None, data=None, **kwargs)
¶
Load GeoJSON data.
load_kml(url='', **kwargs)
¶
Load KML/KMZ data.
add_tileset(url=None, ion_asset_id=None, **kwargs)
¶
Add a 3D Tiles tileset.
add_primitive(primitive)
¶
Add a scene primitive such as a particle system.
add_particle_system(particle_system=None, **kwargs)
¶
Add a :class:cesiumkit.ParticleSystem scene primitive.
on(event_type, handler)
¶
Register a screen space event handler.
on_click(callback)
¶
Register a Python callback for left-click events on entities.
The callback receives the public Cesium entity ID, or None when
the click did not hit an entity. The bridge works when registered
before or after :meth:show starts.
wait_for_click(timeout=30.0)
¶
Wait for the next left click and return its entity ID, if any.
Raises :class:TimeoutError if no click arrives within timeout.
Pass None to wait indefinitely.
add_script(js_code)
¶
Add custom JavaScript code to be executed after viewer setup.
fly_to(destination, **kwargs)
¶
Fly the camera to a destination.
set_view(destination, orientation=None)
¶
Set the camera view immediately.
look_at(target, offset)
¶
Point the camera at a target.
set_time(iso_string)
¶
Jump the timeline to a specific ISO 8601 epoch and update the widget.
Example: viewer.set_time("2024-03-15T03:00:00Z")
animate(on=True)
¶
Start or stop clock playback.
Example: viewer.animate(on=False) to pause.
set_multiplier(multiplier)
¶
Change the clock playback speed.
Example: viewer.set_multiplier(3600) for 1 hour per second.
get_current_time(*, timeout=10.0)
¶
Return the live viewer clock as an ISO 8601 string.
screenshot_base64(*, timeout=10.0)
¶
Return a PNG screenshot of the live viewer as base64 text.
screenshot(path, *, timeout=10.0)
¶
Save a PNG screenshot of the live viewer.
canvas_to_image(*, timeout=10.0)
¶
Return a screenshot as a detached Pillow image.
Install the optional images extra to use this method.
select_entity(entity_id)
¶
Select a viewer entity by ID.
deselect()
¶
Clear the live viewer selection.
pick(position, *, timeout=10.0)
¶
Return the local entity at a screen position.
drill_pick(position, *, timeout=10.0)
¶
Return all local entities at a screen position.
update_czml(source)
¶
Replace the first live CZML data source from a URL or CZML packets.
update_geojson(source)
¶
Replace the first live GeoJSON data source from a URL or mapping.
poll_czml(url, *, interval=5.0)
¶
Refresh CZML from url in the browser at a fixed interval.
Returns an identifier that can be passed to :meth:stop_polling.
stop_polling(poller_id)
¶
Stop a browser-side data-source poller.
stream_czml(packets, *, interval=1.0)
¶
Consume CZML packet batches in a daemon thread and queue live updates.
to_html()
¶
Render the complete standalone HTML document string.
save(path)
¶
Save to an HTML file.
show(port=0, open_browser=True)
¶
Launch a local HTTP server and open the visualization in a browser.
Cesium requires HTTP (not file://) due to web worker CORS restrictions.
The server runs until interrupted. Call show() from a background
thread when other Python code needs to control the live viewer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
port
|
int
|
Port to serve on. 0 = auto-pick a free port. |
0
|
open_browser
|
bool
|
Whether to automatically open the browser. |
True
|
show_in_browser()
¶
Alias for show(). Opens visualization via local HTTP server.
to_czml()
¶
Export all entities as CZML JSON.
to_czml_string(indent=2)
¶
Export CZML as formatted JSON string.
save_czml(path)
¶
Save CZML to a .czml file.
Runtime clock control¶
When a viewer is being served with show(), Python can update and read its
live Cesium clock:
viewer.set_time("2024-03-15T03:00:00Z")
viewer.animate(on=True)
viewer.set_multiplier(60)
current_time = viewer.get_current_time()
show() blocks while serving. Run it in a background thread when the same
Python process needs to issue runtime commands.
Live data sources¶
CZML and GeoJSON sources can be replaced without rebuilding the viewer. Values may be URLs or in-memory JSON-compatible data:
viewer.update_czml([{"id": "document", "version": "1.0"}, packet])
viewer.update_geojson({"type": "FeatureCollection", "features": []})
poller = viewer.poll_czml("https://example.com/live.czml", interval=5)
viewer.stop_polling(poller)
For Python-produced updates, stream_czml() consumes an iterable of CZML
packet batches in a daemon thread.
Runtime selection and picking¶
Selection commands operate on entities already added to the viewer. Picking
returns the corresponding local Python Entity when its ID is known:
viewer.select_entity("sat-1")
selected = viewer.selected_entity
picked = viewer.pick(cesiumkit.Cartesian2(x=100, y=200))
all_picked = viewer.drill_pick(cesiumkit.Cartesian2(x=100, y=200))
viewer.deselect()
Python click events¶
Register callbacks before or after show() starts, or synchronously wait for
the next click. A click on an entity returns its public ID; a click on empty
space returns None:
viewer.on_click(lambda entity_id: print("clicked", entity_id))
# Run viewer.show() in another thread, then:
entity_id = viewer.wait_for_click(timeout=30)
wait_for_click() raises TimeoutError when no click arrives before the
timeout. Callback exceptions are logged and do not prevent other callbacks
from running.
Screenshots¶
Capture the live canvas as a file, base64 text, or a Pillow image: