sparea 0.4.0

Compute the area of spherical polygons on the unit sphere.

sparea: Spherical Polygon Area

Python bindings for sparea_zig, a Zig library for computing the area of spherical polygons.

import sparea as sp

# Octant triangle: equator at lng=0, equator at lng=90°, north pole.
sp.area([
    (0.0,  0.0),
    (0.0, 90.0),
    (90.0, 0.0),
])  # ≈ pi / 2

# Same polygon expressed as unit (x, y, z) vectors.
sp.area([
    (1.0, 0.0, 0.0),
    (0.0, 1.0, 0.0),
    (0.0, 0.0, 1.0),
], geo='vec3')  # ≈ pi / 2

sp.area accepts three keyword arguments:

• geo: input convention.

  • 'latlng' (default) and 'latlng_deg' — each row is (lat, lng) in degrees (matching h3's convention).
  • 'latlng_rad' — each row is (lat, lng) in radians.
  • 'vec3' — each row is a unit (x, y, z).

  The number of input columns must match (2 for the latlng family, 3 for vec3).

• algo: kernel selection. 'auto' (default) dispatches between a cross-product centroid-fan path (for hemisphere-contained polygons) and a per-edge angle formula. 'cross' and 'angle' force the named kernel.

• signed: output sign convention. False (default) folds the result into [0, 4π) — reversing the vertex order yields the complementary region (4π − interior). True returns the raw signed kernel value (positive for CCW-from-outside, negative otherwise).

Cross-check against H3

import sparea as sp
import h3

h = h3.latlng_to_cell(37.7749, -122.4194, 9)
diff = h3.cell_area(h, unit='rads^2') - sp.area(h3.cell_to_boundary(h))

Installing

pip install sparea
# or
uv add sparea

Wheels are published for Python 3.11–3.14 across Linux (x86_64, aarch64, manylinux + musllinux), macOS arm64, and Windows AMD64. No host-level Zig install needed.

To install the unreleased main branch instead, point pip/uv at the git URL:

pip install git+https://github.com/ajfriend/sparea_py.git
uv pip install git+https://github.com/ajfriend/sparea_py.git

That path triggers a source build: the hatchling hook (src/hatch_build.py) pulls the Zig toolchain from the ziglang PyPI wheel, compiles libsparea.{dylib,so,dll}, and bundles it into the wheel before pip installs it. The upstream sparea_zig source is fetched over the network from the URL pinned in src/zig/build.zig.zon.

See dev.md for architecture, layout, and contributor notes.