SpatialFrame

SpatialFrame is the entry point for all spatial queries. It can own a materialized Polars DataFrame and spatial engine or defer both behind a Polars LazyFrame. All declarative query planning begins with .lazy().

Lazy sources

Use from_lazy with any Polars lazy source or transformation:

zones = SpatialFrame.from_lazy(
    pl.scan_parquet("s3://bucket/zones/*.parquet").filter(pl.col("state") == "CA"),
    geometry_col="geometry",
    geometry_kind="polygon",
)

For direct Parquet access, scan_parquet forwards scan options to Polars:

zones = SpatialFrame.scan_parquet(
    "s3://bucket/zones/*.parquet",
    geometry_col="geometry",
    geometry_kind="polygon",
    storage_options={"skip_signature": "true"},
)

Point WKB sources use the same APIs:

events = SpatialFrame.scan_parquet(
    "s3://bucket/events/*.parquet",
    geometry_col="geometry",
    geometry_kind="point",
    coordinate_system="geographic",
    ingest_batch_size=32_768,
)

At collection, eligible filters, limits, and projections are pushed into the lazy source before WKB is decoded in ordered batches. Geometry is read for every surviving row but is returned as a column only when selected. Without .select(), all source columns are returned.

The complete native geometry dataset is built before spatial execution. ingest_batch_size controls decode batch size and defaults to 32,768 rows. Blocking operations already present in the supplied LazyFrame may still materialize their input.

Inspecting GeoParquet metadata

scan_parquet() calls infer_geoparquet_geometry() automatically when the geometry column or kind is omitted. The utility is also available directly when you only need to inspect a source:

from pycanopy import infer_geoparquet_geometry

geometry_col, geometry_kind = infer_geoparquet_geometry("zones.parquet")

pycanopy.infer_geoparquet_geometry(source, geometry_col=None, geometry_kind=None, storage_options=None, credential_provider='auto', retries=None)

Resolve a WKB geometry column and kind from GeoParquet metadata.

Explicit geometry values override their metadata counterparts. Dataset sources use the first matching file as their representative footer.

Parameters:

Name	Type	Description	Default
source	ParquetSource	Parquet file, local dataset, cloud URI, or explicit list of paths.	required
geometry_col	str | None	Geometry column override.	None
geometry_kind	GeometryKind | None	Geometry kind override, "point" or "polygon".	None
storage_options	dict[str, str] | None	Cloud connection options for Polars.	None
credential_provider	CredentialProviderFunction | Literal['auto'] | None	Cloud credential provider forwarded to Polars.	'auto'
retries	int | None	Maximum cloud metadata read retries.	None

Returns:

Type	Description
tuple[str, GeometryKind]	The resolved geometry column and kind.

pycanopy.SpatialFrame

Own materialized or deferred spatial data for query planning.

Parameters:

Name	Type	Description	Default
df	DataFrame	Materialized Polars DataFrame.	required
x_col	str	Name of the column holding x (longitude/easting) coordinates.	required
y_col	str	Name of the column holding y (latitude/northing) coordinates.	required
index_mode	str	Index build policy fixed for this frame's engine. "auto" (default) builds only when the cost model beats a scan, "eager" always builds an index, "none" always scans brute-force.	'auto'
coordinate_system	Literal['planar', 'geographic'] | None	How distances are measured. "planar" (default) uses the coordinates' own units, "geographic" reads lon/lat degrees as meters.	None

coordinate_system property

Expose how this frame measures threshold distances.

Returns:

Type	Description
str	Either "planar" or "geographic".

df property

Expose the materialized DataFrame backing this frame.

Returns:

Type	Description
DataFrame	The underlying Polars DataFrame.

engine property

Expose the spatial index engine backing this frame.

Returns:

Type	Description
Engine	The underlying Engine.

x_col property

Expose the x-coordinate column name.

Returns:

Type	Description
str	The name of the x-coordinate column.

y_col property

Expose the y-coordinate column name.

Returns:

Type	Description
str	The name of the y-coordinate column.

convex_hull_area(xs, ys) staticmethod

Compute the area of the convex hull of a standalone point set.

Parameters:

Name	Type	Description	Default
xs		Sequence of x coordinates.	required
ys		Sequence of y coordinates.	required

Returns:

Type	Description
float	The area of the convex hull of the point set.

from_lazy(frame, geometry_col, geometry_kind, index_mode='auto', coordinate_system=None, ingest_batch_size=_DEFAULT_INGEST_BATCH_SIZE, x_col='_x', y_col='_y') classmethod

Construct a deferred SpatialFrame from a Polars LazyFrame.

Parameters:

Name	Type	Description	Default
frame	LazyFrame	Lazy source of spatial rows.	required
geometry_col	str	Name of the Binary WKB geometry column.	required
geometry_kind	Literal['point', 'polygon']	WKB geometry kind, "point" or "polygon".	required
index_mode	str	Index build policy ("eager" / "none" / "auto").	'auto'
coordinate_system	Literal['planar', 'geographic'] | None	Point distance system ("planar" / "geographic").	None
ingest_batch_size	int	Source rows decoded per batch.	_DEFAULT_INGEST_BATCH_SIZE
x_col	str	Internal column name for the extracted x coordinates.	'_x'
y_col	str	Internal column name for the extracted y coordinates.	'_y'

Returns:

Type	Description
SpatialFrame	A SpatialFrame materialized when its query is collected.

from_polygons(df, geometry_col, x_col='_x', y_col='_y', index_mode='auto') classmethod

Construct from a DataFrame containing a shapely/GeoArrow geometry column.

Parameters:

