Documentation

Module documentation.

Corona binding of Clipper, a library that performs line & polygon clipping - intersection, union, difference & exclusive-or, and line & polygon offsetting. The library is based on Vatti's clipping algorithm.

To use the plugin, add the following in build.settings:

plugins = {
  ["plugin.clipper"] = { publisherId = "com.xibalbastudios" }
}

A sample project is available here.

This plugin is designed to be called safely from other Lua processes.

Adapted from the Clipper home page:

The Clipper Library performs clipping, and offsetting of both lines and polygons.

A number of features set Clipper apart from other clipping libraries:

it accepts all types of polygons including self-intersecting ones
it supports multiple polygon filling rules (EvenOdd, NonZero, Positive, Negative)
it's very fast relative to other libraries
it's numerically robust
it also performs line and polygon offsetting
it's free to use in both freeware and commercial applications

Version: 6.1.3

Last updated: 19 January 2014

Freeware for both open source and commercial applications (Boost Software License).

Terminology:

Clipping: commonly refers to the process of cutting away from a set of 2-dimensional geometric shapes those parts that are outside a rectangular 'clipping' window. This can be achieved by intersecting subject paths (lines and polygons) with a clipping rectangle. In a more general sense, the clipping window need not be rectangular but can be any type of polygon, even multiple polygons. Also, while clipping typically refers to an intersection operation, in this documentation it will refer to any one of the four boolean operations (intersection, union, difference and exclusive-or).
Path: is an ordered sequence of vertices defining a single geometric contour that's either a line (an open path) or a polygon (a closed path).
Line: or polyline is an open path containing 2 or more vertices.
Polygon: commonly refers to a two-dimensional region bounded by an outer non-intersecting closed contour. That region may also contain a number of 'holes'. In this documentation however, polygon will simply refer to a closed path.
Contour: synonymous with path.
Hole: is a closed region within a polygon that's not part of the polygon. A 'hole polygon' is a closed path that forms the outer boundaries of a hole.
Polygon Filling Rule: the filling rule, together with a list of closed paths, defines those regions (bounded by paths) that are inside (ie regions 'brush filled' in a graphical display) and those which are outside (ie 'holes').

References:

The Library is based on but significantly extends Bala Vatti's polygon clipping algorithm as described in "A generic solution to polygon clipping", Communications of the ACM, Vol 35, Issue 7 (July 1992) pp 56-63.

A section in "Computer graphics and geometric modeling: implementation and algorithms" by By Max K. Agoston (Springer, 2005) discussing Vatti Polygon Clipping was also helpful in creating the initial Clipper implementation.

The paper titled "Polygon Offsetting by Computing Winding Numbers" by Chen & McMains (Paper no. DETC2005-85513, ASME 2005. Pages 565-575) contains helpful discussion on the complexities of polygon offsetting together with some solutions.

Modules

core	Various free functions used by Clipper.

Classes

Buffer	Utility data storage type.
ClipType	One of the following strings: "Intersection": Create regions where both subject and clip polygons are filled.
Offset	An encapsulation of the process of offsetting (inflating/deflating) both open and closed paths using a number of different join types and end types.
Path	A sequence of integer-valued points representing a single contour (see also terminology).
Paths	This structure is fundamental to the Clipper Library.
PolyFillType	One of the following strings: "EvenOdd": Odd numbered sub-regions are filled, while even numbered sub-regions are not.
PolyNode	PolyNodes are encapsulated within a PolyTree container, and together provide a data structure representing the parent-child relationships of polygon contours returned by the Clipper:Execute method.
PolyTree	PolyTree is intended as a read-only data structure that should only be used to receive solutions from clipping and offsetting operations.
cInt	Clipper integer.
Clipper	An encapsulation of various boolean operations on polygons.