GIS Integration¶

GeoPandas and pandas DataFrame helpers. These functions let you convert a GeoDataFrame or a plain DataFrame into cesiumkit Entity objects with a single call.

Install the optional dependencies with:

pip install cesiumkit[gis]

gis ¶

GeoPandas / pandas integration for cesiumkit.

Convert GeoDataFrame and plain DataFrame objects into lists of Entity in one call. GeoPandas and shapely are optional dependencies — install with pip install cesiumkit[gis].

Functions:

Name	Description
`geodataframe_to_entities`	Convert a `geopandas.GeoDataFrame` to a list of `Entity` objects.
`geodataframe_to_czml_packets`	Yield CZML packet batches from a GeoDataFrame, chunked for streaming.
`dataframe_to_entities`	Convert a plain `pandas.DataFrame` with lon/lat columns to point entities.

geodataframe_to_entities ¶

geodataframe_to_entities(
    gdf: Any,
    *,
    name_column: str | None = None,
    description_column: str | None = None,
    color: Any = None,
    color_column: str | None = None,
    fill_alpha: float = 0.5,
    stroke: Any = None,
    stroke_width: float = 2.0,
    height: float = 0.0,
    height_column: str | None = None,
    extruded_height_column: str | None = None,
    point_pixel_size: float = 8.0,
) -> list[Entity]

Convert a geopandas.GeoDataFrame to a list of Entity objects.

The GeoDataFrame is reprojected to EPSG:4326 (WGS84 lon/lat) if a CRS is set and it is not already 4326.

Parameters:

Name	Type	Description	Default
`gdf`	`Any`	The `geopandas.GeoDataFrame` to convert.	required
`name_column`	`str \| None`	Column to use for each entity's `name`.	`None`
`description_column`	`str \| None`	Column to use for each entity's `description`.	`None`
`color`	`Any`	Default color for all entities. Accepts a `Color`, a CSS/hex string, or a named-color string (e.g. `"RED"`).	`None`
`color_column`	`str \| None`	Column with a per-feature color (same types as `color`). Overrides `color` on a per-row basis.	`None`
`fill_alpha`	`float`	Alpha value for polygon fill (default 0.5).	`0.5`
`stroke`	`Any`	Outline color for polygons / line color for polylines.	`None`
`stroke_width`	`float`	Outline / polyline width in pixels (default 2).	`2.0`
`height`	`float`	Base height for polygons if no column is specified.	`0.0`
`height_column`	`str \| None`	Column with per-row polygon base heights.	`None`
`extruded_height_column`	`str \| None`	Column with per-row polygon extruded heights. Use this to extrude polygons into 3D volumes (e.g. building footprints).	`None`
`point_pixel_size`	`float`	Size in pixels for Point entities.	`8.0`

Returns:

Type	Description
`list[Entity]`	A list of `Entity` objects ready to add to a `Viewer`.

Raises:

Type	Description
`ImportError`	if geopandas is not installed.
`ValueError`	if the GeoDataFrame contains an unsupported geometry type.

geodataframe_to_czml_packets ¶

geodataframe_to_czml_packets(
    gdf: Any, *, batch_size: int = 100, **kwargs: Any
) -> Any

Yield CZML packet batches from a GeoDataFrame, chunked for streaming.

Each yielded batch is a list of CZML packet dicts that can be fed to :meth:cesiumkit.Viewer.update_czml or stream_czml for large datasets. Styling keywords are forwarded to :func:geodataframe_to_entities unchanged.

dataframe_to_entities ¶

dataframe_to_entities(
    df: Any,
    lon_col: str,
    lat_col: str,
    *,
    height_col: str | None = None,
    name_column: str | None = None,
    description_column: str | None = None,
    color: Any = None,
    color_column: str | None = None,
    point_pixel_size: float = 8.0,
) -> list[Entity]

Convert a plain pandas.DataFrame with lon/lat columns to point entities.

This is a convenience wrapper for the most common case — a CSV of points — that avoids requiring GeoPandas. Only produces Point entities.

Parameters:

Name	Type	Description	Default
`df`	`Any`	A `pandas.DataFrame`.	required
`lon_col`	`str`	Name of the longitude column.	required
`lat_col`	`str`	Name of the latitude column.	required
`height_col`	`str \| None`	Optional column for point heights (meters above ellipsoid).	`None`
`name_column`	`str \| None`	Column to use for each entity's `name`.	`None`
`description_column`	`str \| None`	Column to use for each entity's `description`.	`None`
`color`	`Any`	Default color for all points.	`None`
`color_column`	`str \| None`	Column for per-feature color.	`None`
`point_pixel_size`	`float`	Point size in pixels.	`8.0`

Returns:

Type	Description
`list[Entity]`	A list of `Entity` objects with `PointGraphics` attached.