Class Clipper

An encapsulation of various boolean operations on polygons.

Input polygons, both subject and clip sets, are passed to a Clipper object by its AddPath and AddPaths methods, and the clipping operation is performed by calling its Execute method. Multiple boolean operations can be performed on the same input polygon sets by repeat calls to Execute.

Methods

Clipper:AddPath (path, poly_type)
Any number of subject and clip paths can be added to a clipping task, either individually via this method, as groups via AddPaths, or even using both methods.

'Subject' paths may be either open (lines) or closed (polygons) or even a mixture of both, but 'clipping' paths will always be closed. Clipper allows polygons to clip both lines and other polygons, but doesn't allow lines to clip either lines or polygons.

With closed paths, orientation should conform with the filling rule that will be passed via Clipper:Execute.

Path Coordinate range:

Path coordinates must be between ±4.6e+18 (2^62), otherwise a range error will be thrown when attempting to add the path to the Clipper object. If coordinates can be kept between ±1.0e+9, large integer math can be avoided, for a modest increase in performance (approx. 15-20%) over the larger range

Parameters:

  • path Path
  • poly_type string One of "Subject", "SubjectClosed", or "Clip".

    Boolean (clipping) operations are mostly applied to two sets of Polygons, represented in this library as subject and clip polygons. Whenever polygons are added to the Clipper object, they must be assigned to either subject or clip polygons.

    UNION operations can be performed on one set or both sets of polygons, but all other boolean operations require both sets of polygons to derive meaningful solutions.

Returns:

    boolean

    Was the path valid? A path is invalid for clipping when:

    • it has less than 2 vertices
    • it has 2 vertices but is not an open path
    • the vertices are all co-linear and it is not an open path
Clipper:AddPaths (paths, poly_type)
Like Clipper:AddPath, but allows adding paths as a group.

Parameters:

Returns:

    boolean As per Clipper:AddPath.
Clipper:Clear ()
Removes any existing subject and clip polygons allowing the Clipper object to be reused for clipping operations on different polygon sets.
Clipper:Execute (clip_type[, opts])
Once subject and clip paths have been assigned (via AddPath and / or AddPaths), Execute can then perform the clipping operation (intersection, union, difference or XOR) specified by the clip_type parameter.

The solution can be either a Paths or PolyTree. 1The Paths structure is simpler than the PolyTree stucture. Because of this it is quicker to populate and hence clipping performance is a little better (it's roughly 10% faster). However, the PolyTree data structure provides more information about the returned paths which may be important to users. Firstly, the PolyTree structure preserves nested parent-child polygon relationships` (i.e. outer polygons owning / containing holes and holes owning / containing other outer polygons etc). Also, only the PolyTree structure can differentiate between open and closed paths since each PolyNode has an IsOpen property. (The Path structure has no member indicating whether it's open or closed.) For this reason, when open paths are passed to a Clipper object, the user must use a PolyTree object as the solution, otherwise an error is thrown.

When a PolyTree object is used in a clipping operation on open paths, two ancillary functions have been provided to quickly separate out open and closed paths from the solution - OpenPathsFromPolyTree and ClosedPathsFromPolyTree. PolyTreeToPaths is also available to convert path data to a Paths structure (irrespective of whether they're open or closed).

There are several things to note about the solution paths returned:

  • they aren't in any specific order
  • they should never overlap or be self-intersecting (but see notes on rounding)
  • holes will be oriented opposite outer polygons
  • the solution fill type can be considered either EvenOdd or NonZero since it will comply with either filling rule
  • polygons may rarely share a common edge (though this is now very rare as of version 6)

The subject and clip fill type parameters define the polygon fill rule to be applied to the polygons (i.e. closed paths) in the subject and clip paths respectively. (It's usual though obviously not essential that both sets of polygons use the same fill rule.)

Execute can be called multiple times without reassigning subject and clip polygons (i.e. when different clipping operations are required on the same polygon sets).

See here for a visual example of the results.

Parameters:

  • clip_type ClipType
  • opts table

    Options, which may include:

    • fill_type: The common fill rule applied to both sets. (Default "EvenOdd")
    • out: If this is a Paths or PolyTree, it will be populated and used as the return value.
    (optional)

Returns:

    PolyTree, Paths or nil Solution, or nil if there was a problem.
Clipper:Execute (clip_type, subject, clip[, opts])
Alternative signature.

Parameters:

  • clip_type ClipType
  • subject PolyFillType Fill rule for subject set...
  • clip PolyFillType ...and for clip set.
  • opts table Options, which may contain out as per the other overload. (optional)

Returns:

    PolyTree, Paths or nil Solution, or nil if there was a problem.
Clipper:GetBounds ([bounds])

Parameters:

  • bounds table If present, this is populated and used as the return value. (optional)

Returns:

    table Bounds table with left, right, top, and bottom cInt members, describing the axis-aligned bounding rectangle of all polygons that have been added to the Clipper object.
Clipper:GetPreserveCollinear ()

Returns:

    boolean Is collinear preservation enabled?

See also:

Clipper:GetReverseSolution ()

Returns:

    boolean Is reversal enabled?

See also:

Clipper:GetStrictlySimple ()

Returns:

    boolean Are simple polygons strictly simple?

See also:

Clipper:SetPreserveCollinear (enable)
By default, when three or more vertices are collinear in input polygons (subject or clip), the Clipper object removes the 'inner' vertices before clipping. When enabled the PreserveCollinear property prevents this default behavior to allow these inner vertices to appear in the solution.

Parameters:

  • enable bool Enable this state? (Disable it with false.)

See also:

Clipper:SetReverseSolution (enable)
When this property is enabled, polygons returned in the solution parameter of Clipper:Execute will have orientations opposite to their normal orientations.

Parameters:

  • enable bool Enable this state? (Disable it with false.)

See also:

Clipper:SetStrictlySimple (enable)
Terminology:

  • A simple polygon is one that does not self-intersect.
  • A weakly simple polygon is a simple polygon that contains 'touching' vertices, or 'touching' edges.
  • A strictly simple polygon is a simple polygon that does not contain 'touching' vertices, or 'touching' edges.

Vertices 'touch' if they share the same coordinates (and are not adjacent). An edge touches another if one of its end vertices touches another edge excluding its adjacent edges, or if they are co-linear and overlapping (including adjacent edges).

Polygons returned by clipping operations (see Clipper:Execute) should always be simple polygons. When the StrictlySimple property is enabled, polygons returned will be strictly simple, otherwise they may be weakly simple. It's computationally expensive ensuring polygons are strictly simple and so this property is disabled by default.

Note: There's currently no guarantee that polygons will be strictly simple since 'simplifying' is still a work in progress.

(See here for a nice visual example.)

Parameters:

  • enable bool Enable this state? (Disable it with false.)

See also:

generated by LDoc 1.4.6 Last updated 2018-08-13 18:06:38