clipper2-py 0.1.0__tar.gz

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

@@ -0,0 +1,115 @@
+name: wheels
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: ${{ matrix.os }} ${{ matrix.arch }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-24.04, arch: x86_64 }
+          - { os: ubuntu-24.04-arm, arch: aarch64 }
+          - { os: macos-14, arch: arm64 }
+          - { os: macos-14, arch: x86_64 }
+          - { os: windows-2022, arch: AMD64 }
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: true
+
+      - name: Check tag matches project version
+        if: startsWith(github.ref, 'refs/tags/v')
+        shell: bash
+        run: |
+          v=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          [ "v$v" = "${GITHUB_REF_NAME}" ] || {
+            echo "tag ${GITHUB_REF_NAME} does not match pyproject version $v"; exit 1; }
+
+      - uses: pypa/cibuildwheel@v4.2.0
+        env:
+          CIBW_ARCHS: ${{ matrix.arch }}
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}-${{ matrix.arch }}
+          path: wheelhouse/*.whl
+
+  sdist:
+    name: sdist
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: true
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - name: Install from sdist and run tests
+        run: |
+          python -m venv /tmp/sdist-venv
+          /tmp/sdist-venv/bin/pip install dist/*.tar.gz pytest
+          /tmp/sdist-venv/bin/python -m pytest tests
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-sdist
+          path: dist/*.tar.gz
+
+  numpy-floor:
+    name: tests with numpy 1.23 + differential tests
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: true
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.10"
+
+      - name: Build the C++ reference CLI
+        run: |
+          cmake -S tests/reference -B build/ref -DCMAKE_BUILD_TYPE=Release
+          cmake --build build/ref
+
+      - name: Install and run tests
+        run: |
+          python -m pip install "numpy==1.23.*" pytest mypy .
+          python -m pytest tests
+
+  publish:
+    needs: [build, sdist, numpy-floor]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+      - name: Publish GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" dist/* \
+            --repo "${GITHUB_REPOSITORY}" --generate-notes ||
+          gh release upload "${GITHUB_REF_NAME}" dist/* \
+            --repo "${GITHUB_REPOSITORY}" --clobber

clipper2_py-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+build/
+dist/
+wheelhouse/
+*.egg-info/
+__pycache__/
+*.so
+*.pyd
+.pytest_cache/
+.venv/
+.DS_Store

clipper2_py-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "third_party/Clipper2"]
+	path = third_party/Clipper2
+	url = https://github.com/AngusJohnson/Clipper2

clipper2_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This package
+has its own [semantic version](https://semver.org/spec/v2.0.0.html), independent of the
+Clipper2 version it bundles; `clipper2.CLIPPER2_VERSION` tells the latter.
+
+## 0.1.0 — 2026-09-19
+
+First release. Bundles Clipper2 2.0.1 (upstream tag `Clipper2_2.0.1`).
+
+### Added
+
+- The complete public Clipper2 API as `clipper2`: the boolean operations (`union`,
+  `intersect`, `difference`, `xor`, `boolean_op`, `boolean_op_tree`) and the `Clipper64` /
+  `ClipperD` engine classes with open subjects, `execute`, `execute_tree` and
+  `ReuseableDataContainer64`.
+- Offsetting: `inflate_paths` and `ClipperOffset`, including upstream's variable-offset
+  delta callback.
+- `rect_clip`, `rect_clip_lines` and the `RectClip64` / `RectClipLines64` classes;
+  `minkowski_sum` and `minkowski_diff`; `triangulate`.
+- The read-only `PolyPath64` / `PolyPathD` tree, `Rect64` / `RectD`, the enums, and the
+  geometry helpers of `clipper.core.h` and `clipper.h` (`area`, `get_bounds`,
+  `point_in_polygon`, `simplify_path`, `ramer_douglas_peucker`, `ellipse`, `distance`,
+  `length`, `make_path`, …).
+- `clipper2.z`: the same library built with `USINGZ`, with N×3 paths and a z callback that
+  returns the z of each new point.
+- numpy arrays in and out: a path is an N×2 array, paths are a list of them, and the
+  input's dtype picks upstream's 64 or D family.
+- `Clipper2Error` for `Clipper2Lib::Clipper2Exception`, with upstream's message.
+- Type stubs and a `py.typed` marker.
+- Wheels for Linux x86_64 and aarch64 (manylinux_2_28), macOS x86_64 and arm64, and
+  Windows AMD64, on CPython 3.10–3.14.
+
+### Known issues
+
+- Upstream's `Triangulate` does not return, or exhausts memory, on some degenerate inputs;
+  the binding cannot guard against it
+  ([#2](https://github.com/Maksim-Burtsev/clipper2-py/issues/2)). Upstream's crash in
+  `ClipperOffset` on an empty path with an open end type is guarded: such paths are dropped
+  ([#1](https://github.com/Maksim-Burtsev/clipper2-py/issues/1)).
+- `clipper.export.h`, upstream's C ABI for DLL users, is not bound. See [DEVIATIONS.md](DEVIATIONS.md)
+  and [docs/api-map.md](docs/api-map.md).

clipper2_py-0.1.0/CMakeLists.txt

@@ -0,0 +1,36 @@
+cmake_minimum_required(VERSION 3.15)
+project(clipper2_py LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_VISIBILITY_PRESET hidden)
+set(CMAKE_VISIBILITY_INLINES_HIDDEN ON)
+
+set(CLIPPER2_DIR "${CMAKE_CURRENT_SOURCE_DIR}/third_party/Clipper2/CPP/Clipper2Lib")
+if(NOT EXISTS "${CLIPPER2_DIR}/src/clipper.engine.cpp")
+  message(FATAL_ERROR "third_party/Clipper2 is empty: run git submodule update --init")
+endif()
+# Upstream sources are compiled straight into each extension: the Z build changes the Point
+# layout, so the two extensions cannot share one library.
+set(CLIPPER2_SOURCES
+  "${CLIPPER2_DIR}/src/clipper.engine.cpp"
+  "${CLIPPER2_DIR}/src/clipper.offset.cpp"
+  "${CLIPPER2_DIR}/src/clipper.rectclip.cpp"
+  "${CLIPPER2_DIR}/src/clipper.triangulation.cpp")
+set(BINDING_SOURCES
+  src/cpp/module.cpp
+  src/cpp/bind_core.cpp
+  src/cpp/bind_engine.cpp
+  src/cpp/bind_offset.cpp
+  src/cpp/bind_misc.cpp)
+
+set(PYBIND11_FINDPYTHON ON)
+find_package(pybind11 CONFIG REQUIRED)
+
+foreach(mod _clipper2 _clipper2z)
+  pybind11_add_module(${mod} ${BINDING_SOURCES} ${CLIPPER2_SOURCES})
+  target_include_directories(${mod} PRIVATE "${CLIPPER2_DIR}/include" src/cpp)
+  target_compile_definitions(${mod} PRIVATE CLIPPER2_PY_MODULE_NAME=${mod})
+  install(TARGETS ${mod} DESTINATION clipper2)
+endforeach()
+target_compile_definitions(_clipper2z PRIVATE USINGZ)

clipper2_py-0.1.0/DEVIATIONS.md

@@ -0,0 +1,198 @@
+# Deviations
+
+The algorithms are upstream Clipper2's, untouched: the same input produces the same result
+as the C++ library. What follows is everything a C++ user would notice when moving to
+Python. Nothing here changes what the library computes.
+
+`docs/api-map.md` lists every upstream symbol with its Python name or the reason it is not
+bound.
+
+## 1. Names
+
+`InflatePaths` → `inflate_paths`, `Clipper64.AddSubject` → `add_subject`. Getter/setter
+pairs such as `MiterLimit()` / `MiterLimit(v)` are properties (`miter_limit`); a plain
+getter stays a method (`is_valid()`, `mid_point()`), except on the `PolyPath` tree, where
+`level`, `is_hole`, `parent`, `polygon`, `scale` are attributes and `area()` is a method.
+Class names keep their CamelCase, enum members are UPPER_SNAKE (`FillRule.NON_ZERO`).
+
+Keyword-argument names are upstream's parameter names, snake_cased. Upstream is not always
+consistent, and neither are we: `boolean_op(..., precision=...)` but
+`intersect(..., decimal_prec=...)`, `Clipper64.execute(clip_type=..., fill_rule=...)` but
+`boolean_op(cliptype=..., fillrule=...)`, `minkowski_sum(..., decimal_places=...)` but
+`triangulate(..., dec_places=...)`, and `ClipperOffset.add_path(path, jt_, et_)` with the
+trailing underscores upstream's parameters carry.
+
+## 2. Points, paths and the two families
+
+A point goes in as any pair `(x, y)` and comes back as a tuple. A path goes in as any
+sequence of points or an N×2 array and comes back as an N×2 numpy array (`int64` for the 64
+family, `float64` for D); paths come back as a list of such arrays.
+
+Which family runs is decided by the dtype `numpy.asarray` infers for the point and path
+arguments: integer → 64, float → D. Mixing families in one call is a `TypeError` (in C++ it
+would not compile). An empty input has no dtype: it takes the family of the other
+arguments, and the 64 family if there are none. An integer array is accepted by a D
+function (C++ converts `int` to `double` implicitly); a float array is refused by a 64
+function.
+
+C++ picks between `Area(Path)` and `Area(Paths)` by static type. Python has only the shape
+of the argument, so `area`, `get_bounds`, `ramer_douglas_peucker`, `strip_near_equal`,
+`strip_duplicates`, `rect_clip` and `rect_clip_lines` choose by nesting depth: a sequence of
+points is a path, a sequence of those is paths. An empty sequence cannot be a point, so it is
+an empty path: `[[]]` is paths holding one empty path, and a bare `[]` is an empty path.
+
+A generator, a `map` object or any other one-shot iterator is accepted wherever a point, a
+path or paths are: the binding materialises it once on the way in, at every level (a list
+of generators of points works too). C++ takes a container; here the argument is walked more
+than once — to pick the family and then to convert it — and an iterator would be empty the
+second time. Strings and bytes are still refused.
+
+`rect_clip` and `rect_clip_lines` take the family from the rect as well, because that is what
+picks the overload in C++: a `Rect64` with float paths, or a `RectD` with integer ones, is a
+`TypeError`. `ClipperOffset` and the `RectClip64` / `RectClipLines64` classes are 64-only
+upstream, so float input is a `TypeError` there too.
+
+## 3. Validation the C++ compiler does for free
+
+* A wrong shape is a `ValueError`.
+* An integer that does not fit `int64` is an `OverflowError`; a `uint64` array above
+  `INT64_MAX` too. Nothing is ever truncated silently. Which family runs is decided from
+  the Python objects, not from the array numpy would make of them: `[(0, 0), (2**63, 0)]`
+  is 64-family input whose coordinate overflows, not float64 input. (An `int` and a `float`
+  *mixed* in one argument is still what numpy makes of it: the D family.)
+* Anything that is not an integer or float dtype is a `TypeError` — including `bool`
+  arrays, string arrays and numpy `object` arrays. A Python `bool` is never a coordinate
+  either, wherever it sits: `distance(True, (1, 2))` and `area([(True, 2), (3, 4), (5, 9)])`
+  are `TypeError`s, although numpy would quietly make them 1 and 0.
+* A float where C++ takes `int64_t` (`translate_path(path, 0.5, 0)` on the 64 family) is a
+  `TypeError`; an int where C++ takes `double` is fine.
+* An index outside a `PolyPath`'s children raises `IndexError`; C++ has undefined behaviour
+  there. Negative indices are not accepted: upstream has no such concept.
+
+## 4. Out-parameters became return values
+
+* `Clipper64.execute(clip_type, fill_rule)` returns `(closed_paths, open_paths)`;
+  `execute_tree` returns `(tree, open_paths)`. Same for `ClipperD`.
+* The `BooleanOp` overload that fills a `PolyTree` is `boolean_op_tree`.
+* `ClipperOffset.execute(delta)` returns the paths and `execute_tree(delta)` the tree. The
+  `Execute` overload that takes a `DeltaCallback64` is `execute(callable)`: as upstream, it
+  offsets with a delta of 1.0 and leaves the callback set on the object afterwards.
+* `triangulate(...)` returns `(TriangulateResult, paths)`.
+* `get_line_intersect_pt(...)` returns the point, or `None` where upstream returns `false`
+  and leaves its out-parameter untouched.
+* `strip_duplicates(path, is_closed_path)` returns the stripped path; C++ edits its
+  argument in place.
+* Upstream's `Execute` returning `false` (an internal inconsistency it reports through the
+  return value) raises `Clipper2Error` with upstream's own "There is an undefined error in
+  Clipper2" text.
+
+## 5. `precision` / `decimal_prec`
+
+Only the D family has these parameters upstream, so they default to `None`: passing one to
+a 64-family call is a `TypeError`. `trim_collinear` (`precision`) and `triangulate`
+(`dec_places`) are the two whose D overload has no default upstream, so they require the
+argument for float input.
+
+In three functions upstream's D overload inserts this parameter in the middle of the list:
+`InflatePaths(…, miter_limit, precision, arc_tolerance)`, `TrimCollinear(path, precision,
+is_open_path)`, `Triangulate(pp, decPlaces, solution, useDelaunay)`. One Python function
+serves both families, so a call written by position would change meaning with the input's
+dtype. There the parameter and everything after it are keyword-only:
+`inflate_paths(paths, delta, jt, et, miter_limit=2.0, *, precision=None, arc_tolerance=0.0)`,
+`trim_collinear(path, *, precision=None, is_open_path=False)`,
+`triangulate(pp, *, dec_places=None, use_delaunay=True)`.
+
+## 6. Errors
+
+`Clipper2Lib::Clipper2Exception` becomes `clipper2.Clipper2Error` (a subclass of
+`Exception`) with upstream's message. Where C++ silently returns an empty result, so do we.
+`clipper2.z.Clipper2Error` is the very same class, as are the enums, `Rect64` and `RectD`.
+
+## 7. The z build
+
+`clipper2.z` is the same library compiled with `USINGZ`. Points are `(x, y, z)` and paths
+are N×3 arrays. Upstream's `z` is `int64_t` in **both** families (`z_type` in
+clipper.core.h), so in the D family the third column is an integer value carried in a
+`float64` array, and a fractional z on the way in is truncated towards zero — exactly what
+upstream's own `MakePathZD` does. An N×2 path is also accepted and gets z = 0, which is
+what upstream's `Point` constructor does.
+
+Because that column is a `float64`, a D-family z on the way **in** is checked where C++
+would only `static_cast`: a `nan` or an infinity is a `ValueError`, a value outside `int64`
+an `OverflowError` (both are undefined behaviour in C++). On the way **out** nothing is
+checked, and a z with |z| > 2⁵³ cannot be represented exactly in the float64 column of a D
+path: the array rounds it. A point returned as a tuple carries the exact integer.
+
+`Rect64` and `RectD` are among the types registered once, in the non-USINGZ extension
+(deviation 6), so in `clipper2.z` they stay two-dimensional: `mid_point()` returns
+`(x, y)`, `as_path()` an N×2 array, and `contains(pt)` wants a plain `(x, y)` — a
+three-element point is a `ValueError` there. Everything compiled into both modules
+(`clipper2.z.mid_point`, `clipper2.z.ellipse`, …) does use three-element points.
+
+`set_z_callback(fn)` takes `fn(e1bot, e1top, e2bot, e2top, pt)` and uses its **return
+value** as the z of `pt`; upstream's callback writes `pt.z` through a reference, which
+Python cannot do. `set_z_callback(None)` removes the callback.
+
+Objects must not be passed between `clipper2` and `clipper2.z`: the two builds lay points
+out differently, so a `clipper2.PolyPath64` is not a `clipper2.z.PolyPath64`. Where such an
+object is a function argument (`poly_tree_to_paths64`, `poly_tree_to_paths_d`,
+`check_polytree_fully_contains_children`, `add_reuseable_data`) the binding checks and
+raises `TypeError`. Reaching an unbound method of one module's class with the other
+module's instance (`clipper2.Clipper64.clear(z_clipper)`) is not guarded.
+
+## 8. Callbacks and the GIL
+
+The GIL is released while upstream code runs and re-acquired for callbacks, so two threads
+clip in parallel. An exception raised inside a callback — a z callback, or `ClipperOffset`'s
+delta callback — propagates out of `execute()`, with its original type, message and
+traceback. It is **not** allowed to unwind through upstream's C++, which would skip the
+clean-up `Execute` ends with (`ClipperOffset::Execute(double, PolyTree64&)` deletes the
+solution it allocated, and leaked it that way). The binding holds the exception instead:
+the first one wins, the callback is not called again for the rest of that `execute`, the
+callback returns a neutral value to upstream (the z callback leaves `pt.z` as upstream set
+it, the delta callback offsets by 0), and once `Execute` has returned and cleaned up after
+itself the exception is re-raised and no result is returned. The object is left as after a
+normal `execute` — usable, with its paths still added — and every object holds its own
+pending exception, so two threads may fail independently.
+
+## 9. A clipper that is executing is off limits
+
+While `Clipper64`, `ClipperD` or `ClipperOffset` is inside `execute` / `execute_tree`, any
+other call on that **same** object that would mutate or execute it — `add_*`, `clear`,
+`execute*`, `set_z_callback`, `set_delta_callback`, `add_reuseable_data`, a property setter,
+`default_z` — raises `RuntimeError("<ClassName> is executing")`, whether it comes from a
+callback or from another thread (the GIL is released, so another thread can get that far).
+C++ has undefined behaviour here: upstream's engine is walking the very structures such a
+call would rebuild. Reading a property is still allowed, and a different object is never
+affected.
+
+`add_reuseable_data` keeps a reference to the container until the clipper's `clear()` or
+its death, because upstream keeps raw `Vertex` pointers into it; in C++ keeping it alive is
+the caller's job.
+
+`ClipperOffset`'s delta callback is upstream's `DeltaCallback64`:
+`fn(path, path_normals, curr_idx, prev_idx)` returns the delta to use, with `path` as an
+int64 array and `path_normals` as a float64 one.
+
+## 10. One guard against an upstream crash
+
+Clipper2 2.0.1 (and its main branch) reads `path.size() - 1` of an **empty path** when the
+end type is an open one (`JOINED`, `BUTT`, `SQUARE`, `ROUND`) and crashes the process. From
+Python that would take the interpreter down, so `inflate_paths`, `ClipperOffset.add_path`
+and `add_paths` drop empty paths before upstream sees them when the end type is an open
+one. An empty path has nothing to offset, and with `EndType.POLYGON` upstream itself
+produces nothing for it, so no result changes. This is the only place where the binding
+steps in front of upstream's code
+([#1](https://github.com/Maksim-Burtsev/clipper2-py/issues/1)).
+
+## 11. What is not bound
+
+`clipper.export.h` (a C ABI for DLL users) and, per the coverage table in
+`docs/api-map.md`, upstream's C++-only plumbing: the type-conversion templates
+(`ScalePath`, `TransformPaths`, …) — use the D functions' `precision` or numpy's `astype` —
+the engine-internal structs, and the scalar helpers whose Python equivalent is exact
+(`Sqr` is `x * x`, `ProductsAreEqual` is `a * b == c * d` on Python's arbitrary-precision
+ints).
+
+`MakePath` and `MakePathD` are bound because upstream's documentation uses them; templates
+are instantiated for the 64 and D families only.

clipper2_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maksim Burtsev
+
+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.

clipper2_py-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: clipper2-py
+Version: 0.1.0
+Summary: Python bindings for Clipper2: polygon clipping, offsetting and triangulation
+Keywords: clipper,clipper2,polygon,clipping,offsetting,boolean,geometry,triangulation,minkowski,cam,gis
+Author-Email: Maksim Burtsev <mburtsev17@gmail.com>
+License-Expression: MIT AND BSL-1.0
+License-File: LICENSE
+License-File: third_party/Clipper2/LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/Maksim-Burtsev/clipper2-py
+Project-URL: Issues, https://github.com/Maksim-Burtsev/clipper2-py/issues
+Project-URL: Upstream, https://github.com/AngusJohnson/Clipper2
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: mypy; extra == "test"
+Description-Content-Type: text/markdown
+
+# clipper2-py
+
+[![PyPI](https://img.shields.io/pypi/v/clipper2-py.svg)](https://pypi.org/project/clipper2-py/)
+[![Python versions](https://img.shields.io/pypi/pyversions/clipper2-py.svg)](https://pypi.org/project/clipper2-py/)
+[![CI](https://github.com/Maksim-Burtsev/clipper2-py/actions/workflows/wheels.yml/badge.svg)](https://github.com/Maksim-Burtsev/clipper2-py/actions/workflows/wheels.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Maksim-Burtsev/clipper2-py/blob/main/LICENSE)
+
+Python bindings for [Clipper2](https://github.com/AngusJohnson/Clipper2), Angus Johnson's
+C++ library for polygon clipping, offsetting and triangulation. Unofficial; the whole C++
+API, numpy in and out.
+
+![intersect, union, difference, xor](https://raw.githubusercontent.com/Maksim-Burtsev/clipper2-py/main/docs/img/booleans.svg)
+
+```python
+import clipper2
+
+subject = [[(0, 0), (100, 0), (100, 100), (0, 100)]]
+clip = [[(50, 50), (150, 50), (150, 150), (50, 150)]]
+
+solution = clipper2.intersect(subject, clip, clipper2.FillRule.NON_ZERO)
+print(solution[0].tolist())
+# -> [[100, 100], [50, 100], [50, 50], [100, 50]]
+```
+
+```bash
+pip install clipper2-py
+```
+
+Wheels for Linux (x86_64, aarch64), macOS (x86_64, arm64) and Windows (AMD64),
+CPython 3.10–3.14. Clipper2 is compiled in; numpy is the only dependency.
+
+## Offsetting
+
+![round, miter and bevel joins](https://raw.githubusercontent.com/Maksim-Burtsev/clipper2-py/main/docs/img/offsetting.svg)
+
+```python
+from clipper2 import EndType, JoinType
+
+square = [[(0, 0), (100, 0), (100, 100), (0, 100)]]
+grown = clipper2.inflate_paths(square, 10, JoinType.MITER, EndType.POLYGON)
+print(grown[0].tolist())
+# -> [[110, 110], [-10, 110], [-10, -10], [110, -10]]
+```
+
+Open paths become strokes with `EndType.BUTT`, `SQUARE` or `ROUND`. `ClipperOffset` is
+the class behind it, with per-vertex deltas through a callback.
+
+## Triangulation, Minkowski sums, rectangle clipping
+
+![triangulate and minkowski_sum](https://raw.githubusercontent.com/Maksim-Burtsev/clipper2-py/main/docs/img/triangulate-minkowski.svg)
+
+```python
+result, triangles = clipper2.triangulate(square)
+print(result.name, len(triangles))
+# -> SUCCESS 2
+
+rect = clipper2.Rect64(50, 50, 200, 200)
+print(clipper2.rect_clip(rect, square)[0].tolist())
+# -> [[50, 50], [100, 50], [100, 100], [50, 100]]
+```
+
+## Integers or floats
+
+Clipper2 has two families of every function: `Paths64` on `int64` and `PathsD` on
+`double`. Here there is one function, and the input picks the family:
+
+```python
+print(clipper2.union([[(0, 0), (10, 0), (10, 10)]], clipper2.FillRule.NON_ZERO)[0].dtype)
+# -> int64
+print(clipper2.union([[(0, 0), (10, 0), (10.5, 10)]], clipper2.FillRule.NON_ZERO)[0].dtype)
+# -> float64
+```
+
+Paths go in as lists of pairs or N×2 numpy arrays and come back as numpy arrays.
+
+## The same library, not a lookalike
+
+- **Names are upstream's, in snake_case**: `InflatePaths` → `inflate_paths`,
+  `Clipper64.AddSubject` → `add_subject`, `FillRule::NonZero` → `FillRule.NON_ZERO`.
+  [Every C++ symbol and its Python name](https://github.com/Maksim-Burtsev/clipper2-py/blob/main/docs/api-map.md).
+- **Results are upstream's, bit for bit.** 13 500 random cases are compared with a C++
+  reference program on every platform, for every wheel, and must be exactly equal —
+  including the `USINGZ` build, which is `clipper2.z`. Upstream's own test suite is ported
+  one to one.
+- **Every difference from C++ is written down** in [DEVIATIONS.md](https://github.com/Maksim-Burtsev/clipper2-py/blob/main/DEVIATIONS.md): out
+  parameters became return values, errors became exceptions, and where C++ has undefined
+  behaviour Python raises.
+
+More examples — `Clipper64` with open paths and the polytree, offset callbacks, the z
+module — are in the [guide](https://github.com/Maksim-Burtsev/clipper2-py/blob/main/docs/guide.md).
+
+## Benchmarks
+
+Apple M4, CPython 3.13, best of 5, conversion from numpy included:
+
+| | clipper2-py | pyclipr | pyclipper | shapely |
+| --- | --- | --- | --- | --- |
+| union of 1000 polygons | 34.4 ms | 35.7 ms | 71.2 ms | **11.4 ms** |
+| intersection, 10⁵ vertices | **5.25 ms** | 5.46 ms | 30.5 ms | 9.51 ms |
+| round offset, 1000 vertices | 0.36 ms | 0.39 ms | 1.46 ms | **0.24 ms** |
+| one small call | **1.14 µs** | 2.43 µs | 2.31 µs | 13.9 µs |
+
+pyclipr wraps the same Clipper2 and is as fast, but ships no Linux wheels and has its own
+API. pyclipper is Clipper1. shapely (GEOS) wins on big unions and on buffering.
+[Method and full results](https://github.com/Maksim-Burtsev/clipper2-py/blob/main/benchmarks/RESULTS.md).
+
+## Known upstream issue
+
+`triangulate` may never return, or may exhaust memory, on paths with **duplicate or
+self-intersecting vertices** — a bug of Clipper2 2.0.1 that is also in its main branch, and
+which inputs trigger it depends on the platform
+([#2](https://github.com/Maksim-Burtsev/clipper2-py/issues/2)). Upstream documents that
+`Triangulate` does not accept intersecting paths; passing the input through `union` first
+makes it safe. The binding changes nothing in upstream's algorithms, so it cannot hide this.
+
+## License
+
+MIT for the binding; Clipper2 is under the Boost Software License 1.0. Both texts ship in
+every wheel. `clipper2.CLIPPER2_VERSION` tells which Clipper2 is inside (2.0.1).