Clipper: Difference between revisions

From GiderosMobile
wip
No edit summary
 
(7 intermediate revisions by the same user not shown)
Line 17: Line 17:


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.
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 ===
=== Example ===
'''Boolean operations on two polygons'''
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
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)
</syntaxhighlight>
</syntaxhighlight>


Line 25: Line 66:
| style="width: 50%; vertical-align:top;"|
| style="width: 50%; vertical-align:top;"|
=== Methods ===
=== Methods ===
[[Clipper.Polygon.new]] ''creates an empty polygon''<br/><!--GIDEROSMTD:Polygon.new() creates an empty polygon-->
[[Polygon.new]] ''creates an empty polygon''<br/><!--GIDEROSMTD:Polygon.new() creates an empty polygon-->
[[Clipper.Polygon:addPoint]] ''appends a vertex to the polygon''<br/><!--GIDEROSMTD:Polygon:addPoint(x, y) appends a vertex to the polygon-->
 
[[Clipper.Polygon:getPoints]] ''returns all vertices of the polygon as a Lua table''<br/><!--GIDEROSMTD:Polygon:getPoints() returns all vertices of the polygon as a Lua table-->
[[Polygon:addPoint]] ''appends a vertex to the polygon''<br/><!--GIDEROSMTD:Polygon:addPoint(x, y) appends a vertex to the polygon-->
[[Clipper.Polygon:getArea]] ''returns the signed area of the polygon''<br/><!--GIDEROSMTD:Polygon:getArea() returns the signed area of the polygon-->
[[Polygon:clean]] ''removes self-intersections and very close vertices from the polygon in place''<br/><!--GIDEROSMTD:Polygon:clean(distance) removes self-intersections and very close vertices from the polygon in place-->
[[Clipper.Polygon:isClockwise]] ''returns the orientation of the polygon''<br/><!--GIDEROSMTD:Polygon:isClockwise() returns the orientation of the polygon-->
[[Polygon:getArea]] ''returns the signed area of the polygon''<br/><!--GIDEROSMTD:Polygon:getArea() returns the signed area of the polygon-->
[[Clipper.Polygon:clean]] ''removes self-intersections and very close vertices from the polygon in place''<br/><!--GIDEROSMTD:Polygon:clean(distance) removes self-intersections and very close vertices from the polygon in place-->
[[Polygon:getLineOffset]] ''offsets an open polyline (a polygon treated as an open path) by delta units, producing one or more parallel polylines''<br/><!--GIDEROSMTD:Polygon:getLineOffset(delta, joinType, endType, limit) offsets an open polyline (a polygon treated as an open path) by delta units, producing one or more parallel polylines-->
[[Clipper.Polygon:reverse]] ''reverses the order of the vertices in place, which flips the orientation of the polygon''<br/><!--GIDEROSMTD:Polygon:reverse() reverses the order of the vertices in place, which flips the orientation of the polygon-->
[[Polygon:getPoints]] ''returns all vertices of the polygon as a Lua table''<br/><!--GIDEROSMTD:Polygon:getPoints() returns all vertices of the polygon as a Lua table-->
[[Polygon:getPolygonOffset]] ''offsets (insets or outsets) the polygon by delta units''<br/><!--GIDEROSMTD:Polygon:getPolygonOffset(delta, joinType, limit, autoFix) offsets (insets or outsets) the polygon by delta units-->
[[Polygon:isClockwise]] ''returns the orientation of the polygon''<br/><!--GIDEROSMTD: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''<br/><!--GIDEROSMTD: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''<br/><!--GIDEROSMTD:Polygon:simplify(fillType) simplifies the polygon by removing redundant vertices and resolving self-intersections, using the given fill rule-->
----
[[Clipper.new]] ''creates a new clipping engine''<br/><!--GIDEROSMTD:Clipper.new() creates a new clipping engine-->
 
[[Clipper:addClipPolygon]] ''adds a polygon to the clip set''<br/><!--GIDEROSMTD:Clipper:addClipPolygon(poly) adds a polygon to the clip set-->
[[Clipper:addSubjectPolygon]] ''adds a polygon to the subject set''<br/><!--GIDEROSMTD:Clipper:addSubjectPolygon(poly) adds a polygon to the subject set-->
[[Clipper:clear]] ''removes all subject and clip polygons from the engine''<br/><!--GIDEROSMTD:Clipper:clear() removes all subject and clip polygons from the engine-->
[[Clipper:getBounds]] ''returns the bounding rectangle of all polygons added to the engine''<br/><!--GIDEROSMTD:Clipper:getBounds() returns the bounding rectangle of all polygons added to the engine-->
[[Clipper:getDifference]] ''computes the subject polygons minus the clip polygons''<br/><!--GIDEROSMTD:Clipper:getDifference(fillType1, fillType2) computes the subject polygons minus the clip polygons-->
[[Clipper:getExclusion]] ''computes the symmetric difference (XOR) of the subject and clip polygons''<br/><!--GIDEROSMTD:Clipper:getExclusion(fillType1, fillType2) computes the symmetric difference (XOR) of the subject and clip polygons-->
[[Clipper:getIntersection]] ''computes the intersection of the subject and clip polygons''<br/><!--GIDEROSMTD:Clipper:getIntersection(fillType1, fillType2) computes the intersection of the subject and clip polygons-->
[[Clipper:getUnion]] ''computes the union of the subject and clip polygons''<br/><!--GIDEROSMTD:Clipper:getUnion(fillType1, fillType2) computes the union of the subject and clip polygons-->


| style="width: 50%; vertical-align:top;"|
| style="width: 50%; vertical-align:top;"|
=== Events ===
=== Events ===
[[Event.CONNECTED]]<br/><!--GIDEROSEVT:Event.CONNECTED connected-->
=== Constants ===
=== Constants ===
The following constants are fields of the Polygon table.
Fill rules (PolyFillType):
Polygon.FILL_EVEN_ODD<!--GIDEROSCST:Polygon.FILL_EVEN_ODD even-odd rule-->
Polygon.FILL_NON_ZERO<!--GIDEROSCST:Polygon.FILL_EVEN_ODD non-zero winding rule-->
Polygon.FILL_POSITIVE<!--GIDEROSCST:Polygon.FILL_EVEN_ODD positive winding rule-->
Polygon.FILL_NEGATIVE<!--GIDEROSCST:Polygon.FILL_EVEN_ODD negative winding rule-->
Join types (JoinType), used by getPolygonOffset and getLineOffset:
Polygon.JOINT_SQUARE<!--GIDEROSCST:Polygon.JOINT_SQUARE square (mitered) joins-->
Polygon.JOINT_ROUND<!--GIDEROSCST:Polygon.JOINT_SQUARE square (mitered) rounded joins-->
Polygon.JOINT_MITER<!--GIDEROSCST:Polygon.JOINT_SQUARE square (mitered) mitered joins-->
End types (EndType), used by getLineOffset:
Polygon.END_CLOSED<!--GIDEROSCST:Polygon.JOINT_SQUARE square (mitered) closed path-->
Polygon.END_BUTT<!--GIDEROSCST:Polygon.JOINT_SQUARE square (mitered) butt end-->
Polygon.END_SQUARE<!--GIDEROSCST:Polygon.JOINT_SQUARE square (mitered) square end-->
Polygon.END_ROUND<!--GIDEROSCST:Polygon.JOINT_SQUARE square (mitered) rounded end-->
|}
|}


{{GIDEROS IMPORTANT LINKS}}
{{GIDEROS IMPORTANT LINKS}}

Latest revision as of 22:12, 14 November 2026

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