Clipper
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
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)
MethodsPolygon.new creates an empty polygon Polygon:addPoint appends a vertex to the polygon Clipper.new creates a new clipping engine Clipper:addSubjectPolygon adds a polygon to the subject set |
EventsConstantsThe 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 |