pypgl 0.1.0

Python bindings for the Pangolin (pgl) exact geometry library

⚠️ Work in Progress: This library is still under construction and contains bugs and missing features. Use in production environments is not recommended.

Pangolin (or pgl) is a C++ library for computational geometry in the plane and pypgl is the official python binding for it. It is designed to be pleasant to use and always exact. It accepts integer and rational coordinates, but rejects floating point numbers.

import pypgl as pgl

p = pgl.Point(1, 0)
q = pgl.Point(4, '15/2')
s = pgl.Segment(p, q)
t = pgl.Segment(0, 8, '7/3', 1)
if s.intersects(t):
    print(s, "intersects", t)
# Output: (1,0)--(4,15/2) intersects (0,8)--(7/3,1)

Shapes and Predicates

Family	Shapes
0-dimensional	Point
1-dimensional	Segment, OrientedSegment, Line, OrientedLine, Ray, Polyline, PolyFunction
2-dimensional	Halfplane, Triangle, Rectangle, Disk, Convex, Polygon

The following predicates are implemented as methods of all shapes.

• contains(Shape) Does it contain the other shape?
• boundaryContains(Shape) Does its boundary contain the other shape?
• interiorContains(Shape) Does it contain the other shape in the interior?
• intersects(Shape) Do the two shapes intersect?
• interiorsIntersect(Shape) Do the interiors of the two shapes intersect?
• separates(Shape) Does one shape cut the other into two (or more) components?
• crosses(Shape) Do both shapes separate each other?

import pypgl as pgl

o = pgl.Point()      # Point (0,0)
d = pgl.Disk(o, 10)  # Disk of radius 10 centered at (0,0)
if d.contains(o):
    print("Disk contains", o)
diam = d.diameter()
if d.contains(diam):
    print("Disk contains the diameter")
if not d.interiorContains(diam):
    print("Disk's interior does not contain the diameter")
# Output:
# Disk contains (0,0)
# Disk contains the diameter
# Disk's interior does not contain the diameter

Other Methods

Several other methods are supported by the shapes.

import pypgl as pgl

c = pgl.Convex([pgl.Point(0, 0), pgl.Point(1, 0), pgl.Point(1, 2), pgl.Point(0, 1)])
s = c.diameter()
print("The diameter of", c,
      "is defined by", s,
      "and has length", s.length())
# Output: The diameter of Convex[(0,0),(1,0),(1,2),(0,1)] is defined by (0,0)--(1,2) and has length 2.23607

Visualization

A Canvas class is provided for SVG visualization:

import pypgl as pgl

canvas = pgl.Canvas()
canvas.draw(pgl.Point(0, 0))

tri = pgl.Triangle(-1, -1, 0, 2, 1, -2)
canvas.stroke("green")
canvas.draw(tri)
canvas.stroke("blue")
canvas.draw(2*tri)
canvas.writeSVG("example2.svg")

Algorithms and Data Structures

PGL includes fundamental algorithms and data structures such as:

• Convex hull: computed with Graham scan.
• Line segment intersection: Bentley-Ottmann sweep line using rational numbers.
• Sort points: by angle or Hilbert order.
• Kd-tree: for points and a generalization for other bounded shapes.
• Triangulation: including Delaunay and constrained Delaunay triangulations for points and polygons.

Installation

pypgl requires Python 3.9 or newer.

From PyPI

pip install pypgl

Pre-built wheels are published for CPython 3.9–3.13 on Linux (manylinux_2_28, x86_64), macOS (Apple Silicon), and Windows, so most users need no compiler.

ℹ️ The first PyPI release is not out yet. Until then, install from source as shown below.

From source

Installing from a source tree or directly from GitHub builds the extension locally and therefore needs a C++20 compiler (GCC 12+, Clang 15+, or, on Windows, the LLVM/ClangCL toolset). The header-only pgl library is fetched automatically by CMake — nothing else to install.

pip install git+https://github.com/gfonsecabr/pypgl.git

Development install

Work on the bindings from a checkout with an editable, in-place build:

git clone https://github.com/gfonsecabr/pypgl.git
cd pypgl
python3 -m venv .venv
.venv/bin/pip install scikit-build-core nanobind pytest
.venv/bin/pip install -e . --no-build-isolation
.venv/bin/python -m pytest tests/ -q

--no-build-isolation lets CMake find the venv's nanobind. Re-run the pip install -e . step after editing any src/*.cpp, since the editable install is what rebuilds the extension. To build against a local pgl checkout instead of the pinned upstream commit:

.venv/bin/pip install -e . --no-build-isolation \
  -C cmake.define.PGL_INCLUDE_DIR=/path/to/pgl/include

More Information

• For a brief description, check the documents at the doc folder.
• For some simple examples, check the files at the examples folder.
• Check the C++ version.