SpatialFrame

SpatialFrame is the entry point for all spatial queries. It owns a materialized Polars DataFrame, the spatial index engine, and cached column metadata. All declarative query planning begins with .lazy().

pycanopy.SpatialFrame

Owns a materialized DataFrame, a spatial index Engine, and cached column stats.

All spatial query planning begins with .lazy(). The DataFrame must be materialized before construction since the Engine and its dataset statistics are built here.

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'

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_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') 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'

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 the index 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 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.

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 the matching rows and a freshly built index.