Add Circle rotate() / rotate_ip() (#2662)

* Add circle.rotate/ip

Co-authored-by: Emc2356 <[email protected]>
Co-authored-by: NovialRiptide <[email protected]>
Co-authored-by: ScriptLineStudios <[email protected]>
Co-authored-by: Avaxar <[email protected]>
Co-authored-by: maqa41 <[email protected]>

* stubs fix

* fixed docs

* added missing versionadded tags

* Apply suggestions from code review

Co-authored-by: Dan Lawrence <[email protected]>

---------

Co-authored-by: Emc2356 <[email protected]>
Co-authored-by: NovialRiptide <[email protected]>
Co-authored-by: ScriptLineStudios <[email protected]>
Co-authored-by: Avaxar <[email protected]>
Co-authored-by: maqa41 <[email protected]>
Co-authored-by: Dan Lawrence <[email protected]>

Author: 7 people

buildconfig/stubs/pygame/geometry.pyi

@@ -96,6 +96,14 @@ class Circle:
     def update(self, x: float, y: float, r: float, /) -> None: ...
     @overload
     def update(self, center: Coordinate, r: float, /) -> None: ...
+    @overload
+    def rotate(self, angle: float, rotation_point: Coordinate, /) -> Circle: ...
+    @overload
+    def rotate(self, angle: float, /) -> Circle: ...
+    @overload
+    def rotate_ip(self, angle: float, rotation_point: Coordinate, /) -> None: ...
+    @overload
+    def rotate_ip(self, angle: float, /) -> None: ...
     def as_rect(self) -> Rect: ...
     def as_frect(self) -> FRect: ...
     def __copy__(self) -> Circle: ...

docs/reST/ref/geometry.rst

@@ -285,6 +285,37 @@
 
          .. ## Circle.update ##
 
+   .. method:: rotate
+
+         | :sl:`rotates the circle`
+         | :sg:`rotate(angle, rotation_point=Circle.center, /) -> Circle`
+         | :sg:`rotate(angle, /) -> Circle`
+
+         Returns a new `Circle` that is rotated by the specified angle around a point.
+         A positive angle rotates the circle clockwise, while a negative angle rotates it counter-clockwise. Angles should be specified in degrees.
+         The rotation point can be a `tuple`, `list`, or `Vector2`.
+         If no rotation point is given, the circle will be rotated around its center.
+
+         .. versionadded:: 2.5.0
+
+         .. ## Circle.rotate ##
+
+    .. method:: rotate_ip
+
+         | :sl:`rotates the circle in place`
+         | :sg:`rotate_ip(angle, rotation_point=Circle.center, /) -> None`
+         | :sg:`rotate_ip(angle, /) -> None`
+
+
+         This method rotates the circle by a specified angle around a point.
+         A positive angle rotates the circle clockwise, while a negative angle rotates it counter-clockwise. Angles should be specified in degrees.
+         The rotation point can be a `tuple`, `list`, or `Vector2`.
+         If no rotation point is given, the circle will be rotated around its center.
+
+         .. versionadded:: 2.5.0
+
+         .. ## Circle.rotate_ip ##
+
    .. method:: as_rect
 
          | :sl:`returns the smallest pygame.Rect object that contains the circle`

src_c/circle.c

@@ -388,6 +388,99 @@ pg_circle_colliderect(pgCircleObject *self, PyObject *const *args,
     return PyBool_FromLong(pgCollision_RectCircle(x, y, w, h, &self->circle));
 }
 
+static void
+_pg_rotate_circle_helper(pgCircleBase *circle, double angle, double rx,
+                         double ry)
+{
+    if (angle == 0.0 || fmod(angle, 360.0) == 0.0) {
+        return;
+    }
+
+    double x = circle->x - rx;
+    double y = circle->y - ry;
+
+    const double angle_rad = DEG_TO_RAD(angle);
+
+    double cos_theta = cos(angle_rad);
+    double sin_theta = sin(angle_rad);
+
+    circle->x = rx + x * cos_theta - y * sin_theta;
+    circle->y = ry + x * sin_theta + y * cos_theta;
+}
+
+static PyObject *
+pg_circle_rotate(pgCircleObject *self, PyObject *const *args, Py_ssize_t nargs)
+{
+    if (!nargs || nargs > 2) {
+        return RAISE(PyExc_TypeError, "rotate requires 1 or 2 arguments");
+    }
+
+    pgCircleBase *circle = &self->circle;
+    double angle, rx, ry;
+
+    rx = circle->x;
+    ry = circle->y;
+
+    if (!pg_DoubleFromObj(args[0], &angle)) {
+        return RAISE(PyExc_TypeError,
+                     "Invalid angle argument, must be numeric");
+    }
+
+    if (nargs != 2) {
+        return _pg_circle_subtype_new(Py_TYPE(self), circle);
+    }
+
+    if (!pg_TwoDoublesFromObj(args[1], &rx, &ry)) {
+        return RAISE(PyExc_TypeError,
+                     "Invalid rotation point argument, must be a sequence of "
+                     "2 numbers");
+    }
+
+    PyObject *circle_obj = _pg_circle_subtype_new(Py_TYPE(self), circle);
+    if (!circle_obj) {
+        return NULL;
+    }
+
+    _pg_rotate_circle_helper(&pgCircle_AsCircle(circle_obj), angle, rx, ry);
+
+    return circle_obj;
+}
+
+static PyObject *
+pg_circle_rotate_ip(pgCircleObject *self, PyObject *const *args,
+                    Py_ssize_t nargs)
+{
+    if (!nargs || nargs > 2) {
+        return RAISE(PyExc_TypeError, "rotate requires 1 or 2 arguments");
+    }
+
+    pgCircleBase *circle = &self->circle;
+    double angle, rx, ry;
+
+    rx = circle->x;
+    ry = circle->y;
+
+    if (!pg_DoubleFromObj(args[0], &angle)) {
+        return RAISE(PyExc_TypeError,
+                     "Invalid angle argument, must be numeric");
+    }
+
+    if (nargs != 2) {
+        /* just return None */
+        Py_RETURN_NONE;
+    }
+
+    if (!pg_TwoDoublesFromObj(args[1], &rx, &ry)) {
+        return RAISE(PyExc_TypeError,
+                     "Invalid rotation point argument, must be a sequence "
+                     "of 2 numbers");
+    }
+
+    _pg_rotate_circle_helper(circle, angle, rx, ry);
+
+    Py_RETURN_NONE;
+}
+
 static PyObject *
 pg_circle_as_rect(pgCircleObject *self, PyObject *_null)
 {
@@ -428,6 +521,10 @@ static struct PyMethodDef pg_circle_methods[] = {
      DOC_CIRCLE_ASFRECT},
     {"__copy__", (PyCFunction)pg_circle_copy, METH_NOARGS, DOC_CIRCLE_COPY},
     {"copy", (PyCFunction)pg_circle_copy, METH_NOARGS, DOC_CIRCLE_COPY},
+    {"rotate", (PyCFunction)pg_circle_rotate, METH_FASTCALL,
+     DOC_CIRCLE_ROTATE},
+    {"rotate_ip", (PyCFunction)pg_circle_rotate_ip, METH_FASTCALL,
+     DOC_CIRCLE_ROTATEIP},
     {NULL, NULL, 0, NULL}};
 
 #define GETTER_SETTER(name)                                                   \

src_c/doc/geometry_doc.h

@@ -15,6 +15,8 @@
 #define DOC_CIRCLE_MOVEIP "move_ip((x, y), /) -> None\nmove_ip(x, y, /) -> None\nmove_ip(vector2, /) -> None\nmoves the circle by a given amount, in place"
 #define DOC_CIRCLE_COLLIDERECT "colliderect(rect, /) -> bool\ncolliderect((x, y, width, height), /) -> bool\ncolliderect(x, y, width, height, /) -> bool\ncolliderect((x, y), (width, height), /) -> bool\nchecks if a rectangle intersects the circle"
 #define DOC_CIRCLE_UPDATE "update((x, y), radius, /) -> None\nupdate(x, y, radius, /) -> None\nupdates the circle position and radius"
+#define DOC_CIRCLE_ROTATE "rotate(angle, rotation_point=Circle.center, /) -> Circle\nrotate(angle, /) -> Circle\nrotates the circle"
+#define DOC_CIRCLE_ROTATEIP "rotate_ip(angle, rotation_point=Circle.center, /) -> None\nrotate_ip(angle, /) -> None\nrotates the circle in place"
 #define DOC_CIRCLE_ASRECT "as_rect() -> Rect\nreturns the smallest pygame.Rect object that contains the circle"
 #define DOC_CIRCLE_ASFRECT "as_frect() -> FRect\nreturns the smallest pygame.FRect object that contains the circle"
 #define DOC_CIRCLE_COPY "copy() -> Circle\nreturns a copy of the circle"

src_c/geometry.h

@@ -40,4 +40,16 @@ pgCircle_FromObjectFastcall(PyObject *const *args, Py_ssize_t nargs,
 #define M_TWOPI 6.28318530717958647692
 #endif
 
+/* PI/180 */
+#ifndef M_PI_QUO_180
+#define M_PI_QUO_180 0.01745329251994329577
+#endif
+
+/* Converts degrees to radians */
+static inline double
+DEG_TO_RAD(double deg)
+{
+    return deg * M_PI_QUO_180;
+}
+
 #endif  // PYGAME_CE_GEOMETRY_H

test/geometry_test.py

@@ -7,6 +7,15 @@
 from pygame.geometry import Circle
 
 
+def float_range(a, b, step):
+    result = []
+    current_value = a
+    while current_value < b:
+        result.append(current_value)
+        current_value += step
+    return result
+
+
 class CircleTypeTest(unittest.TestCase):
     def testConstruction_invalid_type(self):
         """Checks whether passing wrong types to the constructor
@@ -910,6 +919,185 @@ class CircleSub(Circle):
         self.assertEqual(type(c.move_ip(1, 1)), type(None))
         self.assertEqual(type(cs.move_ip(1, 1)), type(None))
 
+    def test_meth_rotate_ip_invalid_argnum(self):
+        """Ensures that the rotate_ip method correctly deals with invalid numbers of arguments."""
+        c = Circle(0, 0, 1)
+
+        with self.assertRaises(TypeError):
+            c.rotate_ip()
+
+        invalid_args = [
+            (1, (2, 2), 2),
+            (1, (2, 2), 2, 2),
+            (1, (2, 2), 2, 2, 2),
+            (1, (2, 2), 2, 2, 2, 2),
+            (1, (2, 2), 2, 2, 2, 2, 2),
+            (1, (2, 2), 2, 2, 2, 2, 2, 2),
+        ]
+
+        for args in invalid_args:
+            with self.assertRaises(TypeError):
+                c.rotate_ip(*args)
+
+    def test_meth_rotate_ip_invalid_argtype(self):
+        """Ensures that the rotate_ip method correctly deals with invalid argument types."""
+        c = Circle(0, 0, 1)
+
+        invalid_args = [
+            ("a",),  # angle str
+            (None,),  # angle str
+            ((1, 2)),  # angle tuple
+            ([1, 2]),  # angle list
+            (1, "a"),  # origin str
+            (1, None),  # origin None
+            (1, True),  # origin True
+            (1, False),  # origin False
+            (1, (1, 2, 3)),  # origin tuple
+            (1, [1, 2, 3]),  # origin list
+            (1, (1, "a")),  # origin str
+            (1, ("a", 1)),  # origin str
+            (1, (1, None)),  # origin None
+            (1, (None, 1)),  # origin None
+            (1, (1, (1, 2))),  # origin tuple
+            (1, (1, [1, 2])),  # origin list
+        ]
+
+        for value in invalid_args:
+            with self.assertRaises(TypeError):
+                c.rotate_ip(*value)
+
+    def test_meth_rotate_ip_return(self):
+        """Ensures that the rotate_ip method always returns None."""
+        c = Circle(0, 0, 1)
+
+        for angle in float_range(-360, 360, 1):
+            self.assertIsNone(c.rotate_ip(angle))
+            self.assertIsInstance(c.rotate_ip(angle), type(None))
+
+    def test_meth_rotate_invalid_argnum(self):
+        """Ensures that the rotate method correctly deals with invalid numbers of arguments."""
+        c = Circle(0, 0, 1)
+
+        with self.assertRaises(TypeError):
+            c.rotate()
+
+        invalid_args = [
+            (1, (2, 2), 2),
+            (1, (2, 2), 2, 2),
+            (1, (2, 2), 2, 2, 2),
+            (1, (2, 2), 2, 2, 2, 2),
+            (1, (2, 2), 2, 2, 2, 2, 2),
+            (1, (2, 2), 2, 2, 2, 2, 2, 2),
+        ]
+
+        for args in invalid_args:
+            with self.assertRaises(TypeError):
+                c.rotate(*args)
+
+    def test_meth_rotate_invalid_argtype(self):
+        """Ensures that the rotate method correctly deals with invalid argument types."""
+        c = Circle(0, 0, 1)
+
+        invalid_args = [
+            ("a",),  # angle str
+            (None,),  # angle str
+            ((1, 2)),  # angle tuple
+            ([1, 2]),  # angle list
+            (1, "a"),  # origin str
+            (1, None),  # origin None
+            (1, True),  # origin True
+            (1, False),  # origin False
+            (1, (1, 2, 3)),  # origin tuple
+            (1, [1, 2, 3]),  # origin list
+            (1, (1, "a")),  # origin str
+            (1, ("a", 1)),  # origin str
+            (1, (1, None)),  # origin None
+            (1, (None, 1)),  # origin None
+            (1, (1, (1, 2))),  # origin tuple
+            (1, (1, [1, 2])),  # origin list
+        ]
+
+        for value in invalid_args:
+            with self.assertRaises(TypeError):
+                c.rotate(*value)
+
+    def test_meth_rotate_return(self):
+        """Ensures that the rotate method always returns a Circle."""
+        c = Circle(0, 0, 1)
+
+        class CircleSubclass(Circle):
+            pass
+
+        cs = CircleSubclass(0, 0, 1)
+
+        for angle in float_range(-360, 360, 1):
+            self.assertIsInstance(c.rotate(angle), Circle)
+            self.assertIsInstance(cs.rotate(angle), CircleSubclass)
+
+    def test_meth_rotate(self):
+        """Ensures the Circle.rotate() method rotates the Circle correctly."""
+
+        def rotate_circle(circle: Circle, angle, center):
+            def rotate_point(x, y, rang, cx, cy):
+                x -= cx
+                y -= cy
+                x_new = x * math.cos(rang) - y * math.sin(rang)
+                y_new = x * math.sin(rang) + y * math.cos(rang)
+                return x_new + cx, y_new + cy
+
+            angle = math.radians(angle)
+            cx, cy = center if center is not None else circle.center
+            x, y = rotate_point(circle.x, circle.y, angle, cx, cy)
+            return Circle(x, y, circle.r)
+
+        def assert_approx_equal(circle1, circle2, eps=1e-12):
+            self.assertAlmostEqual(circle1.x, circle2.x, delta=eps)
+            self.assertAlmostEqual(circle1.y, circle2.y, delta=eps)
+            self.assertAlmostEqual(circle1.r, circle2.r, delta=eps)
+
+        c = Circle(0, 0, 1)
+        angles = float_range(-360, 360, 0.5)
+        centers = [(a, b) for a in range(-10, 10) for b in range(-10, 10)]
+        for angle in angles:
+            assert_approx_equal(c.rotate(angle), rotate_circle(c, angle, None))
+            for center in centers:
+                assert_approx_equal(
+                    c.rotate(angle, center), rotate_circle(c, angle, center)
+                )
+
+    def test_meth_rotate_ip(self):
+        """Ensures the Circle.rotate_ip() method rotates the Circle correctly."""
+
+        def rotate_circle(circle: Circle, angle, center):
+            def rotate_point(x, y, rang, cx, cy):
+                x -= cx
+                y -= cy
+                x_new = x * math.cos(rang) - y * math.sin(rang)
+                y_new = x * math.sin(rang) + y * math.cos(rang)
+                return x_new + cx, y_new + cy
+
+            angle = math.radians(angle)
+            cx, cy = center if center is not None else circle.center
+            x, y = rotate_point(circle.x, circle.y, angle, cx, cy)
+            circle.x = x
+            circle.y = y
+            return circle
+
+        def assert_approx_equal(circle1, circle2, eps=1e-12):
+            self.assertAlmostEqual(circle1.x, circle2.x, delta=eps)
+            self.assertAlmostEqual(circle1.y, circle2.y, delta=eps)
+            self.assertAlmostEqual(circle1.r, circle2.r, delta=eps)
+
+        c = Circle(0, 0, 1)
+        angles = float_range(-360, 360, 0.5)
+        centers = [(a, b) for a in range(-10, 10) for b in range(-10, 10)]
+        for angle in angles:
+            c.rotate_ip(angle)
+            assert_approx_equal(c, rotate_circle(c, angle, None))
+            for center in centers:
+                c.rotate_ip(angle, center)
+                assert_approx_equal(c, rotate_circle(c, angle, center))
+
 
 if __name__ == "__main__":
     unittest.main()