Clipper Module

From SolarStrike wiki
Jump to: navigation, search

The Clipper module makes use of the Clipper library[1]

Path & 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.

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,
}


Module functions

getPointPrecision

number clipper.getPointPrecision()

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


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.


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'[2] is "miter". You may specify either "miter", "square" or "round" or 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.


merge

table clipper.merge(table polygons) 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.


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[3] for more information.


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[4] for more information.


pointInPoly

inPoly, 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' will be true. If the point is on a segment between two vertices, 'onPoly' will also be true.

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