Merge pull request #1450 from obucklin/angle_vectors_projected

Angle vectors projected

Author: gonzalocasas

AUTHORS.md

@@ -41,3 +41,4 @@
 - Adam Anouar <<[email protected]>> [@AdamAnouar](https://github.com/AdamAnouar)
 - Joseph Kenny <<[email protected]>> [@jckenny59](https://github.com/jckenny59)
 - Panayiotis Papacharalambous <<[email protected]>> [@papachap](https://github.com/papachap)
+- Oliver Bucklin <<[email protected]>> [@obucklin](https://github.com/obucklin)

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Added `Group` to `compas.scene`.
 * Added `compas.geometry.Brep.cap_planar_holes`.
 * Added `compas_rhino.geometry.RhinoBrep.cap_planar_holes`.
+* Added `compas.geometry.angle_vectors_projected`.
 
 ### Changed
 

src/compas/geometry/__init__.py

@@ -99,6 +99,7 @@
     angle_points_xy,
     angle_vectors,
     angle_vectors_signed,
+    angle_vectors_projected,
     angle_vectors_xy,
     angles_points,
     angles_points_xy,
@@ -488,6 +489,7 @@
     "angle_points_xy",
     "angle_vectors",
     "angle_vectors_signed",
+    "angle_vectors_projected",
     "angle_vectors_xy",
     "angles_points",
     "angles_points_xy",

src/compas/geometry/_core/angles.py

@@ -78,8 +78,7 @@ def angle_vectors(u, v, deg=False, tol=None):
 def angle_vectors_signed(u, v, normal, deg=False, tol=None):
     """Computes the signed angle between two vectors.
 
-    It calculates the angle such that rotating vector u about the normal by
-    angle would result in a vector that looks into the same direction as v.
+    Returns the smallest angle between 2 vectors, with the sign of the angle based on the direction of the normal vector according to the right hand rule of rotation.
 
     Parameters
     ----------
@@ -121,6 +120,44 @@ def angle_vectors_signed(u, v, normal, deg=False, tol=None):
         return angle
 
 
+def angle_vectors_projected(u, v, normal, deg=False, tol=None):
+    """Computes the signed angle between two vectors.
+
+    Retuns the angle between 2 vectors projected onto a plane defined by a normal vector.
+    This can be positive or negative depending on the direction of the normal vector and the order of the input vectors
+
+    Parameters
+    ----------
+    u : [float, float, float] | :class:`compas.geometry.Vector`
+        XYZ components of the first vector.
+    v : [float, float, float] | :class:`compas.geometry.Vector`
+        XYZ components of the second vector.
+    normal : [float, float, float] | :class:`compas.geometry.Vector`
+        XYZ components of the plane's normal spanned by u and v.
+    deg : bool, optional
+        If True, returns the angle in degrees.
+    tol : float, optional
+        The tolerance for comparing values to zero.
+        Default is :attr:`TOL.absolute`.
+
+    Returns
+    -------
+    float
+        The signed angle in radians (in degrees if deg == True).
+
+    Examples
+    --------
+    >>> normal = [0.0, 0.0, 1.0]
+    >>> angle_vectors_projected([0.0, 1.0, -1.0], [1.0, 0.0, 1.0], normal)
+    -1.57079
+
+    """
+    u_cross = cross_vectors(u, normal)
+    v_cross = cross_vectors(v, normal)
+
+    return angle_vectors_signed(u_cross, v_cross, normal, deg, tol)
+
+
 def angle_vectors_xy(u, v, deg=False, tol=None):
     """Compute the smallest angle between the XY components of two vectors.
 

tests/compas/compas_api.json

@@ -263,6 +263,7 @@
       "angle_points_xy",
       "angle_vectors",
       "angle_vectors_signed",
+      "angle_vectors_projected",
       "angle_vectors_xy",
       "angles_points",
       "angles_points_xy",
@@ -648,4 +649,4 @@
       "yellow"
     ]
   }
-}
+}

tests/compas/compas_api_ipy.json

@@ -241,6 +241,7 @@
       "angle_points_xy",
       "angle_vectors",
       "angle_vectors_signed",
+      "angle_vectors_projected",
       "angle_vectors_xy",
       "angles_points",
       "angles_points_xy",
@@ -578,4 +579,4 @@
       "yellow"
     ]
   }
-}
+}

tests/compas/geometry/test_core.py

@@ -10,6 +10,7 @@
 from compas.geometry import angle_planes
 from compas.geometry import angles_vectors
 from compas.geometry import angle_vectors_signed
+from compas.geometry import angle_vectors_projected
 from compas.geometry import centroid_points
 from compas.geometry import centroid_polyhedron
 from compas.geometry import length_vector
@@ -137,6 +138,17 @@ def test_angle_vectors_signed(u, v, normal, result):
     assert TOL.is_close(angle_vectors_signed(u, v, normal), result)
 
 
+@pytest.mark.parametrize(
+    "u,v,normal,result",
+    [
+        ([1, 0, 1], [0, 1, -1], [0, 0, 1], +pi / 2),
+        ([1, 0, 1], [0, 1, -1], [0, 0, -1], -pi / 2),
+    ],
+)
+def test_angle_vectors_projected(u, v, normal, result):
+    assert TOL.is_close(angle_vectors_projected(u, v, normal), result)
+
+
 # ==============================================================================
 # average
 # ==============================================================================