Add new Vec2d.from_polars method, cleanup tests/docs for vec2d. #261

Author: viblo

CHANGELOG.rst

@@ -3,6 +3,11 @@ Changelog
 =========
 
 
+.. Pymunk 6.10.0??
+    Changes:
+    - Added from_polars() static method to Vec2d to easily create Vec2ds from polar coordinates.
+    - Improved docs (of Vec2d)
+
 Pymunk 6.9.0 (2024-10-13)
 -------------------------
 

pymunk/tests/test_vec2d.py

@@ -32,6 +32,10 @@ def testCreationAndAccess(self) -> None:
         self.assertEqual(list(v), [3, 5])
         self.assertEqual(tuple(v), (3, 5))
 
+        v = Vec2d.from_polar(3, 2)
+        self.assertEqual(v.length, 3)
+        self.assertEqual(v.angle, 2)
+
     def testMath(self) -> None:
         v = Vec2d(111, 222)
         self.assertEqual(v + Vec2d(1, 2), Vec2d(112, 224))
@@ -66,8 +70,6 @@ def testLength(self) -> None:
         self.assertEqual(length, 0)
         with self.assertRaises(AttributeError):
             v.length = 5  # type: ignore
-        v2 = Vec2d(10, -2)
-        self.assertEqual(v.get_distance(v2), (v - v2).length)
 
     def testAnglesDegrees(self) -> None:
         v = Vec2d(0, 3)
@@ -109,21 +111,6 @@ def testAnglesRadians(self) -> None:
         v2 = v2.rotated(v2.get_angle_between(v))
         self.assertAlmostEqual(v.get_angle_between(v2), 0)
 
-    def testHighLevel(self) -> None:
-        basis0 = Vec2d(5.0, 0)
-        basis1 = Vec2d(0, 0.5)
-        v = Vec2d(10, 1)
-        self.assertEqual(v.convert_to_basis(basis0, basis1), (2, 2))
-        self.assertEqual(v.projection(basis0), (10, 0))
-        self.assertEqual(v.projection(Vec2d(0, 0)), (0, 0))
-        self.assertEqual(v.projection((0, 0)), (0, 0))
-        self.assertEqual(basis0.dot(basis1), 0)
-
-    def testCross(self) -> None:
-        lhs = Vec2d(1, 0.5)
-        rhs = Vec2d(4, 6)
-        self.assertEqual(lhs.cross(rhs), 4)
-
     def testComparison(self) -> None:
         int_vec = Vec2d(3, -2)
         flt_vec = Vec2d(3.0, -2.0)

pymunk/vec2d.py

@@ -304,17 +304,24 @@ def perpendicular_normal(self) -> "Vec2d":
 
     def dot(self, other: Tuple[float, float]) -> float:
         """The dot product between the vector and other vector
-            v1.dot(v2) -> v1.x*v2.x + v1.y*v2.y
+        v1.dot(v2) -> v1.x*v2.x + v1.y*v2.y
 
-        :return: The dot product
+        >>> Vec2d(5, 0).dot((0, 5))
+        0.0
+        >>> Vec2d(1, 2).dot((3, 4))
+        11.0
         """
         assert len(other) == 2
         return float(self.x * other[0] + self.y * other[1])
 
     def get_distance(self, other: Tuple[float, float]) -> float:
         """The distance between the vector and other vector
 
-        :return: The distance
+        >>> Vec2d(0, 2).get_distance((0, -3))
+        5.0
+        >>> a, b = Vec2d(3, 2), Vec2d(4,3)
+        >>> a.get_distance(b) == (a - b).length == (b - a).length
+        True
         """
         assert len(other) == 2
         return math.sqrt((self.x - other[0]) ** 2 + (self.y - other[1]) ** 2)
@@ -324,15 +331,25 @@ def get_dist_sqrd(self, other: Tuple[float, float]) -> float:
         It is more efficent to use this method than to call get_distance()
         first and then do a square() on the result.
 
-        :return: The squared distance
+        >>> Vec2d(1, 0).get_dist_sqrd((1,10))
+        100
+        >>> Vec2d(1, 2).get_dist_sqrd((10, 11))
+        162
+        >>> Vec2d(1, 2).get_distance((10, 11))**2
+        162.0
         """
         assert len(other) == 2
         return (self.x - other[0]) ** 2 + (self.y - other[1]) ** 2
 
     def projection(self, other: Tuple[float, float]) -> "Vec2d":
         """Project this vector on top of other vector
 
-        :return: The projected vector
+        >>> Vec2d(10, 1).projection((5.0, 0))
+        Vec2d(10.0, 0.0)
+        >>> Vec2d(10, 1).projection((10, 5))
+        Vec2d(8.4, 4.2)
+        >>> Vec2d(10, 1).projection((0, 0))
+        Vec2d(0, 0)
         """
         assert len(other) == 2
         other_length_sqrd = other[0] * other[0] + other[1] * other[1]
@@ -344,17 +361,19 @@ def projection(self, other: Tuple[float, float]) -> "Vec2d":
 
     def cross(self, other: Tuple[float, float]) -> float:
         """The cross product between the vector and other vector
-            v1.cross(v2) -> v1.x*v2.y - v1.y*v2.x
+        v1.cross(v2) -> v1.x*v2.y - v1.y*v2.x
 
-        :return: The cross product
+        >>> Vec2d(1, 0.5).cross((4, 6))
+        4.0
         """
         assert len(other) == 2
         return self.x * other[1] - self.y * other[0]
 
     def interpolate_to(self, other: Tuple[float, float], range: float) -> "Vec2d":
         """Vector interpolation between the current vector and another vector.
 
-        :return: The interpolated vector
+        >>> Vec2d(10,20).interpolate_to((20,-20), 0.1)
+        Vec2d(11.0, 16.0)
         """
         assert len(other) == 2
         return Vec2d(
@@ -366,7 +385,8 @@ def convert_to_basis(
     ) -> "Vec2d":
         """Converts the vector to a new basis defined by the given x and y vectors.
 
-        :return: Vec2d: The vector converted to the new basis.
+        >>> Vec2d(10, 1).convert_to_basis((5, 0), (0, 0.5))
+        Vec2d(2.0, 2.0)
         """
         assert len(x_vector) == 2
         assert len(y_vector) == 2
@@ -411,6 +431,20 @@ def ones() -> "Vec2d":
         """
         return Vec2d(1, 1)
 
+    @staticmethod
+    def from_polar(length: float, angle: float) -> "Vec2d":
+        """Create a new Vec2d from a length and an angle (in radians).
+
+        >>> Vec2d.from_polar(2, 0)
+        Vec2d(2.0, 0.0)
+        >>> Vec2d(2, 0).rotated(0.5) == Vec2d.from_polar(2, 0.5)
+        True
+        >>> v = Vec2d.from_polar(2, 0.5)
+        >>> v.length, v.angle
+        (2.0, 0.5)
+        """
+        return Vec2d(math.cos(angle) * length, math.sin(angle) * length)
+
     # Extra functions, mainly for chipmunk
     def cpvrotate(self, other: Tuple[float, float]) -> "Vec2d":
         """Uses complex multiplication to rotate this vector by the other."""