DOCSEARCHbyAlgolia
Submit Docs

Pyclipper

repository·main·Indexed 42 days ago

https://github.com/fonttools/pyclipper

A Cython wrapper for the C++ Clipper library providing high-performance polygon clipping (intersection, union, difference, XOR) and offsetting capabilities for Python. Features the Pyclipper and PyclipperOffset classes and provides helper functions scale_to_clipper() and scale_from_clipper() for floating-point coordinate conversion.

Tokens
964
Snippets
3
Records
6
Agent score
4%

What's inside Pyclipper

  1. How Pyclipper maps to the original Clipper library

    main

    Pyclipper follows the naming conventions of the original C++ Clipper library with the following mappings:

    • The ClipperLib namespace is represented by the pyclipper module.
    • The classes Clipper and ClipperOffset are mapped to Pyclipper and PyclipperOffset respectively.
    • When the original library overloads functions with different parameter counts or types (e.g., Clipper.Execute returning a list of paths vs. a PolyTree), Pyclipper uses Pyclipper.Execute and Pyclipper.Execute2 to distinguish them.

  2. Install pyclipper

    main

    You can install pyclipper via PyPI using pip, or build it from source.

    From PyPI

    pip install pyclipper

    From source

    Clone the repository and install using pip:

    git clone git@github.com:fonttools/pyclipper.git
pip install .

    For development, use an editable install:

    pip install -e .

  3. Migrate from Pyclipper 0.9.3b0 (Removal of SCALING_FACTOR)

    main

    In version 1.0.0, the SCALING_FACTOR variable was removed to prevent inexact conversions related to floating-point operations and to preserve the numerical robustness of the base library.

    This change breaks backward compatibility. Users who relied on automatic scaling via SCALING_FACTOR must now manually manage coordinate scaling using the provided helper functions: scale_to_clipper() and scale_from_clipper().

  4. Perform polygon offsetting with PyclipperOffset

    main

    Use the PyclipperOffset class to offset lines and polygons.

    Commonly used constants include:

    • JT_ROUND: Join type (Round).
    • ET_CLOSEDPOLYGON: End type (Closed Polygon).
    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)

  5. Perform polygon clipping with Pyclipper

    main

    Use the Pyclipper class to perform intersection, union, difference, or exclusive-or operations on polygons.

    Note that the library uses integers for numerical robustness. If you are working with floating-point coordinates, use the helper functions scale_to_clipper() and scale_from_clipper() to convert them.

    Commonly used constants include:

    • PT_SUBJECT: Subject path type.
    • PT_CLIP: Clip path type.
    • CT_INTERSECTION: Clipping type for intersection.
    • PFT_EVENODD: Fill type (Even-Odd rule).
    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)

  6. Configure Clipper preprocessor directives

    main

    Pyclipper supports certain Clipper preprocessor directives that can be changed by modifying the define_macros collection in setup.py and rebuilding the package.

    Supported directives:

    • use_int32: When enabled, 32-bit integers are used instead of 64-bit integers. This improves performance but limits coordinate values to the range +/- 46340. Disabled by default.
    • use_lines: Enables line clipping. Adds a minor performance cost. Enabled by default (since version 0.9.2b0).

    To change these, add a set like ('use_int32', 1) to define_macros in setup.py and rebuild.