Source: https://gometry.monicz.dev/api/interop/

# Optional interoperability

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

**Related:** [Interoperability guide](https://gometry.monicz.dev/ecosystem/)

## explore

```python
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

```python
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

```python
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

```python
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

```python
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. |