Description

About ===== .. image:: https://badge.fury.io/py/pyclipper.svg :target: https://badge.fury.io/py/pyclipper .. image:: https://github.com/fonttools/pyclipper/workflows/Build%20+%20Deploy/badge.svg :target: https://github.com/fonttools/pyclipper/actions?query=workflow%3A%22Build+%2B+Deploy%22 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) <http://www.angusj.com/delphi/clipper.php>`__. Source code is available on `GitHub <https://github.com/fonttools/pyclipper>`__. The package is published on `PyPI <https://pypi.python.org/pypi/pyclipper>`__. 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. \ `Angus Johnson's Clipper library <http://www.angusj.com/delphi/clipper.php>`__\ 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 <http://www.angusj.com/delphi/clipper.php>`__): .. code:: python 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: .. code:: python 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. Authors ======= - The Clipper library is written by `Angus Johnson <http://www.angusj.com/delphi/clipper.php>`__, - This wrapper was initially written by `Maxime Chalton <https://sites.google.com/site/