Programming Language
- Python
- Python :: 3
- Python :: 3.10
- Python :: 3.11
- Python :: 3.12
- Python :: 3.13
- Python :: 3.14
- Cython
- C++
Environment
- Other Environment
Development Status
- 4 - Beta
Intended Audience
- Developers
Operating System
- OS Independent
License
- OSI Approved
- OSI Approved :: MIT License
Topic
- Multimedia :: Graphics
- Scientific/Engineering :: Mathematics
- Software Development :: Libraries :: Python Modules
About
Pyclipper is a Cython wrapper exposing public functions and classes of the C++ translation of the Angus Johnson’s Clipper library (ver. 6.4.2).
Source code is available on GitHub. The package is published on PyPI.
About Clipper
Clipper - an open source freeware library for clipping and offsetting lines and polygons.
The Clipper library performs line & polygon clipping - intersection, union, difference & exclusive-or, and line & polygon offsetting. The library is based on Vatti’s clipping algorithm.
Install
From PyPI
pip install pyclipper
From source
Clone the repository:
git clone git@github.com:fonttools/pyclipper.git
Install:
pip install .
For development, use an editable install:
pip install -e .
Clippers’ preprocessor directives
Clipper can be compiled with the following preprocessor directives: use_int32, use_xyz, use_lines and use_deprecated. Among these the use_int32 and use_lines can be used with Pyclipper.
use_int32 - when enabled 32bit ints are used instead of 64bit ints. This improve performance but coordinate values are limited to the range +/- 46340. In Pyclipper this directive is disabled by default.
use_lines - enables line clipping. Adds a very minor cost to performance. In Pyclipper this directive is enabled by default (since version 0.9.2b0).
In case you would want to change these settings, clone this repository and change the define_macros collection (setup.py, pyclipper extension definition). Add a set like ('use_int32', 1) to enable the directive, or remove the set to disable it. After that you need to rebuild the package.
How to use
This wrapper library tries to follow naming conventions of the original library.
ClipperLib namespace is represented by the pyclipper module,
classes Clipper and ClipperOffset -> Pyclipper and PyclipperOffset,
when Clipper is overloading functions with different number of parameters or different types (eg. Clipper.Execute, one function fills a list of paths the other PolyTree) that becomes Pyclipper.Execute and Pyclipper.Execute2.
Basic clipping example (based on Angus Johnson’s Clipper library):
import pyclipper
subj = (
((180, 200), (260, 200), (260, 150), (180, 150)),
((215, 160), (230, 190), (200, 190))
)
clip = ((190, 210), (240, 210), (240, 130), (190, 130))
pc = pyclipper.Pyclipper()
pc.AddPath(clip, pyclipper.PT_CLIP, True)
pc.AddPaths(subj, pyclipper.PT_SUBJECT, True)
solution = pc.Execute(pyclipper.CT_INTERSECTION, pyclipper.PFT_EVENODD, pyclipper.PFT_EVENODD)
# solution (a list of paths): [[[240, 200], [190, 200], [190, 150], [240, 150]], [[200, 190], [230, 190], [215, 160]]]Basic offset example:
import pyclipper
subj = ((180, 200), (260, 200), (260, 150), (180, 150))
pco = pyclipper.PyclipperOffset()
pco.AddPath(subj, pyclipper.JT_ROUND, pyclipper.ET_CLOSEDPOLYGON)
solution = pco.Execute(-7.0)
# solution (a list of paths): [[[253, 193], [187, 193], [187, 157], [253, 157]]]The Clipper library uses integers instead of floating point values to preserve numerical robustness. If you need to scale coordinates of your polygons, this library provides helper functions scale_to_clipper() and scale_from_clipper() to achieve that.
Migrating from Pyclipper 0.9.3b0
In previous version of Pyclipper (0.9.3b0) polygons could be automatically scaled using the SCALING_FACTOR variable. This was removed in version 1.0.0 due to inexact conversions related to floating point operations. This way the library now provides the original numerical robustness of the base library.
The SCALING_FACTOR removal breaks backward compatibility. For an explanation and help with migration, see https://github.com/fonttools/pyclipper/wiki/Deprecating-SCALING_FACTOR.
License
Pyclipper is available under MIT license.
The core Clipper library is available under Boost Software License. Freeware for both open source and commercial applications.
Changelog
For recent versions, see the GitHub Releases page.
1.1.0
Updated embedded Clipper library to version 6.4.2.
1.0.6
Added support for Python 3.6.
1.0.3
added Travis CI and Appveyor CI to build wheel packages (thanks to @anthrotype)
1.0.2
bug fix: sympy.Zero recognized as a collection (thanks to @jamiebull1)
1.0.0
(breaks backwards compatibility) removes SCALING_FACTOR (thanks to @Feuermurmel)
0.9.3b0
Applied SCALING_FACTOR to the relevant function parameters and class properties
Refactored tests
0.9.2b1
bug fix: Fix setting of the PyPolyNode.IsHole property
0.9.2b0
enable preprocessor directive use_lines by default,
bug fix: PyPolyNode.Contour that is now one path and not a list of paths as it was previously.