Clipper

From GiderosMobile

Supported platforms:
Available since: Gideros 2015.03.22

Description

The Clipper plugin wraps the Clipper polygon clipping library for Gideros.

require "clipper"

Enable Clipper in Gideros Studio -> Plugins before use. This makes the two classes Polygon and Clipper available as globals.

It provides two classes:

  • Polygon: a single polygon (a list of integer points). It can be created, edited, measured, cleaned, reversed, simplified and offset (inset/outset)
  • Clipper: a clipping engine that combines one or more subject polygons with one or more clip polygons using boolean operations (intersection, union, difference, exclusion)

All coordinates are integers. The plugin registers a weak table that keeps the C++ objects alive as long as their Lua wrappers exist, so polygons and clippers are garbage collected automatically.

Notes

  • Coordinates are integers. Fractional values passed to addPoint are truncated to integers by the C++ binding
  • Polygons are implicitly closed: the last vertex connects back to the first. getArea(), simplify() and the Clipper operations all assume closed polygons
  • clean(), reverse() and the offset methods that return a single polygon modify or replace data in place where stated; offset and simplify always return new Polygon objects and never modify the original
  • Offset and simplify can produce several polygons (for example when a polygon splits into multiple parts); always iterate over the returned table
  • getPolygonOffset currently ignores its joinType argument and always uses square joins, because of a bug in the C++ binding
  • The Clipper engine keeps references to the polygons added to it, so they must not be garbage collected before execute is called. In practice the Lua wrappers stay alive as long as you hold them
  • Boolean operations on empty polygon sets return an empty table, they do not raise an error
  • Fill rules follow the Clipper library conventions; FILL_EVEN_ODD and FILL_NON_ZERO are the most commonly used

Full Demo

Clipper Demo

Example

Boolean operations on two polygons

require "clipper"

local subject = Polygon.new()
subject:addPoint(0, 0)
subject:addPoint(200, 0)
subject:addPoint(200, 200)
subject:addPoint(0, 200)

local clip = Polygon.new()
clip:addPoint(100, 50)
clip:addPoint(250, 150)
clip:addPoint(100, 250)
clip:addPoint(-50, 150)

local c = Clipper.new()
c:addSubjectPolygon(subject)
c:addClipPolygon(clip)

local inter = c:getIntersection(Polygon.FILL_EVEN_ODD, Polygon.FILL_EVEN_ODD)
local uni   = c:getUnion(Polygon.FILL_EVEN_ODD, Polygon.FILL_EVEN_ODD)
local diff  = c:getDifference(Polygon.FILL_EVEN_ODD, Polygon.FILL_EVEN_ODD)
local xor   = c:getExclusion(Polygon.FILL_EVEN_ODD, Polygon.FILL_EVEN_ODD)

print("intersection polygons:", #inter)
print("union polygons:", #uni)
print("difference polygons:", #diff)
print("exclusion polygons:", #xor)

Methods

Polygon.new creates an empty polygon

Polygon:addPoint appends a vertex to the polygon
Polygon:clean removes self-intersections and very close vertices from the polygon in place
Polygon:getArea returns the signed area of the polygon
Polygon:getLineOffset offsets an open polyline (a polygon treated as an open path) by delta units, producing one or more parallel polylines
Polygon:getPoints returns all vertices of the polygon as a Lua table
Polygon:getPolygonOffset offsets (insets or outsets) the polygon by delta units
Polygon:isClockwise returns the orientation of the polygon
Polygon:reverse reverses the order of the vertices in place, which flips the orientation of the polygon
Polygon:simplify simplifies the polygon by removing redundant vertices and resolving self-intersections, using the given fill rule


Clipper.new creates a new clipping engine

Clipper:addClipPolygon adds a polygon to the clip set
Clipper:addSubjectPolygon adds a polygon to the subject set
Clipper:clear removes all subject and clip polygons from the engine
Clipper:getBounds returns the bounding rectangle of all polygons added to the engine
Clipper:getDifference computes the subject polygons minus the clip polygons
Clipper:getExclusion computes the symmetric difference (XOR) of the subject and clip polygons
Clipper:getIntersection computes the intersection of the subject and clip polygons
Clipper:getUnion computes the union of the subject and clip polygons

Events

Constants

The following constants are fields of the Polygon table.

Fill rules (PolyFillType):

Polygon.FILL_EVEN_ODD
Polygon.FILL_NON_ZERO
Polygon.FILL_POSITIVE
Polygon.FILL_NEGATIVE

Join types (JoinType), used by getPolygonOffset and getLineOffset:

Polygon.JOINT_SQUARE
Polygon.JOINT_ROUND
Polygon.JOINT_MITER

End types (EndType), used by getLineOffset:

Polygon.END_CLOSED
Polygon.END_BUTT
Polygon.END_SQUARE
Polygon.END_ROUND