Clipper Module
The Clipper Module makes use of the Clipper library to perform line & polygon clipping. #Path and Point Definitions

Many Clipper functions will require or return a 'path.' In this context, a path will be a table of points. Each point (or vertex) of a path must be given in counter-clockwise fashion. A 'point' will be a table of x,y value pairs. Some functions will even use, or return, a table of paths. This may be a confusing explanation so a code example is given below.

Example: local point = {x = 5, y = 10}; -- This is a valid Clipper point local path = { -- This path creates a triangle; remember, counter-clockwise {x = 8, y = 8}, {x = 4, y = 4}, {x = 12, y = 4}, }; -- Two more paths. Also known as... polygons. local polygon1 = { {x = 4, y = 10}, {x = 4, y = 4}, {x = 5, y = 5}, {x = 5, y = 10}, } local polygon2 = { {x = 4, y = 7.5}, {x = 6, y = 6}, {x = 8, y = 12}, {x = 1, y = 8}, } local paths = { polygon1, polygon2, }
#clipper.getPointPrecision number clipper.getPointPrecision()

Returns the precision level used internally for scaling between floating-point numbers and integers (which the Clipper library uses for points). By default, this is 16384.0.

You may need to adjust this value based on the target application's scale. Large, open areas with little in between units of space probably don't need high precision, but instead may benefit from being able to span larger space. In 3D applications, the unit of space is arbitrary although many try to stick to 1 unit = 1 meter. Under this assumption, a game that takes place in outer space probably will not need high precision as you likely won't need to be tracking items down to the millimeter on this scale.

#clipper.setPointPrecision clipper.setPointPrecision(number newPrecision)

Sets the precision for scaling points (as described in getPointPrecision). While any non-zero number should work, it is recommended that you stick to power-of-two values to prevent lossy conversions. The underlying Clipper library uses integers to process points, however you probably will need floating-point numbers in your own project, and this number will aid in scaling between them.

The default value should be fine enough for most cases so you will likely never need this function. If, however, you need finer (more decimal places) precision, try increasing this number. If you instead need larger but less precise points, you might try lowering this number.

#clipper.offset table clipper.offset(table polygon, number offsetAmount) table clipper.offset(table polygon, number offsetAmount, string joinType)

"Offsets" (ie. scales/extrudes/shrinks/whatever) a polygon by some amount. If 'offsetAmount' is positive, the resulting polygon will be pushed outwards (become larger). If 'offsetAmount' is a negative number, the resulting polygon will instead be pushed inward (shrink).

By default, the 'joinType' is "miter". You may specify either "miter", "square" or "round" to determine how corners should be handled.

'polygon' should be a valid path. This function will return a table of paths, as self-intersection may occur, causing a polygon to be split into two separate polygons.

#clipper.merge table clipper.merge(table polygons, string clipType)

Performs a merge operation on a set of polygons. By default, 'clipType' is assumed to be "union" (combine overlapping polygons into one). You may alternatively specify a 'clipType' of "intersection" (solution will be a polygon of the area where input polygons were overlapping), "difference" (where the polygons are not overlapping), or "xor" (exclusive or, the area where one polygons or the other covers, but not both).

'polygons' will be, as you might expect, a table of paths you wish to apply the merge. This function will return a table of paths.

#clipper.clean table clipper.clean(table polygon) table clipper.clean(table polygon, number distance)

Cleans up a polygon by removing unnecessary vertices. As per the Clipper docs, it will remove vertices that:

  • 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

Simply put, it merges points that are too close together, removes dangling vertices, and simplifies vertices in a line into just one line.

This function accepts 'polygon' as a path and returns a single path (not a table of paths).

See the Clipper docs for more information.

#clipper.simplify table clipper.simplify(table polygon)

Simplifies a polygon. For example, a polygon that overlaps itself will instead be broken into two separate simple polygons.

'polygon' should be a valid path. This function will return a table of paths.

See the Clipper docs for more information.

#clipper.pointInPoly boolean inPoly, boolean onPoly clipper.pointInPoly(table point, table polygon)

Checks if a given point is inside (or on) a polygon. If the point is fully inside the given polygon, 'inPoly' (the first returned value) will be true. If the point is on a segment between two vertices, 'onPoly' (the second returned value) will also be true.

'polygon' should be a valid path, and point should of course be a valid point. Both return values will be boolean.

Page last updated at 2018-09-25 20:47:24


Copyright 2018