pypgl 0.1.0__tar.gz

pypgl-0.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,92 @@
+name: Build wheels
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: wheels-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_wheels:
+    name: Wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Native runners only (no emulation/cross): nanobind_add_stub imports the
+        # freshly built _pgl to emit _pgl.pyi, so the build host must run the
+        # target binary. macos-14 = arm64 (Apple Silicon).
+        # macos-13 (x86_64 Intel) is dropped: GitHub is retiring the Intel
+        # runners, so those jobs sit queued for hours and time out. Apple Silicon
+        # is covered by macos-14; we don't ship Intel-mac wheels.
+        # windows-2022 is pinned (not windows-latest) so the "Visual Studio 17
+        # 2022" generator name in [tool.cibuildwheel.windows] stays valid.
+        os: [ubuntu-latest, macos-14, windows-2022]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21
+        # cibuildwheel reads [tool.cibuildwheel] from pyproject.toml.
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: ./dist/*.tar.gz
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    # Dry run: manual "Run workflow" uploads to test.pypi.org for validation.
+    # Uses Trusted Publishing (OIDC) — no API token.
+    if: github.event_name == 'workflow_dispatch'
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish:
+    name: Publish to PyPI
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    # Only on a version tag. Uses PyPI Trusted Publishing (OIDC) — no API token.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

pypgl-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.pgl-ref/
+build/
+*.so
+__pycache__/
+*.egg-info/
+dist/
+.venv/

pypgl-0.1.0/CLAUDE.md

@@ -0,0 +1,169 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project status
+
+**Core shapes done** (milestones 1–2 of [pypgl.md](pypgl.md)): all
+shapes are bound — `Point`, `Segment`, `OrientedSegment`,
+`Line`, `OrientedLine`, `Ray`, `Halfplane`, `Triangle`, `Rectangle`, `Convex`,
+`Disk` — each with the full 7-predicate × 10-shape matrix
+(`PGL_BIND_ALL_PREDICATES` in [src/common.h](src/common.h)), constructors,
+accessors/measures, and typed `intersection` results for the 0D/1D-result pairs.
+The two casters work and the exact round-trip / `optional`→`None` /
+`variant`→concrete mappings are verified by the `tests/` suite.
+
+**Notebook UX done** (milestone 3): `Canvas`
+([src/bind_canvas.cpp](src/bind_canvas.cpp)) is bound — pgl's stream API
+(`canvas << pgl::stroke("red") << shape`) does not map to Python, so each stream
+operation is re-exposed as a method: fluent `scale`/`width`/`height`/`size`/
+`margin`/`pointRadius`/`borders` and the numeric `strokeWidth` configuration;
+fluent `stroke`/`fill`/`fillOpacity`/`strokeOpacity` style commands applied to the
+*current* style (so only shapes drawn afterwards capture it); one `draw(shape)`
+overload per bound shape; and `toSVG()`/`writeSVG(path)`. The fluent self-returns
+use `nb::rv_policy::reference_internal`. `_repr_svg_` is added Python-side in
+[pypgl/__init__.py](pypgl/__init__.py) — on the canvas it returns `toSVG()`, on
+every shape it renders a one-shot `Canvas().draw(self)` — so shapes and canvases
+display inline in Jupyter.
+
+**Type stubs done** (milestone 4): `_pgl.pyi` is generated at build time by
+`nanobind_add_stub` in [CMakeLists.txt](CMakeLists.txt) — from the *bare* `_pgl`
+module, with the Python-layer sugar re-added via
+[src/stubgen_patterns.txt](src/stubgen_patterns.txt) — and shipped next to
+`py.typed` (PEP 561).
+
+**Wheels CI done** (milestone 4): `cibuildwheel` is configured in
+[pyproject.toml](pyproject.toml) and run by
+[.github/workflows/wheels.yml](.github/workflows/wheels.yml) — CPython 3.9–3.13 on
+`manylinux_2_28` (GCC 12 for C++20), macOS arm64+x86_64, and Windows, plus sdist.
+pgl has no native deps, so the build only `FetchContent`s the **pinned** pgl commit
+(kept in lockstep with `.pgl-ref`, since the sdist omits the gitignored
+`.pgl-ref/`). Native-arch only (no QEMU/cross) because `nanobind_add_stub` imports
+the just-built `_pgl` to emit `_pgl.pyi`. A `publish` job (PyPI Trusted Publishing,
+gated on `v*` tags) is wired but not yet enabled on PyPI.
+
+Still to do: broaden `intersection` to 2D∩2D / `Halfplane` (Convex/Polygon
+results), the rest of milestone 4 (confirm the PyPI name + enable Trusted
+Publishing, then tag a release; consider STABLE_ABI to cut the wheel count), and
+the experimental `Polygon`.
+[pypgl.md](pypgl.md) remains the authoritative design contract —
+update it in lockstep if a decision changes; [ROADMAP.md](ROADMAP.md) tracks
+progress.
+
+`Disk` ([src/bind_disk.cpp](src/bind_disk.cpp)) is bound as its own complete
+class — its full predicate matrix against every shape (including itself) plus
+exact `center`/`squaredRadius`/`bbox`/`pointInside`. `area` is irrational (π) so
+it always returns Python `float`; `radius` returns an exact `Fraction` when the
+disk was built from a center and radius (delegating the exact/inexact decision to
+pgl's throwing `radius<ERational>()`) and a `float` otherwise (square root);
+`squaredDistance` to a disk is likewise `float`. `diameter()` is reconstructed as
+an exact `Segment` for center+radius disks (pgl ships only a floating-point one)
+and raises for an irrational radius; `fbox()` is not bound (its double-coordinate
+return type is not registered). Disk's
+*column* is not added to the other shapes' matrices yet (e.g. `triangle.contains(disk)`),
+partly because pgl still lacks `Triangle::contains(Disk)` and
+`Convex::squaredDistance(Disk)`; symmetric relations are reachable from the Disk
+side.
+
+The package directory is [pypgl/](pypgl/) (so `import pypgl` works); the compiled
+extension is `pypgl._pgl`. Binding sources live in [src/](src/).
+
+## What pypgl is
+
+Python bindings for **Pangolin** (`pgl`), a header-only C++20 exact-geometry
+library at `github.com/gfonsecabr/pgl`. The public API mirrors the C++ one:
+`import pypgl` and type/method names stay unchanged. pgl is consumed via CMake
+`FetchContent` (pinned `GIT_TAG`), never vendored or submoduled.
+
+## Load-bearing design decisions
+
+These are the choices that constrain everything else; violating them defeats the
+point of the project:
+
+- **One numeric instantiation only:** `pgl::ERational = pgl::Rational<pgl::BigInt>`.
+  Do **not** bind the `double` / `Rational<int64_t>` family. This is what keeps the
+  binary and API surface bounded. "The number type" / `Num` always means `ERational`.
+- **Exactness is a hard contract.** Coordinates are accepted as `int`, `Fraction`,
+  or `"a/b"` strings. **Reject `float` loudly** with a message pointing at the
+  accepted forms — never silently approximate.
+- **nanobind, not pybind11.** Chosen for small binaries / fast compile because
+  binding a templated header-only library is instantiation-heavy.
+- **Bind concrete shapes, not the `Shape` variant wrapper.** Each shape is its own
+  Python class.
+
+## Architecture
+
+The only hand-written plumbing is two type casters in `src/casters.h`; everything
+else is mechanical `.def(...)`:
+
+1. `pgl::BigInt` ↔ Python `int` — via decimal string round-trip (lossless; uses
+   pgl's existing `operator<<`/`operator>>`). A machine-int fast path is a later
+   optimization, not a correctness requirement.
+2. `pgl::ERational` ↔ Python `fractions.Fraction` — built from `numerator()` /
+   `denominator()` (stored in lowest terms), each term flowing through the BigInt
+   caster so arbitrarily large coordinates round-trip.
+
+What falls out for free from pgl's typed API (built-in nanobind casters):
+`std::optional<T>` → `T`/`None`; `std::variant<Point, Segment, …>` → the concrete
+shape (so `intersection` returns `None` / `Point` / `Segment` with no sentinels);
+`operator<<` → `__repr__`; `operator==`/`<`/`std::hash` → usable in `set`/`dict`.
+
+**Layering:** the compiled `_pgl` extension stays minimal (just `.def`s). All
+Pythonic sugar lives in `pgl/__init__.py`: vertex iteration, `point in shape` →
+`shape.contains(point)` (point-in-shape only — keep shape-vs-shape as explicit
+methods), pickling, and `_repr_svg_` for inline Jupyter rendering via `Canvas`.
+
+**Translation units:** one `bind_*.cpp` per shape group (point, segment, lines,
+polygons, canvas) so heavy template instantiation compiles in parallel and objects
+stay small. A `PGL_BIND_PREDICATES(cls, OtherTypes...)` macro in `src/common.h`
+keeps the seven uniform predicates (`contains`, `boundaryContains`,
+`interiorContains`, `intersects`, `interiorsIntersect`, `separates`, `crosses`)
+consistent across classes; each predicate is overloaded per accepted shape type.
+
+`Disk` and `Polygon` are **experimental** — keep them gated until their C++
+predicates settle, so the public API doesn't churn.
+
+## Build & test
+
+Build backend is `scikit-build-core` (PEP 517); `nanobind` is a build dependency
+found via `python -m nanobind --cmake_dir` (not FetchContent). Development uses a
+venv:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install scikit-build-core nanobind pytest
+.venv/bin/pip install -e . --no-build-isolation   # --no-build-isolation so CMake finds the venv's nanobind
+.venv/bin/python -m pytest tests/ -q
+```
+
+Re-run the `pip install -e .` line after editing any `src/*.cpp` — the editable
+install rebuilds the extension; importing alone does not.
+
+**pgl headers.** pgl is header-only and (currently) ships no CMake target or
+release tags, so we do **not** `FetchContent_MakeAvailable` a `pgl::pgl` target.
+[CMakeLists.txt](CMakeLists.txt) resolves `PGL_INCLUDE_DIR` in this order: an
+explicit `-DPGL_INCLUDE_DIR=…`, then an in-tree `.pgl-ref/` checkout (the offline
+default — a gitignored `git clone` of github.com/gfonsecabr/pgl), then FetchContent
+from GitHub. `.pgl-ref/` is the local copy of the real pgl API; **read it to get
+exact signatures** rather than trusting the design doc's header paths (which differ,
+e.g. real headers are `include/shape/point.hpp`, `include/implementation/io.hpp`).
+
+Co-develop against another pgl checkout:
+`pip install -e . --no-build-isolation -C cmake.define.PGL_INCLUDE_DIR=/path/to/pgl/include`
+
+Wheels (later milestone): `cibuildwheel` in GitHub Actions; ship generated
+`_pgl.pyi` stubs + `py.typed`.
+
+## Gotchas learned while binding
+
+- **pgl's `BigInt::operator>>` reads a whole whitespace-delimited token**, so it
+  cannot drive `Rational::operator>>`'s `"a/b"` parse (the `/` gets swallowed). The
+  `ERational` caster therefore parses string coordinates through Python's
+  `fractions.Fraction` instead, then uses the uniform numerator/denominator path.
+- **Predicate/intersection methods are templated** on the result/other-shape type
+  with defaults (`ResultNumber = NumberType = ERational`). Bind them via lambdas
+  (`[](const Self&, const Other&){ return self.method(other); }`) so the default
+  instantiation is chosen; don't try to take their address.
+- The `in`/iteration sugar is added Python-side in [pypgl/__init__.py](pypgl/__init__.py)
+  by assigning to the nanobind classes (`Point.__contains__ = …`), which nanobind
+  permits.

pypgl-0.1.0/CMakeLists.txt

@@ -0,0 +1,88 @@
+cmake_minimum_required(VERSION 3.15...3.30)
+project(pypgl LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "" FORCE)
+endif()
+
+find_package(Python 3.9 COMPONENTS Interpreter Development.Module REQUIRED)
+
+# Locate the installed nanobind (a build dependency) and load its CMake config.
+execute_process(
+  COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+  OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT)
+find_package(nanobind CONFIG REQUIRED)
+
+# Locate pgl's header-only include/ directory. Resolution order:
+#   1. an explicit -DPGL_INCLUDE_DIR=... (co-development against a local checkout)
+#   2. an in-tree .pgl-ref/ checkout (offline default)
+#   3. CMake FetchContent from GitHub (pinned to a tag once pgl publishes them)
+set(PGL_INCLUDE_DIR "" CACHE PATH "Path to pgl's include/ directory")
+if(NOT PGL_INCLUDE_DIR)
+  if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/.pgl-ref/include/pgl.hpp")
+    set(PGL_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/.pgl-ref/include")
+  else()
+    include(FetchContent)
+    # Pinned to the exact commit the in-tree .pgl-ref/ dev checkout is at, so CI
+    # wheel builds (which don't ship the gitignored .pgl-ref/) are reproducible
+    # and match local development. Bump in lockstep with .pgl-ref. Switch to a
+    # release tag once pgl publishes them.
+    FetchContent_Declare(pgl
+      GIT_REPOSITORY https://github.com/gfonsecabr/pgl
+      GIT_TAG        110300042bf65463aca25a559b2f47d65323b225)
+    FetchContent_MakeAvailable(pgl)
+    set(PGL_INCLUDE_DIR "${pgl_SOURCE_DIR}/include")
+  endif()
+endif()
+message(STATUS "pypgl: using pgl headers from ${PGL_INCLUDE_DIR}")
+
+nanobind_add_module(_pgl
+  NB_STATIC
+  src/module.cpp
+  src/bind_point.cpp
+  src/bind_segment.cpp
+  src/bind_lines.cpp
+  src/bind_polygons.cpp
+  src/bind_disk.cpp
+  src/bind_canvas.cpp)
+
+target_include_directories(_pgl PRIVATE "${PGL_INCLUDE_DIR}" src)
+
+# clang-cl (the Windows toolset — see pyproject's [tool.cibuildwheel.windows])
+# emits calls to compiler-rt's 128-bit-integer builtins (__udivti3, __modti3,
+# __divti3, __floattidf, __fixdfti) for the __int128 path pgl takes, but lld-link
+# does not auto-link the builtins archive the way GCC/Clang do on Unix. Link it
+# explicitly, located relative to the compiler.
+if(MSVC AND CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  get_filename_component(_clang_bin_dir "${CMAKE_CXX_COMPILER}" DIRECTORY)
+  file(GLOB _clang_rt_builtins
+    "${_clang_bin_dir}/../lib/clang/*/lib/windows/clang_rt.builtins-x86_64.lib")
+  if(_clang_rt_builtins)
+    list(GET _clang_rt_builtins -1 _clang_rt_builtins)  # highest clang version
+    target_link_libraries(_pgl PRIVATE "${_clang_rt_builtins}")
+    message(STATUS "pypgl: linking compiler-rt builtins ${_clang_rt_builtins}")
+  else()
+    message(WARNING "pypgl: clang_rt.builtins-x86_64.lib not found near ${_clang_bin_dir}")
+  endif()
+endif()
+
+install(TARGETS _pgl LIBRARY DESTINATION pypgl)
+
+# Generate a type stub (_pgl.pyi) for the compiled module and ship it next to
+# py.typed (PEP 561) so type checkers and IDEs see the full exact-geometry API.
+# The stub is built from the bare `_pgl` module (importing it standalone, before
+# pypgl/__init__.py runs); src/stubgen_patterns.txt re-adds the Python-layer
+# sugar that __init__.py applies at import time (len/indexing/iteration over a
+# shape's defining points and `point in shape`).
+nanobind_add_stub(_pgl_stub
+  MODULE _pgl
+  OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/_pgl.pyi"
+  PYTHON_PATH "$<TARGET_FILE_DIR:_pgl>"
+  PATTERN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/src/stubgen_patterns.txt"
+  DEPENDS _pgl)
+
+install(FILES "${CMAKE_CURRENT_BINARY_DIR}/_pgl.pyi" DESTINATION pypgl)

pypgl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guilherme D. da Fonseca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pypgl-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.1
+Name: pypgl
+Version: 0.1.0
+Summary: Python bindings for the Pangolin (pgl) exact geometry library
+Author: Guilherme D. da Fonseca
+License: MIT License
+         
+         Copyright (c) 2026 Guilherme D. da Fonseca
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+         
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/gfonsecabr/pypgl
+Project-URL: Repository, https://github.com/gfonsecabr/pypgl
+Project-URL: pgl (C++ library), https://github.com/gfonsecabr/pgl
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<img align="left" src="https://raw.githubusercontent.com/gfonsecabr/pypgl/main/doc/figures/logo.png" width="23%"/>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gfonsecabr/pypgl/main/doc/figures/logotextdark.svg"/>
+  <img alt="Pangolin: Plane Geometry Library" src="https://raw.githubusercontent.com/gfonsecabr/pypgl/main/doc/figures/logotext.svg" width="65%"/>
+</picture>
+
+<!-- [![Tests](https://github.com/gfonsecabr/pgl/actions/workflows/tests.yml/badge.svg)](https://github.com/gfonsecabr/pgl/actions/workflows/tests.yml)
+[![Standard](https://img.shields.io/badge/C%2B%2B-20/23/26-rgb(10,66,158).svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) -->
+[![License](https://img.shields.io/badge/license-MIT-rgb(216,134,42).svg)](https://opensource.org/licenses/MIT)
+<!-- [![Benchmarks](https://img.shields.io/badge/benchmarks-online-rgb(21,153,135).svg)](https://gfonsecabr.github.io/pgl/benchmarks/index.html) -->
+
+> ⚠️ **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.
+
+```python
+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`](doc/shapes.md#point) |
+| 1-dimensional | [`Segment`](doc/shapes.md#segment), [`OrientedSegment`](doc/shapes.md#oriented-segment), [`Line`](doc/shapes.md#line), [`OrientedLine`](doc/shapes.md#oriented-line), [`Ray`](doc/shapes.md#ray), ~~[`Polyline`](doc/shapes.md#polyline), [`PolyFunction`](doc/shapes.md#monotone-polyline)~~ |
+| 2-dimensional | [`Halfplane`](doc/shapes.md#half-plane), [`Triangle`](doc/shapes.md#triangle), [`Rectangle`](doc/shapes.md#rectangle), [`Disk`](doc/shapes.md#disk), [`Convex`](doc/shapes.md#convex), [`Polygon`](doc/shapes.md#polygon) |
+
+The following [predicates](doc/shape_methods.md#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?
+
+```python
+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](doc/shape_methods.md) are supported by the shapes.
+
+```python
+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](doc/canvas.md):
+
+<img align="right" src="https://raw.githubusercontent.com/gfonsecabr/pypgl/main/doc/figures/example2.svg" width="200"/>
+
+```python
+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
+
+<img align="right" src="https://raw.githubusercontent.com/gfonsecabr/pypgl/main/doc/figures/example_triangulation.svg" width="200"/>
+
+PGL includes [fundamental algorithms](doc/algorithms.md) and [data structures](doc/data_structures.md) 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
+
+```bash
+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.
+
+```bash
+pip install git+https://github.com/gfonsecabr/pypgl.git
+```
+
+### Development install
+
+Work on the bindings from a checkout with an editable, in-place build:
+
+```bash
+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:
+
+```bash
+.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](doc/).
+- For some simple examples, check the files at the [examples folder](examples/).
+- Check the [C++ version](https://github.com/gfonsecabr/pgl).
+