PolyTreeD

Ancestors

PolyPathBase
   |
PolyPathD


PolyTreeD is a read-only data structure that receives solutions from clipping operations. It's an alternative to the PathsD data structure which also receives solutions. However the principle advantage of PolyTreeD over PathsD is that it also represents the parent-child relationships of the polygons in the solution (where a parent's Polygon will contain all its children Polygons).

The PolyTreeD object that's to receive a clipping solution is passed as a parameter to ClipperD.Execute. When the clipping operation finishes, this object will be populated with data representing the clipped solution.

A PolyTreeD object is a container for any number of PolyPathD child objects, each representing a single polygon contour. Direct descendants of PolyTreeD will always be outer polygon contours. PolyPathD children may in turn contain their own children to any level of nesting. Children of outer polygon contours will always represent holes, and children of holes will always represent nested outer polygon contours.

PolyTreeD is a specialised PolyPathD object that's simply as a container for other PolyPathD objects and its own polygon property will always be empty.

PolyTreeD will never contain open paths (unlike in Clipper1) since open paths can't contain paths. When clipping open paths, these will always be represented in solutions via a separate PathsD structure.

Example1: 
  // create a very simple "subject" consisting of 
  // just 4 unnested polygons
  PathsD subject;
  subject.Add(MakePathD({10,10 40,10, 40,40, 10,40}));
  subject.Add(MakePathD({60,10 90,10, 90,40, 60,40}));
  subject.Add(MakePathD({10,60 40,60, 40,90, 10,90}));
  subject.Add(MakePathD({60,60 90,60, 90,90, 60,90}));
  
  // union "subject" and put the result into a polytree;
  PolyTreeD polytree;
  ClipperD cD;
  cD.AddSubject(subject);
  cD.Execute(ClipType.Union, FillRule.NonZero, polytree);
  
  // display polytree and its structure ...
      

    Polytree 1:
       +- Polygon
       +- Polygon
       +- Polygon
       +- Polygon

Example2: 
  // create "subject" consisting of multiple nested
  // polygon contours
  PathsD subject;
  subject.Add(MakePathD({0,0 100,0, 100,100, 0,100}));
  // add several holes (note reversed orientation)
  subject.Add(MakePathD({10,10 10,30, 25,30, 25,10}));
  subject.Add(MakePathD({40,10 40,30, 55,30, 55,10}));
  subject.Add(MakePathD({70,10 70,30, 85,30, 85,10}));
  subject.Add(MakePathD({10,40 10,90, 90,90, 90,40}));
  // add 2 nested outer polygons inside one of the holes
  subject.Add(MakePathD({20,45 80,45, 80,75, 20,75}));
  subject.Add(MakePathD({20,80 80,80, 80,85, 20,85}));
  // and holes inside one of these nested polygons
  subject.Add(MakePathD("30,50, 30,70, 45,70, 45,50"));
  subject.Add(MakePathD("55,50, 55,70, 70,70, 70,50"));
  
  // union "subject" and put the result into a polytree;
  PolyTreeD polytree;
  ClipperD cD;
  cD.AddSubject(subject);
  cD.Execute(ClipType.Union, FillRule.NonZero, polytree);
  
  // display polytree and its structure ...
      

    Polytree 2:
       +- Polygon with 4 holes.
          +- Hole with 2 nested polygons.
          |  +- Polygon
          |  +- Polygon with 2 holes.
          |     +- Hole
          |     +- Hole
          +- Hole
          +- Hole
          +- Hole

Note: Since the PolyTreeD's structure is much more complex than PathsD's structure, it'll take quite a bit longer to populate, so clipping operations will be roughly 10% slower. Because of this, it's better to use the PathsD structure in clipping operations unless the parent-child relationships of the returned polygons is important.

Reference

Methods Properties
In PolyPathD:
Clear Child
Count
IsHole
Level
Polygon

See Also

Overview, ClipperD.Execute, PolyTree64, PathsD