Module core
Various free functions used by Clipper.
A few additional values are provided to build a Path like so:
local path = point1 .. point2 .. point3 .. clipper.ToPath
As shown, the value must appear at end of the sequence. The following choices are provided:
- ToPath: Points in Bytes form are interpreted as a contiguous pair of 32-bit signed integers.
- ToPath8: Like ToPath, but integers are 8-bit... (1 byte per component.)
- ToPath16: ...or 16-bit... (2 bytes per component.)
- ToPath64: ...or 64-bit. (8 bytes per component.)
A point may instead be a two-element array of cInts, i.e. {x, y}. The end marker is irrelevant here.
Functions
- Area (poly)
-
This function returns the area of the supplied polygon. Depending on Orientation, this value may be positive
or negative. If Orientation is true, then the area will be positive and conversely, if Orientation is
false, then the area will be negative. (It's assumed that the path will be closed.)
Parameters:
- poly Path
Returns:
-
number
Area.
- CleanPolygon (poly[, opts])
-
Removes vertices:
- that join co-linear edges, or join edges that are almost co-linear (such that if the vertex was moved no more than the specified distance the edges would be co-linear)
- that are within the specified distance of an adjacent vertex
- that are within the specified distance of a semi-adjacent vertex together with their out-lying vertices
Vertices are semi-adjacent when they are separated by a single (out-lying) vertex.
The distance parameter's default value is approximately √2 so that a vertex will be removed when adjacent or semi-adjacent vertices having their corresponding X and Y coordinates differing by no more than 1 unit. (If the edges are semi-adjacent the out-lying vertex will be removed too.)
See here for a visual example.
Parameters:
- CleanPolygons (polys[, opts])
-
Like CleanPolygon, but for multiple polygons.
Parameters:
- ClosedPathsFromPolyTree (PT[, opts])
-
This function filters out open paths from the PolyTree structure and returns only closed paths.
Parameters:
- PT PolyTree
- opts
table
Options, which may include:
- out: If this is a Paths, it will be populated and used as the return value.
Returns:
-
Paths
P
- MinkowskiDiff (poly1, poly2[, opts])
-
Minkowski Difference is performed by subtracting each point in a polygon from the set of points in an
open or closed path. A key feature of Minkowski Difference is that when it's applied to two polygons, the
resulting polygon will contain the coordinate space origin whenever the two polygons touch or overlap.
(This function is often used to determine when polygons collide.)
See here for a visual example.
Parameters:
- poly1 Path
- poly2 Path
- opts
table
Options, which may include:
- out: If this is a Paths, it will be populated and used as the return value.
Returns:
- MinkowskiSum (pattern, path[, opts])
-
Minkowski Addition is performed by adding each point in a polygon 'pattern' to the set of points in an open
or closed path. The resulting polygon (or polygons) defines the region that the 'pattern' would pass over in moving
from the beginning to the end of the 'path'.
See here for a visual example.
Parameters:
- pattern Path
- path Path or Paths
- opts
table
Options, which may include:
- is_closed: Is path closed?
- out: If this is a Paths, it will be populated and used as the return value.
Returns:
- NewBuffer ()
-
Returns:
-
Buffer
New Buffer object.
See also:
- NewClipper (init_opts)
-
Parameters:
- init_opts
{string,...}, string or nil
This may be an array of one or more of the following options to enable:
"PreserveCollinear", "ReverseSolution", "StrictlySimple". See the corresponding setters in Clipper
for details.
As a string, any of the above.
Returns:
-
Clipper
New Clipper object.
See also:
- init_opts
{string,...}, string or nil
This may be an array of one or more of the following options to enable:
"PreserveCollinear", "ReverseSolution", "StrictlySimple". See the corresponding setters in Clipper
for details.
- NewOffset ([opts])
-
DOCME
Parameters:
- opts
table
Options, which may include:
- miter_limit: Initial value for the miter limit (Default 2)
- round_precision: Initial value for the arc tolerance. (Default .25)
Returns:
-
Offset
New Offset object.
- opts
table
- NewPath ()
-
Returns:
-
Path
An empty instance.
- NewPathArray ()
-
Returns:
-
Paths
An empty instance.
- NewPolyNode ()
-
Returns:
-
PolyNode
An empty instance, intended as an out parameter.
- NewPolyTree ()
-
Returns:
-
PolyTree
An empty instance, intended as an out parameter.
- OpenPathsFromPolyTree ([opts])
-
This function filters out closed paths from the PolyTree structure and returns only open paths.
Parameters:
- opts
table
Options, which may include:
- out: If this is a Paths, it will be populated and used as the return value.
Returns:
- opts
table
- Orientation (P)
-
Orientation is only important to closed paths. Given that vertices are declared in a specific order, orientation refers to the direction (clockwise or counter-clockwise) that these vertices progress around a closed path; this will be true when the polygon's orientation is clockwise.
(Follow the link for a nice visual example.)
Notes:
- Self-intersecting polygons have indeterminate orientations in which case this function won't return a meaningful value.
- For Non-Zero filled polygons, the orientation of holes must be opposite that of outer polygons.
- For closed paths (polygons) in the solution returned by Clipper:Execute, their orientations will always be true for outer polygons and false for hole polygons (unless the ReverseSolution property has been enabled).
Parameters:
- P Path
Returns:
-
boolean
B
- PointInPolygon (x, y, poly)
-
Parameters:
Returns:
-
If the point is outside, false. Otherwise, "on_poly" if the point is on one of
poly's edges, or "inside" when in the interior.
- PolyTreeToPaths (poly_tree[, opts])
-
Converts a PolyTree structure into a Paths structure.
Parameters:
- poly_tree PolyTree
- opts
table
Options, which may include:
- out: If this is a Paths, it will be populated and used as the return value.
Returns:
- ReversePath (path)
-
Reverses the vertex order (and hence orientation) in the specified path.
Parameters:
- path Path
- ReversePaths (paths)
-
Reverses the vertex order (and hence orientation) in each contained path.
Parameters:
- paths Paths
- SimplifyPolygon (poly[, opts])
-
Removes self-intersections from the supplied polygon (by performing a boolean union operation using
the nominated PolyFillType). Polygons with non-contiguous duplicate vertices (i.e. 'touching') will
be split into two polygons.
Note: There's currently no guarantee that polygons will be strictly simple since 'simplifying' is still a work in progress.
See here for a couple visual examples.
Parameters:
- poly Path
- opts
table
Options, which may include:
- fill_type: Fill type for the union operation. (Default "EvenOdd")
- out: If this is a Paths, it will be populated and used as the return value.
Returns:
See also:
- SimplifyPolygons (polys[, opts])
-
Like SimplifyPolygon, but for multiple polygons.
Parameters:
- polys Paths
- opts table As per SimplifyPolygon. (optional)
Returns:
See also: