feat: add new arc constructors (#1208)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Kathy Pippert <[email protected]>

Author: 3 people

doc/changelog.d/1208.added.md

@@ -0,0 +1 @@
+feat: add new arc constructors

doc/source/examples/02_sketching/basic_usage.mystnb

@@ -105,6 +105,31 @@ sketch.select("Arc")
 sketch.plot_selection()
 ```
 
+There are also additional ways to draw arcs, such as by specifying the start, center point, and angle.
+
+```{code-cell} ipython3
+start_point = Point2D([2, 1], unit=u.m)
+center_point = Point2D([1, 1], unit=u.m)
+angle = 90
+sketch.arc_from_start_center_and_angle(
+    start_point, center_point, angle=90, tag="Arc_from_start_center_angle"
+)
+sketch.select("Arc_from_start_center_angle")
+sketch.plot_selection()
+```
+
+Or by specifying the start, end point, and radius.
+
+```{code-cell} ipython3
+start_point, end_point = Point2D([2, 1], unit=u.m), Point2D([0, 1], unit=u.meter)
+radius = 1 * u.m
+sketch.arc_from_start_end_and_radius(
+    start_point, end_point, radius, tag="Arc_from_start_end_radius"
+)
+sketch.select("Arc_from_start_end_radius")
+sketch.plot_selection()
+```
+
 ### Draw a slot
 
 You draw a slot by specifying the center, width, and height.

doc/source/examples/04_applied/01_naca_airfoils.mystnb

@@ -78,7 +78,7 @@ def naca_airfoil_4digits(number: Union[int, str], n_points: int = 200) -> List[P
         # near the leading edge
         x = (1 - np.cos(i / (n_points - 1) * np.pi)) / 2
 
-        # Check if it is a symmetric airfoil or not
+        # Check if it is a symmetric airfoil
         if p == 0 and m == 0:
             # Camber line is zero in this case
             yc = 0

src/ansys/geometry/core/connection/product_instance.py

@@ -363,7 +363,7 @@ def _wait_for_backend(host: str, port: int, timeout: int):
 
 def _is_port_available(port: int, host: str = "localhost") -> bool:
     """
-    Check whether the argument port is available or not.
+    Check whether the argument port is available.
 
     The optional argument is the ip address where to check port availability.
     Its default is ``localhost``.

src/ansys/geometry/core/math/__init__.py

@@ -39,6 +39,7 @@
 )
 from ansys.geometry.core.math.frame import Frame
 from ansys.geometry.core.math.matrix import Matrix, Matrix33, Matrix44
+from ansys.geometry.core.math.misc import get_two_circle_intersections
 from ansys.geometry.core.math.plane import Plane
 from ansys.geometry.core.math.point import Point2D, Point3D
 from ansys.geometry.core.math.vector import UnitVector2D, UnitVector3D, Vector2D, Vector3D

src/ansys/geometry/core/math/misc.py

@@ -0,0 +1,97 @@
+# Copyright (C) 2023 - 2024 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Provides auxiliary math functions for PyAnsys Geometry."""
+
+
+from beartype import beartype as check_input_types
+from beartype.typing import Tuple, Union
+import numpy as np
+
+from ansys.geometry.core.typing import Real
+
+
+@check_input_types
+def get_two_circle_intersections(
+    x0: Real, y0: Real, r0: Real, x1: Real, y1: Real, r1: Real
+) -> Union[Tuple[Tuple[Real, Real], Tuple[Real, Real]], None]:
+    """
+    Get the intersection points of two circles.
+
+    Parameters
+    ----------
+    x0 : Real
+        x coordinate of the first circle.
+    y0 : Real
+        y coordinate of the first circle.
+    r0 : Real
+        Radius of the first circle.
+    x1 : Real
+        x coordinate of the second circle.
+    y1 : Real
+        y coordinate of the second circle.
+    r1 : Real
+        Radius of the second circle.
+
+    Notes
+    -----
+    This function is based on the following StackOverflow post:
+    https://stackoverflow.com/questions/55816902/finding-the-intersection-of-two-circles
+
+    That post is based on the following implementation:
+    https://paulbourke.net/geometry/circlesphere/
+
+    Returns
+    -------
+    Union[Tuple[Tuple[Real, Real], Tuple[Real, Real]], None]
+        Intersection points of the two circles if they intersect.
+        The points are returned as ``((x3, y3), (x4, y4))``, where ``(x3, y3)`` and ``(x4, y4)``
+        are the intersection points of the two circles. If the circles do not
+        intersect, then ``None`` is returned.
+    """
+    # circle 1: (x0, y0), radius r0
+    # circle 2: (x1, y1), radius r1
+    d = np.sqrt((x1 - x0) ** 2 + (y1 - y0) ** 2)
+
+    # non-intersecting
+    if d > r0 + r1:
+        return None
+    # one circle within other
+    if d < abs(r0 - r1):
+        return None
+    # coincident circles
+    if d == 0 and r0 == r1:
+        return None
+    else:
+        a = (r0**2 - r1**2 + d**2) / (2 * d)
+        h = np.sqrt(r0**2 - a**2)
+        x2 = x0 + a * (x1 - x0) / d
+        y2 = y0 + a * (y1 - y0) / d
+
+        dx = h * (y1 - y0) / d
+        dy = h * (x1 - x0) / d
+        x3 = x2 + dx
+        y3 = y2 - dy
+
+        x4 = x2 - dx
+        y4 = y2 + dy
+
+        return ((x3, y3), (x4, y4))

src/ansys/geometry/core/shapes/surfaces/torus.py

@@ -22,7 +22,6 @@
 """Provides for creating and managing a torus."""
 
 from functools import cached_property
-from typing import Tuple
 
 from beartype import beartype as check_input_types
 from beartype.typing import Tuple, Union

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

@@ -22,16 +22,18 @@
 """Provides for creating and managing an arc."""
 
 from beartype import beartype as check_input_types
-from beartype.typing import Optional
+from beartype.typing import Optional, Union
 import numpy as np
 from pint import Quantity
 import pyvista as pv
 
+from ansys.geometry.core.math.matrix import Matrix
 from ansys.geometry.core.math.point import Point2D
 from ansys.geometry.core.math.vector import Vector2D
-from ansys.geometry.core.misc.measurements import DEFAULT_UNITS
+from ansys.geometry.core.misc.measurements import DEFAULT_UNITS, Angle, Distance
 from ansys.geometry.core.misc.units import UNITS
 from ansys.geometry.core.sketch.edge import SketchEdge
+from ansys.geometry.core.typing import Real
 
 
 class Arc(SketchEdge):
@@ -270,6 +272,7 @@ def __arc_pyvista_hack(self):
         return arc_sub1 + arc_sub2
 
     @classmethod
+    @check_input_types
     def from_three_points(cls, start: Point2D, inter: Point2D, end: Point2D):
         """
         Create an arc from three given points.
@@ -342,3 +345,122 @@ def from_three_points(cls, start: Point2D, inter: Point2D, end: Point2D):
 
         # Finally... you can create the arc
         return Arc(start=start, end=end, center=center, clockwise=is_clockwise)
+
+    @classmethod
+    @check_input_types
+    def from_start_end_and_radius(
+        cls,
+        start: Point2D,
+        end: Point2D,
+        radius: Union[Quantity, Distance, Real],
+        convex_arc: Optional[bool] = False,
+        clockwise: Optional[bool] = False,
+    ):
+        """
+        Create an arc from a starting point, an ending point, and a radius.
+
+        Parameters
+        ----------
+        start : Point2D
+            Starting point of the arc.
+        end : Point2D
+            Ending point of the arc.
+        radius : Union[Quantity, Distance, Real]
+            Radius of the arc.
+        convex_arc : bool, default: False
+            Whether the arc is convex. The default is ``False``.
+            When ``False``, the arc is concave. When ``True``, the arc is convex.
+        clockwise : bool, default: False
+            Whether the arc spans the clockwise angle between the start and end points.
+            When ``False``, the arc spans the counter-clockwise angle.
+            When ``True``, the arc spands the clockwise angle.
+
+        Returns
+        -------
+        Arc
+            Arc generated from the three points.
+        """
+        # Compute the potential centers of the circle
+        # that could generate the arc
+        from ansys.geometry.core.math.misc import get_two_circle_intersections
+
+        # Sanitize the radius
+        radius = radius if isinstance(radius, Distance) else Distance(radius)
+        if radius.value <= 0:
+            raise ValueError("Radius must be a real positive value.")
+
+        # Unpack the points into its coordinates (in DEFAULT_UNITS.LENGTH)
+        x_s, y_s = start.tolist()
+        x_e, y_e = end.tolist()
+        r0 = r1 = radius.value.m_as(DEFAULT_UNITS.LENGTH)
+
+        # Compute the potential centers of the circle
+        centers = get_two_circle_intersections(x0=x_s, y0=y_s, r0=r0, x1=x_e, y1=y_e, r1=r1)
+        if centers is None:
+            raise ValueError("The provided points and radius do not yield a valid arc.")
+
+        # Choose the center depending on if the arc is convex
+        center = Point2D(centers[1] if convex_arc else centers[0])
+
+        # Create the arc
+        return Arc(start=start, end=end, center=center, clockwise=clockwise)
+
+    @classmethod
+    @check_input_types
+    def from_start_center_and_angle(
+        cls,
+        start: Point2D,
+        center: Point2D,
+        angle: Union[Angle, Quantity, Real],
+        clockwise: Optional[bool] = False,
+    ):
+        """
+        Create an arc from a starting point, a center point, and an angle.
+
+        Parameters
+        ----------
+        start : Point2D
+            Starting point of the arc.
+        center : Point2D
+            Center point of the arc.
+        angle : Union[Angle, Quantity, Real]
+            Angle of the arc.
+        clockwise : bool, default: False
+            Whether the provided angle should be considered clockwise.
+            When ``False``, the angle is considered counter-clockwise.
+            When ``True``, the angle is considered clockwise.
+
+        Returns
+        -------
+        Arc
+            Arc generated from the three points.
+        """
+        # Define a 2D vector from the center to the start point
+        to_start_vector = Vector2D.from_points(center, start)
+
+        # Perform sanity check for the angle
+        angle = angle if isinstance(angle, Angle) else Angle(angle)
+        rad_angle = angle.value.m_as(UNITS.radian)
+        cang = np.cos(rad_angle)
+        sang = np.sin(rad_angle)
+
+        # Rotate the vector by the angle
+        if clockwise:
+            rot_matrix = Matrix([[cang, sang], [-sang, cang]])
+        else:
+            rot_matrix = Matrix([[cang, -sang], [sang, cang]])
+
+        # Compute the end vector
+        to_end_vector = rot_matrix @ to_start_vector
+
+        # Define the end point
+        end = Point2D(
+            [
+                to_end_vector[0] + center.x.to_base_units().m,
+                to_end_vector[1] + center.y.to_base_units().m,
+            ],
+            center.base_unit,
+        )
+
+        # Create the arc
+        return Arc(start=start, end=end, center=center, clockwise=clockwise)