Planar and Geographic Distances

PyCanopy has built-in distance handling for planar coordinates and WGS84 longitude/latitude. The default planar model uses Euclidean distance in the coordinates' existing units. The geographic model interprets coordinates as WGS84 longitude/latitude and uses haversine distance in meters. PyCanopy does not store CRS metadata or reproject coordinates, so inputs must already use the expected coordinate system.

from pycanopy import SpatialFrame

planar = SpatialFrame(df, x_col="x", y_col="y")  # Euclidean, coordinate units
geographic = SpatialFrame(df, x_col="lon", y_col="lat", coordinate_system="geographic")  # haversine meters

Planar or geographic	Planar only
within_distance_of_point	knn
within_distance_join	knn_join
Engine.radius_query	polygon_within_distance_join
point_distance	points_within_distance_of_polygon
distance_to_point	wkb_point_distance

Distance utilities

These module-level helpers compute distances over raw coordinate arrays without a frame. Each accepts anything that coerces to a float64 array, including Polars columns, and runs in one parallel pass. point_distance and distance_to_point take a coordinate_system of "planar" or "geographic".

from pycanopy import point_distance, distance_to_point

d = point_distance(df["lon_a"], df["lat_a"], df["lon_b"], df["lat_b"], coordinate_system="geographic")
d = distance_to_point(df["lon"], df["lat"], -111.7610, 34.8697, coordinate_system="geographic")

pycanopy.point_distance(x1, y1, x2, y2, coordinate_system='planar')

Distance between two point sets row by row, in one parallel pass.

Parameters:

Name	Type	Description	Default
x1		x (or longitude) of the first point set.	required
y1		y (or latitude) of the first point set.	required
x2		x (or longitude) of the second point set.	required
y2		y (or latitude) of the second point set.	required
coordinate_system	str	"planar" (default) Euclidean, or "geographic" for haversine meters.	'planar'

Returns:

Type	Description
ndarray	Float64 numpy array of per-row distances.

pycanopy.distance_to_point(xs, ys, cx, cy, coordinate_system='planar')

Distance from each point to a fixed center, in one parallel pass.

Parameters:

Name	Type	Description	Default
xs		x (or longitude) of each point.	required
ys		y (or latitude) of each point.	required
cx	float	x (or longitude) of the fixed center.	required
cy	float	y (or latitude) of the fixed center.	required
coordinate_system	str	"planar" (default) Euclidean, or "geographic" for haversine meters.	'planar'

Returns:

Type	Description
ndarray	Float64 numpy array of per-point distances to the center.

pycanopy.wkb_point_distance(series_a, series_b)

Compute the Euclidean distance between two WKB point columns in one parallel pass.

Parameters:

Name	Type	Description	Default
series_a		A column of WKB point geometries (first point set).	required
series_b		A column of WKB point geometries (second point set).	required

Returns:

Type	Description
ndarray	Float64 numpy array of per-row distances.

pycanopy.wkb_points_to_xy(points)

Decode a column of WKB point geometries to contiguous float64 x and y arrays.

Standard 2D little-endian points use a vectorised buffer read. Other variants (big-endian, Z/M, nulls) fall back to shapely.

Parameters:

Name	Type	Description	Default
points		A column of WKB point geometries in one of the accepted forms.	required

Returns:

Type	Description
tuple[ndarray, ndarray]	Pair (xs, ys) of contiguous float64 numpy arrays.