fix(face): Add core geometry properties to assist with DOE-2 translation

ladybug_geometry/geometry3d/face.py

@@ -85,7 +85,11 @@ class Face3D(Base2DIn3D):
         * upper_left_counter_clockwise_vertices
         * lower_left_counter_clockwise_vertices
         * lower_right_counter_clockwise_vertices
-        * upper_right_counter_clockwise_vertices
+        * upper_right_counter_clockwise_boundary
+        * upper_left_counter_clockwise_boundary
+        * lower_left_counter_clockwise_boundary
+        * lower_right_counter_clockwise_boundary
+        * upper_right_counter_clockwise_boundary
     """
     __slots__ = ('_plane', '_polygon2d', '_mesh2d', '_mesh3d',
                  '_boundary', '_holes', '_boundary_segments', '_hole_segments',
@@ -466,9 +470,14 @@ def azimuth(self):
 
     @property
     def altitude(self):
-        """Get the altitude of the Face3D (between Pi/2 and -Pi/2)."""
+        """Get the altitude of the Face3D. Between Pi/2 (up) and -Pi/2 (down)."""
         return self.plane.altitude
 
+    @property
+    def tilt(self):
+        """Get the tilt of the Face3D. Between 0 (up) and Pi (down)."""
+        return self.plane.tilt
+
     @property
     def is_clockwise(self):
         """Boolean for whether the face vertices and boundary are in clockwise order.
@@ -609,6 +618,50 @@ def upper_right_counter_clockwise_vertices(self):
         verts3d, verts2d = self._counter_clockwise_verts(polygon)
         return self._corner_pt_verts(corner_pt, verts3d, verts2d)
 
+    @property
+    def upper_left_counter_clockwise_boundary(self):
+        """Get face boundary starting from the upper left and moving counterclockwise.
+
+        Horizontal faces will treat the positive Y axis as up. All other faces
+        treat the positive Z axis as up.
+        """
+        corner_pt, polygon = self._corner_point_and_polygon(self._boundary, 'min', 'max')
+        verts3d, verts2d = self._counter_clockwise_verts(polygon)
+        return self._corner_pt_verts(corner_pt, verts3d, verts2d)
+
+    @property
+    def lower_left_counter_clockwise_boundary(self):
+        """Get face boundary starting from the lower left and moving counterclockwise.
+
+        Horizontal faces will treat the positive Y axis as up. All other faces
+        treat the positive Z axis as up.
+        """
+        corner_pt, polygon = self._corner_point_and_polygon(self._boundary, 'min', 'min')
+        verts3d, verts2d = self._counter_clockwise_verts(polygon)
+        return self._corner_pt_verts(corner_pt, verts3d, verts2d)
+
+    @property
+    def lower_right_counter_clockwise_boundary(self):
+        """Get face boundary starting from the lower left and moving counterclockwise.
+
+        Horizontal faces will treat the positive Y axis as up. All other faces
+        treat the positive Z axis as up.
+        """
+        corner_pt, polygon = self._corner_point_and_polygon(self._boundary, 'max', 'min')
+        verts3d, verts2d = self._counter_clockwise_verts(polygon)
+        return self._corner_pt_verts(corner_pt, verts3d, verts2d)
+
+    @property
+    def upper_right_counter_clockwise_boundary(self):
+        """Get face boundary starting from the lower left and moving counterclockwise.
+
+        Horizontal faces will treat the positive Y axis as up. All other faces
+        treat the positive Z axis as up.
+        """
+        corner_pt, polygon = self._corner_point_and_polygon(self._boundary, 'max', 'max')
+        verts3d, verts2d = self._counter_clockwise_verts(polygon)
+        return self._corner_pt_verts(corner_pt, verts3d, verts2d)
+
     def pole_of_inaccessibility(self, tolerance):
         """Get the pole of inaccessibility for the Face3D.
 

ladybug_geometry/geometry3d/plane.py

@@ -29,6 +29,7 @@ class Plane(object):
         * k
         * x
         * y
+        * tilt
         * altitude
         * azimuth
         * min
@@ -139,7 +140,10 @@ def y(self):
 
     @property
     def azimuth(self):
-        """Get the azimuth of the plane (between 0 and 2 * Pi).
+        """Get the azimuth of the plane.
+
+        This is always between 0, indicating the positive Y-axis, and moving clockwise
+        up to 2 * Pi, which indicates a return to the positive Y-axis.
 
         This will be zero if the plane is perfectly horizontal.
         """
@@ -153,11 +157,16 @@ def azimuth(self):
 
     @property
     def altitude(self):
-        """Get the altitude of the plane (between Pi/2 and -Pi/2)."""
+        """Get the altitude of the plane. Between Pi/2 (up) and -Pi/2 (down)."""
         if self._altitude is None:
             self._altitude = self.n.angle(Vector3D(0, 0, -1)) - math.pi / 2
         return self._altitude
 
+    @property
+    def tilt(self):
+        """Get the tilt of the plane. Between 0 (up) and Pi (down)."""
+        return abs(self.altitude - (math.pi / 2))
+
     @property
     def min(self):
         """Returns the Plane origin."""

tests/face3d_test.py

@@ -37,6 +37,7 @@ def test_face3d_init():
 
     assert face.area == 4
     assert face.perimeter == 8
+    assert round(face.tilt, 3) == 0
     assert round(face.altitude, 3) == round(math.pi / 2, 3)
     assert round(face.azimuth, 3) == 0
     assert face.is_clockwise is False
@@ -623,6 +624,7 @@ def test_upper_left_counter_clockwise_vertices():
     face_4 = Face3D(pts_2, plane_2, enforce_right_hand=False)
 
     up_cclock_1 = face_1.upper_left_counter_clockwise_vertices
+    assert up_cclock_1 == face_1.upper_left_counter_clockwise_boundary
     assert up_cclock_1[0] == Point3D(2, 0, 2)
     assert face_1.is_clockwise is True
     assert Face3D(up_cclock_1, enforce_right_hand=False).is_clockwise is False
@@ -651,6 +653,7 @@ def test_upper_left_counter_clockwise_vertices_triangle():
     face_2 = Face3D(pts_2, plane_1, enforce_right_hand=False)
 
     up_cclock_1 = face_1.upper_left_counter_clockwise_vertices
+    assert up_cclock_1 == face_1.upper_left_counter_clockwise_boundary
     assert up_cclock_1[0] == Point3D(0, 0, 2)
     assert face_1.is_clockwise is True
     assert Face3D(up_cclock_1, enforce_right_hand=False).is_clockwise is False