Name	Type	Description	Default
df	DataFrame	Materialized Polars DataFrame with a geometry column.	required
geometry_col	str	Name of the column holding shapely Polygon geometries.	required
x_col	str	Internal column name for extracted x coordinates.	'_x'
y_col	str	Internal column name for extracted y coordinates.	'_y'
index_mode	str	Index build policy ("eager" / "none" / "auto").	'auto'

Returns:

Type	Description
SpatialFrame	SpatialFrame backed by a polygon index.

from_wkb_points(df, wkb_col, x_col='_x', y_col='_y', index_mode='auto', coordinate_system=None) classmethod

Construct a point SpatialFrame from a WKB point column of df.

The WKB points are decoded (vectorised for standard 2D LE points) and appended as x_col / y_col before the index is built.

Parameters:

Name	Type	Description	Default
df	DataFrame	Materialized Polars DataFrame with a WKB point column.	required
wkb_col	str	Name of the Binary column holding WKB point geometries.	required
x_col	str	Internal column name for the extracted x coordinates.	'_x'
y_col	str	Internal column name for the extracted y coordinates.	'_y'
index_mode	str	Index build policy ("eager" / "none" / "auto").	'auto'
coordinate_system	Literal['planar', 'geographic'] | None	How distances are measured ("planar" / "geographic").	None

Returns:

Type	Description
SpatialFrame	SpatialFrame backed by a point index.

from_wkb_polygons(df, wkb_col, x_col='_x', y_col='_y', index_mode='auto') classmethod

Construct a polygon SpatialFrame from a WKB polygon column of df.

The WKB Polygon / MultiPolygon bytes are decoded directly in Rust, and the raw WKB column is dropped from the retained DataFrame once native geometry is built.

Parameters:

Name	Type	Description	Default
df	DataFrame	Materialized Polars DataFrame with a WKB polygon column.	required
wkb_col	str	Name of the Binary column holding WKB polygon geometries.	required
x_col	str	Internal column name placeholder (unused for polygon frames).	'_x'
y_col	str	Internal column name placeholder (unused for polygon frames).	'_y'
index_mode	str	Index build policy ("eager" / "none" / "auto").	'auto'

Returns:

Type	Description
SpatialFrame	SpatialFrame backed by a polygon index.

intersects_pairs(key_col=None)

Return intersecting polygon pairs (i < j) with overlap area and IoU (polygon datasets).

Parameters:

Name	Type	Description	Default
key_col	str | None	Optional column name whose values replace the positional left/right indices. When provided, output columns are named {key_col}_1 and {key_col}_2, and each pair is canonicalized so the smaller key value appears in _1.	None

Returns:

Type	Description
DataFrame	DataFrame with columns left/right (or key_1/key_2 if key_col given),
DataFrame	area_left, area_right, overlap_area, iou. Empty with correct schema when none intersect.

lazy()

Start a declarative spatial query plan over this frame.

Returns:

Type	Description
SpatialLazyFrame	A SpatialLazyFrame for declarative plan construction.

points_within_distance_of_polygon(polygon, distance)

Return the rows whose point lies within distance of a polygon boundary (zero inside).

Parameters:

Name	Type	Description	Default
polygon		A single shapely Polygon (interior holes supported).	required
distance	float	Maximum Euclidean point-to-polygon distance for a match.	required

Returns:

Type	Description
DataFrame	The subset of this frame's DataFrame matching the distance predicate.

polygon_areas()

Append an unsigned 'area' column to this frame's DataFrame (polygon datasets).

Returns:

Type	Description
DataFrame	The frame's DataFrame with an appended unsigned 'area' column.

radius_query(cx, cy, distance)

Return the rows whose point lies within distance of the center (cx, cy).

Parameters:

Name	Type	Description	Default
cx	float	Center x coordinate.	required
cy	float	Center y coordinate.	required
distance	float	Maximum Euclidean distance for a match.	required

Returns:

Type	Description
DataFrame	The subset of this frame's DataFrame within the radius.

range_filter(min_x, min_y, max_x, max_y)

Return a new SpatialFrame containing only geometries that intersect the bounding box.

Parameters:

Name	Type	Description	Default
min_x	float	Left edge of the query rectangle.	required
min_y	float	Bottom edge of the query rectangle.	required
max_x	float	Right edge of the query rectangle.	required
max_y	float	Top edge of the query rectangle.	required

Returns:

Type	Description
SpatialFrame	New SpatialFrame with compact matching geometry. Its index builds on demand
SpatialFrame	according to the inherited index policy.

scan_parquet(source, geometry_col=None, geometry_kind=None, index_mode='auto', storage_options=None, coordinate_system=None, ingest_batch_size=_DEFAULT_INGEST_BATCH_SIZE, x_col='_x', y_col='_y', **scan_options) classmethod

Construct a deferred SpatialFrame from Parquet.

Parameters:

Name	Type	Description	Default
source	str | Path | list[str] | list[Path]	Parquet path, glob, cloud URI, or list of paths.	required
geometry_col	str | None	Name of the Binary WKB geometry column. Inferred from GeoParquet metadata when omitted.	None
geometry_kind	Literal['point', 'polygon'] | None	WKB geometry kind, "point" or "polygon". Inferred from GeoParquet metadata when omitted.	None
index_mode	str	Index build policy ("eager" / "none" / "auto").	'auto'
storage_options	dict[str, str] | None	Cloud connection options for Polars.	None
coordinate_system	Literal['planar', 'geographic'] | None	Point distance system ("planar" / "geographic").	None
ingest_batch_size	int	Source rows decoded per batch.	_DEFAULT_INGEST_BATCH_SIZE
x_col	str	Internal column name for the extracted x coordinates.	'_x'
y_col	str	Internal column name for the extracted y coordinates.	'_y'
**scan_options	object	Options forwarded to polars.scan_parquet.	{}

Returns:

Type	Description
SpatialFrame	A SpatialFrame materialized when its query is collected.