Feat/enhance parameters (#406)

Co-authored-by: Roberto Pastor Muela <[email protected]>

Author: jonahrb

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

@@ -1,10 +1,16 @@
 """Provides the PyGeometry ``primitives`` subpackage."""
 
 from ansys.geometry.core.primitives.circle import Circle, CircleEvaluation
-from ansys.geometry.core.primitives.cone import Cone
-from ansys.geometry.core.primitives.cylinder import Cylinder
+from ansys.geometry.core.primitives.cone import Cone, ConeEvaluation
+from ansys.geometry.core.primitives.cylinder import Cylinder, CylinderEvaluation
 from ansys.geometry.core.primitives.ellipse import Ellipse, EllipseEvaluation
-from ansys.geometry.core.primitives.line import Line
-from ansys.geometry.core.primitives.sphere import Sphere
-from ansys.geometry.core.primitives.surface_evaluation import ParamUV, SurfaceEvaluation
+from ansys.geometry.core.primitives.line import Line, LineEvaluation
+from ansys.geometry.core.primitives.parameterization import (
+    Parameterization,
+    ParamForm,
+    ParamType,
+    ParamUV,
+)
+from ansys.geometry.core.primitives.sphere import Sphere, SphereEvaluation
+from ansys.geometry.core.primitives.surface_evaluation import SurfaceEvaluation
 from ansys.geometry.core.primitives.torus import Torus

src/ansys/geometry/core/primitives/circle.py

@@ -8,6 +8,12 @@
 from ansys.geometry.core.math import UNITVECTOR3D_X, UNITVECTOR3D_Z, Point3D, UnitVector3D, Vector3D
 from ansys.geometry.core.misc import Accuracy, Distance
 from ansys.geometry.core.primitives.curve_evaluation import CurveEvaluation
+from ansys.geometry.core.primitives.parameterization import (
+    Interval,
+    Parameterization,
+    ParamForm,
+    ParamType,
+)
 from ansys.geometry.core.typing import Real, RealSequence
 
 
@@ -99,12 +105,36 @@ def __eq__(self, other: "Circle") -> bool:
             and self._axis == other._axis
         )
 
-    def evaluate(self, parameter: float) -> "CircleEvaluation":
-        """Evaluate the circle at the given parameter."""
+    def evaluate(self, parameter: Real) -> "CircleEvaluation":
+        """
+        Evaluate the circle at the given parameter.
+
+        Parameters
+        ----------
+        parameter : Real
+            The parameter at which to evaluate the circle.
+
+        Returns
+        -------
+        CircleEvaluation
+            The resulting evaluation.
+        """
         return CircleEvaluation(self, parameter)
 
     def project_point(self, point: Point3D) -> "CircleEvaluation":
-        """Project a point onto the circle and return its ``CircleEvaluation``."""
+        """
+        Project a point onto the circle and return its ``CircleEvaluation``.
+
+        Parameters
+        ----------
+        point : Point3D
+            The point to project onto the circle.
+
+        Returns
+        -------
+        CircleEvaluation
+            The resulting evaluation.
+        """
         origin_to_point = point - self.origin
         dir_in_plane = UnitVector3D.from_points(
             Point3D([0, 0, 0]), origin_to_point - ((origin_to_point * self.dir_z) * self.dir_z)
@@ -116,13 +146,38 @@ def project_point(self, point: Point3D) -> "CircleEvaluation":
         return CircleEvaluation(self, t)
 
     def is_coincident_circle(self, other: "Circle") -> bool:
-        """Determine if this circle is coincident with another."""
+        """
+        Determine if this circle is coincident with another.
+
+        Parameters
+        ----------
+        other : Circle
+            The circle to determine coincidence with.
+
+        Returns
+        -------
+        bool
+            Returns true if this circle is coincident with the other.
+        """
         return (
             Accuracy.length_is_equal(self.radius.m, other.radius.m)
             and self.origin == other.origin
             and self.dir_z == other.dir_z
         )
 
+    def get_parameterization(self) -> Parameterization:
+        """
+        The parameter of a circle specifies the clockwise angle around the axis
+        (right hand corkscrew law), with a zero parameter at `dir_x` and a period
+        of 2*pi.
+
+        Returns
+        -------
+        Parameterization
+            Information about how a circle is parameterized.
+        """
+        return Parameterization(ParamForm.PERIODIC, ParamType.CIRCULAR, Interval(0, 2 * np.pi))
+
 
 class CircleEvaluation(CurveEvaluation):
     """
@@ -132,11 +187,12 @@ class CircleEvaluation(CurveEvaluation):
     ----------
     circle: ~ansys.geometry.core.primitives.circle.Circle
         The ``Circle`` object to be evaluated.
-    parameter: float, int
+    parameter: Real
         The parameter at which the ``Circle`` evaluation is requested.
     """
 
     def __init__(self, circle: Circle, parameter: Real) -> None:
+        """``CircleEvaluation`` class constructor."""
         self._circle = circle
         self._parameter = parameter
 
@@ -151,31 +207,68 @@ def parameter(self) -> Real:
         return self._parameter
 
     def position(self) -> Point3D:
-        """The position of the evaluation."""
+        """
+        The position of the evaluation.
+
+        Returns
+        -------
+        Point3D
+            The point that lies on the circle at this evaluation.
+        """
         return (
             self.circle.origin
             + ((self.circle.radius * np.cos(self.parameter)) * self.circle.dir_x).m
             + ((self.circle.radius * np.sin(self.parameter)) * self.circle.dir_y).m
         )
 
     def tangent(self) -> UnitVector3D:
-        """The tangent of the evaluation."""
+        """
+        The tangent of the evaluation.
+
+        Returns
+        -------
+        UnitVector3D
+            The tangent unit vector to the circle at this evaluation.
+        """
         return (
             np.cos(self.parameter) * self.circle.dir_y - np.sin(self.parameter) * self.circle.dir_x
         )
 
     def first_derivative(self) -> Vector3D:
-        """The first derivative of the evaluation."""
+        """
+        The first derivative of the evaluation. The first derivative is in the direction of the
+        tangent and has a magnitude equal to the velocity (rate of change of position) at that
+        point.
+
+        Returns
+        -------
+        Vector3D
+            The first derivative of this evaluation.
+        """
         return self.circle.radius.m * (
             np.cos(self.parameter) * self.circle.dir_y - np.sin(self.parameter) * self.circle.dir_x
         )
 
     def second_derivative(self) -> Vector3D:
-        """The second derivative of the evaluation."""
+        """
+        The second derivative of the evaluation.
+
+        Returns
+        -------
+        Vector3D
+            The second derivative of this evaluation.
+        """
         return -self.circle.radius.m * (
             np.cos(self.parameter) * self.circle.dir_x + np.sin(self.parameter) * self.circle.dir_y
         )
 
     def curvature(self) -> Real:
-        """The curvature of the evaluation."""
+        """
+        The curvature of the circle.
+
+        Returns
+        -------
+        Real
+            The curvature of the circle.
+        """
         return 1 / np.abs(self.circle.radius.m)