Optional interoperability

Convert dataframe columns, read and write GeoParquet, and display maps.

Related: Interoperability guide

explore

explore(values: Geometry | GeometryArray, *, attributes: Table | Mapping[str, Any] | None = None, **kwargs: Any) -> Map

Build an interactive lonboard map from gometry geometries.

Geometries are handed to lonboard through the Arrow capsule interface. Reprojection, attribute assembly, and widget construction may allocate.

Parameters:

Name	Type	Description	Default
values	Geometry or GeometryArray	Input geometries. A scalar geometry is wrapped as a one-row array.	required
attributes	Arrow table or mapping	Aligned feature columns carried into lonboard.	None
kwargs	mapping	Keyword arguments forwarded to lonboard.viz. The default map keeps points, lines, and polygons visually distinct and makes features inspectable on hover. Pass scatterplot_kwargs, path_kwargs, polygon_kwargs, or map_kwargs to tailor individual settings.	{}

Returns:

Type	Description
Map	Interactive map widget for further customization.

Raises:

Type	Description
ModuleNotFoundError	If lonboard is not installed.
TypeError	If values is not a Geometry or GeometryArray.
GeometryError	If the input is empty, CRS-free, or lacks finite bounds.

from_geopandas

from_geopandas(geoseries_or_gdf: GeoSeries | GeoDataFrame) -> GeometryArray[Geometry | None]

Convert a geopandas GeoSeries or geometry column to a GeometryArray.

Parameters:

Name	Type	Description	Default
geoseries_or_gdf	GeoSeries or GeoDataFrame	geopandas geometry container.	required

Returns:

Type	Description
GeometryArray	Decoded geometries with CRS taken from the geopandas frame metadata.

Raises:

Type	Description
ModuleNotFoundError	If geopandas is not installed.
TypeError	If the input is not a GeoSeries or GeoDataFrame.

from_geoparquet

from_geoparquet(path: str | PathLike[str] | BinaryIO | NativeFile, *, geometry: str | None = None, columns: Iterable[str] | None = None, filters: Any = None, row_groups: Iterable[int] | None = None, bbox: Iterable[FloatScalar] | None = None, filesystem: Any = None, **kwargs: Any) -> tuple[GeometryArray[Geometry | None], Table]

Read a GeoParquet geometry column and its aligned attributes.

Parameters:

Name	Type	Description	Default
path	str, path-like, or binary stream	GeoParquet file or caller-owned binary seekable stream. Text streams are not supported; the reader leaves streams open.	required
geometry	str	Geometry column to decode; the primary column is used by default.	None
columns	iterable of str	Attribute columns to preserve; all non-geometry, non-covering columns by default. Covering columns remain available by explicit selection. One-shot iterables (e.g. generators) are materialized once.	None
filters	object	Predicate filters forwarded to pyarrow.parquet.read_table.	None
row_groups	iterable of int	Row groups to read from a single file, in the requested order, including repetitions. One-shot iterables are materialized once.	None
bbox	iterable of four floats	Closed query rectangle (xmin, ymin, xmax, ymax) in the selected geometry column's CRS. Geographic rectangles may cross the longitude seam. Available covering columns or native statistics prune reads; exact intersection refinement removes bbox-only candidates. Empty and missing geometries do not match.	None
filesystem	object	PyArrow filesystem used to open the source.	None
kwargs	mapping	Curated options forwarded to pyarrow.parquet.read_table.	{}

Returns:

Type	Description
tuple of GeometryArray and pyarrow.Table	Decoded geometry rows and aligned non-geometry attribute columns.

Raises:

Type	Description
ModuleNotFoundError	If pyarrow is not installed.
ParseError	If declarations are malformed or inconsistent, or edge interpolation is incompatible with gometry's straight source-chart edges. Native Parquet GEOMETRY files can be read without GeoParquet metadata. M ordinates require native GEOMETRY / GeoParquet 2.0.

from_pandas

from_pandas(series: Series) -> GeometryArray[Geometry | None]

Import a pandas Series of geometries.

A Series backed by GeometryExtensionArray shares its native storage without copying. An ordinary object-dtype Series imports Geometry objects, WKB buffers, GeoJSON mappings, and __geo_interface__ rows; pandas missing values become missing geometry rows. A Series backed by pd.ArrowDtype imports its GeoArrow extension column through :func:gometry.from_arrow, preserving Arrow chunks and geometry metadata.

Parameters:

Name	Type	Description	Default
series	Series	A geometry Series backed by gometry storage, GeoArrow ArrowDtype, or geometry-like object rows. Use from_geopandas for a GeoSeries so its CRS is retained.	required

Returns:

Type	Description
GeometryArray

Raises:

Type	Description
ModuleNotFoundError	If pandas is not installed.
TypeError	If a row is not a supported geometry representation, or an Arrow-backed Series does not contain a supported GeoArrow geometry column.

from_polars

from_polars(series: Series, *, crs: CrsInput | None = None, epoch: SupportsFloat | SupportsIndex | FloatScalar | ScalarFloatArray | None = None) -> GeometryArray[Geometry | None]

Decode a WKB/EWKB polars Series into a GeometryArray.

Parameters:

Name	Type	Description	Default
series	Series	Binary WKB/EWKB storage (see to_polars).	required
crs	str, int, or CRS input	Restore CRS metadata when the binary values do not embed an EPSG SRID. If EWKB does carry an SRID, this value must agree with it.	None
epoch	numeric scalar or 0-D numeric array	Restore coordinate epoch metadata. The CRS must admit geometry epochs under gometry's frame policy.	None

Returns:

Type	Description
GeometryArray	Decoded geometries with the embedded or explicitly supplied frame.

Raises:

Type	Description
CRSError	If crs is not a valid CRS identifier or disagrees with an embedded EWKB SRID, or if the CRS is absent or does not admit coordinate epochs.
GeometryError	If epoch is not a finite decimal year.