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/maxelsbackyard/home/pyclipper>`__,
-  Adaptions to make it work with version 5 written by `Lukas
   Treyer <http://www.lukastreyer.com>`__,
-  Adaptions to make it work with version 6.2.1 and PyPI package written by `Gregor Ratajc <http://www.gregorratajc.com>`__,
-  ``SCALING_FACTOR`` removal and additions to documentation by Michael Schwarz (@Feuermurmel),
-  Bug fix `sympy.Zero` is not a collection by Jamie Bull (@jamiebull1),
-  Travis CI and Appveyor CI integration for continuous builds of wheel packages by Cosimo Lupo (@anthrotype).

The package is maintained by Cosimo Lupo (`@anthrotype <https://github.com/anthrotype>`__).

License
=======

-  Pyclipper is available under `MIT
   license <http://opensource.org/licenses/MIT>`__.
-  The core Clipper library is available under `Boost Software
   License <http://www.boost.org/LICENSE_1_0.txt>`__. Freeware for both
   open source and commercial applications.

Changelog
=========

For recent versions, see the `GitHub Releases page <https://github.com/fonttools/pyclipper/releases>`__.

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.
