Planar and Geographic Distances

PyCanopy supports planar coordinates and WGS84 longitude/latitude. The default planar model uses Euclidean distance in the coordinates' existing units. The geographic model reads coordinates as longitude/latitude degrees and returns haversine distance in meters. PyCanopy does not store CRS metadata or reproject coordinates, so inputs must already use the declared coordinate system.

from pycanopy import SpatialFrame

planar = SpatialFrame(df, x_col="x", y_col="y")
geographic = SpatialFrame(
    df,
    x_col="lon",
    y_col="lat",
    coordinate_system="geographic",
)

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

Declaring geographic coordinates outside the valid longitude/latitude range emits PyCanopyCoordinateWarning.

pycanopy.PyCanopyCoordinateWarning

Bases: UserWarning

Warns that a geographic frame's coordinates are not lon/lat degrees.

Point-to-point distances

Compute one distance for each pair of rows. Inputs may be Polars columns, NumPy arrays, or other numeric sequences of equal length:

from pycanopy import point_distance

distances_m = point_distance(
    df["start_lon"],
    df["start_lat"],
    df["end_lon"],
    df["end_lat"],
    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.

Distance to one fixed point

from pycanopy import distance_to_point

distances_m = distance_to_point(
    df["lon"],
    df["lat"],
    cx=-111.7610,
    cy=34.8697,
    coordinate_system="geographic",
)

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.

Distances between WKB point columns

wkb_point_distance() compares two WKB point columns row by row using planar Euclidean distance:

from pycanopy import wkb_point_distance

distances = wkb_point_distance(df["pickup_wkb"], df["dropoff_wkb"])

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.

Decode WKB points

wkb_points_to_xy() returns contiguous NumPy coordinate arrays that can be used directly or added back to a Polars DataFrame:

import polars as pl
from pycanopy import wkb_points_to_xy

xs, ys = wkb_points_to_xy(df["geometry"])
points = df.with_columns(pl.Series("x", xs), pl.Series("y", ys))

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.