ClipperLib

A PolyTree is a read-only data structure used to receive solutions from polygon clipping operations. It is an alternative to the Paths structure.

**Use PolyTree when you need to:

1. Represent parent-child relationships between polygons (e.g., knowing which hole belongs to which outer polygon).
2. Differentiate between open and closed paths.

Note on Performance: PolyTree is more computationally expensive than Paths. The Execute method using a PolyTree is roughly 5-10% slower. Use it only when the hierarchical relationship or open paths are required.

In Clipper, PolyNode objects are used to represent individual polygons within a PolyTree container. This structure preserves the parent-child relationships of polygon contours returned by the Clipper.Execute method.

Key Concepts:

• Hierarchy: A PolyNode can own multiple child PolyNode objects. The relationship alternates: children of outer polygons are holes, and children of holes are nested outer polygons.
• IsHole: The IsHole() property indicates if the polygon is a hole or an outer polygon.
• PolyTree Root: A PolyTree object is itself a PolyNode (the root), but its IsHole() property is undefined. Its children are always top-level outer polygons.

// Example of the hierarchical relationship
// Outer Polygon -> Hole -> Nested Outer Polygon

The library uses two fundamental structures to manage geometry:

1. Path: A sequence of IntPoint vertices defining a single contour. Paths can be open (representing line segments with 2+ vertices) or closed (representing polygons).
2. Paths: An array of one or more Path structures. This is the primary container for multiple contours.

In JavaScript, both can be initialized as empty arrays [] or via their respective constructors.

// Creating a Path (single contour)
var path = new ClipperLib.Path(); 
// or
var path = [];

// Creating Paths (multiple contours)
var paths = new ClipperLib.Paths();
// or
var paths = [];

A PolyTree acts as a container for PolyNode children.

• Hierarchy: The PolyTree itself is a specialized PolyNode with an empty Contour. Its immediate children are top-level outer polygons.
• Nesting Rules: Children of outer polygons are always holes, and children of holes are always outers. This creates a nested tree structure.
• Open Paths: Open paths are always represented by top-level PolyNodes.
• Separation: You can use ClosedPathsFromPolyTree and OpenPathsFromPolyTree to quickly separate closed and open paths from a single PolyTree.

You can easily traverse all nodes in a PolyTree by starting with GetFirst() and following the GetNext() pointers in a loop until you reach a null pointer. GetNext() returns the first child if one exists; otherwise, it returns the next sibling, or the next sibling of the parent, and so on.

var polytree = new ClipperLib.PolyTree();
// call to Clipper.Execute method here which fills 'polytree'

var polynode = polytree.GetFirst();
while (polynode)
{
  // do stuff with polynode here

  polynode = polynode.GetNext();
}

You can control certain library behaviors by setting specific boolean variables. Note that these are implemented as variables in the Javascript environment.

• use_xyz: Adds a 'Z' member to IntPoint. Useful for 3D-related logic but has a minor performance cost. (Disabled by default)
• use_lines: Enables open path (line) clipping. Disabling this can provide a ~5% performance improvement if you only work with closed polygons. (Enabled by default)
• use_deprecated: Enables compatibility code for projects migrating from versions prior to Clipper 6. (Enabled by default)
• use_int32: Not implemented in the Javascript version.

var use_xyz = true;
var use_lines = true;
var use_deprecated = true;

Calculates the perimeter of paths. If a scale is provided, the function returns the downscaled perimeter.

• PerimeterOfPath(path, closed, scale):
  • If closed is true (polygon), it treats the path as closed by connecting the last vertex to the first.
  • If closed is false (line), it measures only the existing vertices.
• PerimeterOfPaths(paths, closed, scale): Returns the sum of perimeters for all paths in the collection.

var path = [{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}];
var polygonal_perimeter = ClipperLib.JS.PerimeterOfPath(path, true, 1);
// polygonal_perimeter is 400

var line_perimeter = ClipperLib.JS.PerimeterOfPath(path, false, 1);
// line_perimeter is 300