fix(face): Add a method to separate Face3D boundary and holes

This will be used in the importers from IDF, OSM, and gbXML, which all represent Faces with a single flat list of vertices.

Author: chriswmackey

ladybug_geometry/geometry3d/face.py

@@ -1002,6 +1002,78 @@ def remove_colinear_vertices(self, tolerance):
         _new_face = Face3D(_boundary, self.plane, _holes, enforce_right_hand=False)
         return _new_face
 
+    def separate_boundary_and_holes(self, tolerance):
+        """Get a version of this face with boundaries and holes separated.
+
+        This method is intended for the case that a Face3D has been imported from
+        a format where everything was collapsed into a single list of vertices.
+        As such, the Face3D.boundary includes both the real shape boundary and the
+        holes by winding inward to cut them out.
+
+        Args:
+            tolerance: The minimum distance between vertices at which point they are
+                considered equivalent.
+        """
+        # first check the holes are not already separated
+        if self.has_holes:
+            return self
+        # loop through the vertices and identify pairs of duplicate vertices
+        boundary, all_holes = self.boundary, []
+        iter_count, max_holes = 0, int(len(boundary) / 3)
+        while iter_count < max_holes:
+            boundary, hole = self._separate_inner_most_hole(boundary, tolerance)
+            if hole is None:
+                break
+            else:
+                all_holes.append(hole)
+            iter_count += 1
+        return Face3D(boundary, self.plane, all_holes)
+
+    @staticmethod
+    def _separate_inner_most_hole(vertices, tolerance):
+        """Separate the inner-most hole from a list of flat vertices:
+
+        Args:
+            vertices: A flat list of Point3D.
+            tolerance: The minimum distance between vertices at which point they are
+                considered equivalent.
+
+        Returns:
+             A tuple with two elements
+
+            -   remain_vertices: A list of Point3D with the inner-most hole
+                separated from it.
+
+            -   hole: A list of Point3D for the inner-most hole. Will be None
+                if the input vertices had no hole.
+        """
+        # loop through the vertices and identify pairs of duplicate vertices
+        dup_pairs, all_dups = [], set()
+        for i, pt in enumerate(vertices):
+            if i in all_dups:
+                continue
+            if i + 2 >= len(vertices):
+                break
+            for j in range(i + 2, len(vertices)):
+                if pt.is_equivalent(vertices[j], tolerance):
+                    dup_pairs.append((i, j))
+                    all_dups.add(i)
+                    all_dups.add(j)
+                    break
+        if len(dup_pairs) == 0:
+            return vertices, None  # no holes were detected
+        # find the duplicate pair with no other duplicates between them (inner most)
+        for pair_low, pair_high in dup_pairs:
+            for btw_pt_i in range(pair_low + 1, pair_high):
+                if btw_pt_i in all_dups:
+                    break  # not an inner-most hole
+            else:
+                break  # the current pair is an inner-most one
+        # separate the inner-most hole from the boundary
+        hole = vertices[pair_low:pair_high]
+        remain_vertices = vertices[:pair_low] + vertices[pair_high + 2:]
+        return remain_vertices, hole
+
     def flip(self):
         """Get a face with a flipped direction from this one."""
         _new_face = Face3D(reversed(self.vertices), self.plane.flip(),

tests/face3d_test.py

@@ -791,6 +791,33 @@ def test_remove_colinear_vertices_custom():
     assert len(face_geo.remove_colinear_vertices(0.0001).vertices) == 16
 
 
+def test_separate_boundary_and_holes():
+    """Test the separate_boundary_and_holes."""
+    bound_pts = [Point3D(0, 0), Point3D(4, 0), Point3D(4, 4), Point3D(0, 4)]
+    hole_pts_1 = [Point3D(1, 1), Point3D(1.5, 1), Point3D(1.5, 1.5), Point3D(1, 1.5)]
+    hole_pts_2 = [Point3D(2, 2), Point3D(3, 2), Point3D(3, 3), Point3D(2, 3)]
+    face_1 = Face3D(bound_pts)
+    face_2 = Face3D(Face3D(bound_pts, None, [hole_pts_2]).vertices)
+    face_3 = Face3D(Face3D(bound_pts, None, [hole_pts_1, hole_pts_2]).vertices)
+
+    clean_face_1 = face_1.separate_boundary_and_holes(0.01)
+    assert len(clean_face_1.boundary) == 4
+    assert not clean_face_1.has_holes
+
+    clean_face_2 = face_2.separate_boundary_and_holes(0.01)
+    assert len(clean_face_2.boundary) == 4
+    assert len(clean_face_2.holes) == 1
+    assert len(clean_face_2.holes[0]) == 4
+    assert clean_face_2.area == face_2.area
+
+    clean_face_3 = face_3.separate_boundary_and_holes(0.01)
+    assert len(clean_face_3.boundary) == 4
+    assert len(clean_face_3.holes) == 2
+    assert len(clean_face_3.holes[0]) == 4
+    assert len(clean_face_3.holes[1]) == 4
+    assert clean_face_3.area == face_3.area
+
+
 def test_triangulated_mesh_and_centroid():
     """Test the triangulation properties of Face3D."""
     pts_1 = (Point3D(0, 0, 2), Point3D(2, 0, 2), Point3D(2, 2, 2), Point3D(0, 2, 2))