fix: trapezoid signature change and internal checks (#1354)

Co-authored-by: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com>

Author: RobPasMue

.github/workflows/ci_cd.yml

@@ -17,7 +17,7 @@ env:
   ANSRV_GEO_PORT: 700
   ANSRV_GEO_LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}
   GEO_CONT_NAME: ans_geo
-  RESET_IMAGE_CACHE: 2
+  RESET_IMAGE_CACHE: 3
   IS_WORKFLOW_RUNNING: True
   ARTIFACTORY_VERSION: v251
   MEILISEARCH_API_KEY: ${{ secrets.MEILISEARCH_API_KEY }}

doc/changelog.d/1354.fixed.md

@@ -0,0 +1 @@
+trapezoid signature change and internal checks

src/ansys/geometry/core/sketch/sketch.py

@@ -582,40 +582,49 @@ def triangle(
 
     def trapezoid(
         self,
-        width: Quantity | Distance | Real,
+        base_width: Quantity | Distance | Real,
         height: Quantity | Distance | Real,
-        slant_angle: Quantity | Angle | Real,
-        nonsymmetrical_slant_angle: Quantity | Angle | Real | None = None,
+        base_angle: Quantity | Angle | Real,
+        base_asymmetric_angle: Quantity | Angle | Real | None = None,
         center: Point2D = ZERO_POINT2D,
         angle: Quantity | Angle | Real = 0,
         tag: str | None = None,
     ) -> "Sketch":
-        """Add a triangle to the sketch using given vertex points.
+        """Add a trapezoid to the sketch using given vertex points.
 
         Parameters
         ----------
-        width : ~pint.Quantity | Distance | Real
-            Width of the slot main body.
+        base_width : ~pint.Quantity | Distance | Real
+            Width of the lower base of the trapezoid.
         height : ~pint.Quantity | Distance | Real
             Height of the slot.
-        slant_angle : ~pint.Quantity | Distance | Real
-            Angle for trapezoid generation.
-        nonsymmetrical_slant_angle : ~pint.Quantity | Angle | Real | None, default: None
-            Asymmetrical slant angles on each side of the trapezoid.
-            The default is ``None``, in which case the trapezoid is symmetrical.
-        center : Point2D, default: (0, 0)
+        base_angle : ~pint.Quantity | Distance | Real
+            Angle for trapezoid generation. Represents the angle
+            on the base of the trapezoid.
+        base_asymmetric_angle : ~pint.Quantity | Angle | Real | None, default: None
+            Asymmetrical angles on each side of the trapezoid.
+            The default is ``None``, in which case the trapezoid is symmetrical. If
+            provided, the trapezoid is asymmetrical and the right corner angle
+            at the base of the trapezoid is set to the provided value.
+        center: Point2D, default: ZERO_POINT2D
             Center point of the trapezoid.
         angle : ~pint.Quantity | Angle | Real, default: 0
             Placement angle for orientation alignment.
         tag : str, default: None
             User-defined label for identifying the face.
 
+        Notes
+        -----
+        If an asymmetric base angle is defined, the base angle is
+        applied to the left-most angle, and the asymmetric base angle
+        is applied to the right-most angle.
+
         Returns
         -------
         Sketch
             Revised sketch state ready for further sketch actions.
         """
-        trapezoid = Trapezoid(width, height, slant_angle, nonsymmetrical_slant_angle, center, angle)
+        trapezoid = Trapezoid(base_width, height, base_angle, base_asymmetric_angle, center, angle)
         return self.face(trapezoid, tag)
 
     def circle(

src/ansys/geometry/core/sketch/trapezoid.py

@@ -27,6 +27,7 @@
 import pyvista as pv
 from scipy.spatial.transform import Rotation as SpatialRotation
 
+from ansys.geometry.core.logger import LOG
 from ansys.geometry.core.math.constants import ZERO_POINT2D
 from ansys.geometry.core.math.matrix import Matrix33
 from ansys.geometry.core.math.point import Point2D
@@ -42,45 +43,57 @@ class Trapezoid(SketchFace):
 
     Parameters
     ----------
-    width : ~pint.Quantity | Distance | Real
-        Width of the trapezoid.
+    base_width : ~pint.Quantity | Distance | Real
+        Width of the lower base of the trapezoid.
     height : ~pint.Quantity | Distance | Real
-        Height of the trapezoid.
-    slant_angle : ~pint.Quantity | Angle | Real
-        Angle for trapezoid generation.
-    nonsymmetrical_slant_angle : ~pint.Quantity | Angle | Real | None, default: None
-        Asymmetrical slant angles on each side of the trapezoid.
-        The default is ``None``, in which case the trapezoid is symmetrical.
+        Height of the slot.
+    base_angle : ~pint.Quantity | Distance | Real
+        Angle for trapezoid generation. Represents the angle
+        on the base of the trapezoid.
+    base_asymmetric_angle : ~pint.Quantity | Angle | Real | None, default: None
+        Asymmetrical angles on each side of the trapezoid.
+        The default is ``None``, in which case the trapezoid is symmetrical. If
+        provided, the trapezoid is asymmetrical and the right corner angle
+        at the base of the trapezoid is set to the provided value.
     center: Point2D, default: ZERO_POINT2D
         Center point of the trapezoid.
     angle : ~pint.Quantity | Angle | Real, default: 0
         Placement angle for orientation alignment.
 
     Notes
     -----
-    If a nonsymmetrical slant angle is defined, the slant angle is
-    applied to the left-most angle, and the nonsymmetrical slant angle
+    If an asymmetric base angle is defined, the base angle is
+    applied to the left-most angle, and the asymmetric base angle
     is applied to the right-most angle.
     """
 
     @check_input_types
     def __init__(
         self,
-        width: Quantity | Distance | Real,
+        base_width: Quantity | Distance | Real,
         height: Quantity | Distance | Real,
-        slant_angle: Quantity | Angle | Real,
-        nonsymmetrical_slant_angle: Quantity | Angle | Real | None = None,
+        base_angle: Quantity | Angle | Real,
+        base_asymmetric_angle: Quantity | Angle | Real | None = None,
         center: Point2D = ZERO_POINT2D,
         angle: Quantity | Angle | Real = 0,
     ):
         """Initialize the trapezoid."""
         super().__init__()
 
+        # TODO: Remove this warning in the next major release (v0.8.0)
+        # https://github.com/ansys/pyansys-geometry/issues/1359
+        LOG.warning(
+            "The signature of the Trapezoid class has changed starting on"
+            "version 0.7.X. Please refer to the documentation for more information."
+        )
+
         self._center = center
-        self._width = width if isinstance(width, Distance) else Distance(width, center.unit)
-        if self._width.value <= 0:
-            raise ValueError("Width must be a real positive value.")
-        width_magnitude = self._width.value.m_as(center.unit)
+        self._base_width = (
+            base_width if isinstance(base_width, Distance) else Distance(base_width, center.unit)
+        )
+        if self._base_width.value <= 0:
+            raise ValueError("Base width must be a real positive value.")
+        width_magnitude = self._base_width.value.m_as(center.unit)
 
         self._height = height if isinstance(height, Distance) else Distance(height, center.unit)
         if self._height.value <= 0:
@@ -91,21 +104,42 @@ def __init__(
             angle = Angle(angle, DEFAULT_UNITS.ANGLE)
         angle = angle if isinstance(angle, Angle) else Angle(angle, angle.units)
 
-        if isinstance(slant_angle, (int, float)):
-            slant_angle = Angle(slant_angle, DEFAULT_UNITS.ANGLE)
-        slant_angle = (
-            slant_angle if isinstance(slant_angle, Angle) else Angle(slant_angle, slant_angle.units)
+        if isinstance(base_angle, (int, float)):
+            base_angle = Angle(base_angle, DEFAULT_UNITS.ANGLE)
+        base_angle = (
+            base_angle if isinstance(base_angle, Angle) else Angle(base_angle, base_angle.units)
         )
 
-        if nonsymmetrical_slant_angle is None:
-            nonsymmetrical_slant_angle = slant_angle
+        if base_asymmetric_angle is None:
+            base_asymmetric_angle = base_angle
         else:
-            if isinstance(nonsymmetrical_slant_angle, (int, float)):
-                nonsymmetrical_slant_angle = Angle(nonsymmetrical_slant_angle, DEFAULT_UNITS.ANGLE)
-            nonsymmetrical_slant_angle = (
-                nonsymmetrical_slant_angle
-                if isinstance(nonsymmetrical_slant_angle, Angle)
-                else Angle(nonsymmetrical_slant_angle, nonsymmetrical_slant_angle.units)
+            if isinstance(base_asymmetric_angle, (int, float)):
+                base_asymmetric_angle = Angle(base_asymmetric_angle, DEFAULT_UNITS.ANGLE)
+            base_asymmetric_angle = (
+                base_asymmetric_angle
+                if isinstance(base_asymmetric_angle, Angle)
+                else Angle(base_asymmetric_angle, base_asymmetric_angle.units)
+            )
+
+        # SANITY CHECK: Ensure that the angles are valid (i.e. between 0 and 180 degrees)
+        for trapz_angle in [base_angle, base_asymmetric_angle]:
+            if (
+                trapz_angle.value.m_as(UNITS.radian) < 0
+                or trapz_angle.value.m_as(UNITS.radian) > np.pi
+            ):
+                raise ValueError("The trapezoid angles must be between 0 and 180 degrees.")
+
+        # Check that the sum of both angles is larger than 90 degrees
+        base_offset_right = height_magnitude / np.tan(
+            base_asymmetric_angle.value.m_as(UNITS.radian)
+        )
+        base_offset_left = height_magnitude / np.tan(base_angle.value.m_as(UNITS.radian))
+
+        # SANITY CHECK: Ensure that the trapezoid is not degenerate
+        if base_offset_right + base_offset_left >= width_magnitude:
+            raise ValueError(
+                "The trapezoid is degenerate. "
+                "The provided angles, width and height do not form a valid trapezoid."
             )
 
         rotation = Matrix33(
@@ -119,14 +153,12 @@ def __init__(
         rotated_point_1 = rotation @ [center.x.m - half_w, center.y.m - half_h, 0]
         rotated_point_2 = rotation @ [center.x.m + half_w, center.y.m - half_h, 0]
         rotated_point_3 = rotation @ [
-            center.x.m - half_w + height_magnitude / np.tan(slant_angle.value.m_as(UNITS.radian)),
+            center.x.m + half_w - base_offset_right,
             center.y.m + half_h,
             0,
         ]
         rotated_point_4 = rotation @ [
-            center.x.m
-            + half_w
-            - height_magnitude / np.tan(nonsymmetrical_slant_angle.value.m_as(UNITS.radian)),
+            center.x.m - half_w + base_offset_left,
             center.y.m + half_h,
             0,
         ]
@@ -154,9 +186,9 @@ def center(self) -> Point2D:
         return self._center
 
     @property
-    def width(self) -> Quantity:
+    def base_width(self) -> Quantity:
         """Width of the trapezoid."""
-        return self._width.value
+        return self._base_width.value
 
     @property
     def height(self) -> Quantity:

tests/integration/test_plotter.py

@@ -365,11 +365,24 @@ def test_plot_trapezoid(verify_image_cache):
     sketch = Sketch()
 
     # Create a trapezoid and plot
-    sketch.trapezoid(10, 8, np.pi / 4, np.pi / 8, Point2D([10, -10]), tag="Trapezoid")
+    sketch.trapezoid(10, 2, np.pi / 4, np.pi / 8, Point2D([10, -10]), tag="Trapezoid")
     sketch.select("Trapezoid")
     sketch.plot_selection(view_2d=True, screenshot=Path(IMAGE_RESULTS_DIR, "plot_trapezoid.png"))
 
 
+def test_plot_trapezoid_symmetric(verify_image_cache):
+    """Test plotting of a trapezoid which is symmetric."""
+    # Create a sketch instance
+    sketch = Sketch()
+
+    # Create a trapezoid and plot
+    sketch.trapezoid(10, 2, np.pi / 4, tag="Trapezoid-symmetric")
+    sketch.select("Trapezoid-symmetric")
+    sketch.plot_selection(
+        view_2d=True, screenshot=Path(IMAGE_RESULTS_DIR, "plot_trapezoid_sym.png")
+    )
+
+
 @skip_no_xserver
 def test_plot_circle(verify_image_cache):
     """Test plotting of a circle."""
@@ -601,14 +614,14 @@ def test_visualization_polydata():
     assert triangle.visualization_polydata.n_open_edges == 3
 
     # Test for trapezoid visualization polydata
-    trapezoid = Trapezoid(10, 8, np.pi / 4, np.pi / 8, Point2D([10, -10]))
+    trapezoid = Trapezoid(10, 2, np.pi / 4, np.pi / 8, Point2D([10, -10]))
     assert trapezoid.visualization_polydata.center == pytest.approx(
-        ([5.34314575050762, -10.0, 0.0]),
+        ([10.0, -10.0, 0.0]),
         rel=1e-6,
         abs=1e-8,
     )
     assert trapezoid.visualization_polydata.bounds == pytest.approx(
-        [-4.313708498984759, 15.0, -14.0, -6.0, 0.0, 0.0],
+        [5.0, 15.0, -11.0, -9.0, 0.0, 0.0],
         rel=1e-6,
         abs=1e-8,
     )

tests/test_sketch.py

@@ -237,16 +237,16 @@ def test_sketch_trapezoidal_face():
     sketch = Sketch()
 
     # Create the sketch face with trapezoid
-    sketch.trapezoid(10, 8, np.pi / 4, np.pi / 8, Point2D([10, -10]), tag="trapezoid1")
+    sketch.trapezoid(10, 1, np.pi / 4, np.pi / 8, Point2D([10, -10]), tag="trapezoid1")
     assert len(sketch.faces) == 1
-    assert sketch.faces[0].width.m == 10
-    assert sketch.faces[0].height.m == 8
+    assert sketch.faces[0].base_width.m == 10
+    assert sketch.faces[0].height.m == 1
     assert sketch.faces[0].center == Point2D([10, -10])
 
-    sketch.trapezoid(20, 10, np.pi / 8, np.pi / 16, Point2D([10, -10]), np.pi / 2, tag="trapezoid2")
+    sketch.trapezoid(20, 2, np.pi / 8, np.pi / 16, Point2D([10, -10]), np.pi / 2, tag="trapezoid2")
     assert len(sketch.faces) == 2
-    assert sketch.faces[1].width.m == 20
-    assert sketch.faces[1].height.m == 10
+    assert sketch.faces[1].base_width.m == 20
+    assert sketch.faces[1].height.m == 2
     assert sketch.faces[1].center == Point2D([10, -10])
 
     trapezoid1_retrieved = sketch.get("trapezoid1")
@@ -258,7 +258,7 @@ def test_sketch_trapezoidal_face():
     assert trapezoid2_retrieved[0] == sketch.faces[1]
 
     # Test the trapezoid errors
-    with pytest.raises(ValueError, match="Width must be a real positive value."):
+    with pytest.raises(ValueError, match="Base width must be a real positive value."):
         sketch.trapezoid(
             0, 10, np.pi / 8, np.pi / 16, Point2D([10, -10]), np.pi / 2, tag="trapezoid3"
         )
@@ -268,6 +268,18 @@ def test_sketch_trapezoidal_face():
             10, -10, np.pi / 8, np.pi / 16, Point2D([10, -10]), np.pi / 2, tag="trapezoid3"
         )
 
+    with pytest.raises(ValueError, match="The trapezoid angles must be between 0 and 180 degrees."):
+        sketch.trapezoid(
+            10, 10, -np.pi, np.pi / 16, Point2D([10, -10]), np.pi / 2, tag="trapezoid3"
+        )
+
+    with pytest.raises(
+        ValueError,
+        match="The trapezoid is degenerate. "
+        "The provided angles, width and height do not form a valid trapezoid.",
+    ):
+        sketch.trapezoid(10, 10, np.pi / 4, np.pi / 8, Point2D([10, -10]), tag="trapezoid3")
+
 
 def test_sketch_circle_instance():
     """Test circle instance."""