Class PolyTree
PolyTree is intended as a read-only data structure that should only be used to receive solutions from clipping and offsetting operations.
(Follow the link for a nice visual example.)
It's an alternative to the Paths data structure which also receives these solutions. PolyTree's two major advantages over
the Paths structure are: it properly represents the parent-child relationships of the returned polygons; it differentiates
between open and closed paths. However, since PolyTree is a more complex structure than the Paths structure, and
since it's more computationally expensive to process (the Execute method being roughly 5-10% slower), it should used only be
when parent-child polygon relationships are needed, or when open paths are being 'clipped'
.
An empty PolyTree object can be passed as the solution parameter in Clipper:Execute and in Offset:Execute. Once the clipping or offseting operation is completed, the method returns with the PolyTree structure filled with data representing the solution.
A PolyTree object is a container for any number of PolyNode children, with each contained PolyNode representing a single polygon contour
(either an outer or hole polygon). PolyTree itself is a specialized PolyNode whose immediate children represent the top-level outer polygons of the
solution. (Its own
Contour property is always empty.)
The contained top-level PolyNodes may contain their own PolyNode
children representing hole polygons that may also contain children representing nested outer polygons etc. Children of outers will always be holes,
and children of holes will always be outers.
PolyTrees can also contain open paths. Open paths will always be represented by top level PolyNodes. Two functions are provided to quickly separate out open and closed paths from a polytree — OpenPathsFromPolyTree and ClosedPathsFromPolyTree.
Derives from PolyNode and thus has all its methods.
Methods
- PolyTree:GetFirst ([opts])
-
This is almost equivalent to
tree:GetChild(1)
except that when a PolyTree object is empty (has no children), calling that would throw an error.Parameters:
- opts
table
Options, which include:
- out: If this is a PolyNode, it will be populated and used as the return value.
Returns:
-
PolyNode or nil
First outer polygon contour if any, otherwise nil.
See also:
- opts
table
- PolyTree:Total ()
-
Returns:
-
uint
The total number of PolyNodes (polygons) contained within the PolyTree. This value is not to be confused
with PolyNode:ChildCount which returns the number of immediate children only (Childs) contained by PolyTree.