From ca21c5e28200c4ba6860347b28f1bf66e3136628 Mon Sep 17 00:00:00 2001 From: itzpr3d4t0r <103119829+itzpr3d4t0r@users.noreply.github.com> Date: Wed, 7 Aug 2024 11:21:11 +0200 Subject: [PATCH 1/9] improved geometry docs. --- docs/reST/ref/geometry.rst | 202 ++++++++++++++++--------------------- 1 file changed, 88 insertions(+), 114 deletions(-) diff --git a/docs/reST/ref/geometry.rst b/docs/reST/ref/geometry.rst index 92fc64378d..3bc9e8bc34 100644 --- a/docs/reST/ref/geometry.rst +++ b/docs/reST/ref/geometry.rst @@ -24,7 +24,7 @@ | :sg:`Circle((x, y), radius) -> Circle` | :sg:`Circle(x, y, radius) -> Circle` - The `Circle` class provides many useful methods for collision / transform and intersection. + The `Circle` class provides many useful methods for collision, transformation, and intersection. A `Circle` can be created from a combination of a pair of coordinates that represent the center of the circle and a radius. Circles can also be created from python objects that are already a `Circle` or have an attribute named "circle". @@ -55,8 +55,6 @@ | :sg:`x -> float` The `x` coordinate of the center of the circle. It can be reassigned to move the circle. - Reassigning the `x` attribute will move the circle to the new `x` coordinate. - The `y` and `r` attributes will not be affected. .. versionadded:: 2.4.0 @@ -68,8 +66,6 @@ | :sg:`y -> float` The `y` coordinate of the center of the circle. It can be reassigned to move the circle. - Reassigning the `y` attribute will move the circle to the new `y` coordinate. - The `x` and `r` attributes will not be affected. .. versionadded:: 2.4.0 @@ -80,9 +76,8 @@ | :sl:`radius of the circle` | :sg:`r -> float` + Represents how big the circle is. It is not possible to set the radius to a negative value. It can be reassigned. - If reassigned it will only change the radius of the circle. - The circle will not be moved from its original position. .. versionadded:: 2.4.0 @@ -96,9 +91,8 @@ | :sl:`radius of the circle squared` | :sg:`r_sqr -> float` - It's equivalent to `r*r`. It can be reassigned. If reassigned, the radius - of the circle will be changed to the square root of the new value. - The circle will not be moved from its original position. + It's equivalent to `r*r`. If reassigned, the radius of the circle will be changed + to the square root of the new value. .. versionadded:: 2.4.0 @@ -109,9 +103,8 @@ | :sl:`x and y coordinates of the center of the circle` | :sg:`center -> (float, float)` - It's a tuple containing the `x` and `y` coordinates that represent the center - of the circle. It can be reassigned. If reassigned, the circle will be moved - to the new position. The radius will not be affected. + It's a tuple containing the circle's `x` and `y` coordinates representing its center. + If reassigned, the circle will be moved to the new position. .. versionadded:: 2.4.0 @@ -122,9 +115,8 @@ | :sl:`diameter of the circle` | :sg:`diameter -> float` - It's calculated using the `d=2*r` formula. It can be reassigned. If reassigned - the radius will be changed to half the diameter. - The circle will not be moved from its original position. + It's calculated using the `d=2*r` formula. If reassigned the radius will be changed + to half the diameter. .. versionadded:: 2.4.0 @@ -135,9 +127,8 @@ | :sl:`area of the circle` | :sg:`area -> float` - It's calculated using the `area=pi*r*r` formula. It can be reassigned. - If reassigned the circle radius will be changed to produce a circle with matching - area. The circle will not be moved from its original position. + It's calculated using the `area=pi*r*r` formula. If reassigned the circle radius + will be changed to produce a circle with matching area. .. versionadded:: 2.4.0 @@ -148,9 +139,8 @@ | :sl:`circumference of the circle` | :sg:`circumference -> float` - It's calculated using the `circumference=2*pi*r` formula. It can be reassigned. - If reassigned the circle radius will be changed to produce a circle with matching - circumference. The circle will not be moved from its original position. + It's calculated using the `circumference=2*pi*r` formula. If reassigned the circle + radius will be changed to produce a circle with matching circumference. .. versionadded:: 2.4.0 @@ -167,10 +157,9 @@ | :sg:`collidepoint(x, y, /) -> bool` | :sg:`collidepoint(vector2, /) -> bool` - The `collidepoint` method tests whether a given point is inside the `Circle` - (including the edge of the `Circle`). It takes a tuple of (x, y) coordinates, two - separate x and y coordinates, or a `Vector2` object as its argument, and returns - `True` if the point is inside the `Circle`, `False` otherwise. + Returns `True` if the given point is inside this `Circle` (edge included), `False` otherwise. + It takes a tuple of (x, y) coordinates, two separate x and y coordinates, or a `Vector2` + object as its argument. .. versionadded:: 2.4.0 @@ -178,83 +167,33 @@ .. method:: collidecircle - | :sl:`test if two circles collide` + | :sl:`test if a circle collides with this circle` | :sg:`collidecircle(circle, /) -> bool` | :sg:`collidecircle(x, y, radius, /) -> bool` | :sg:`collidecircle((x, y), radius, /) -> bool` - The `collidecircle` method tests whether two `Circle` objects overlap. It takes either - a `Circle` object, a tuple of (x, y) coordinates and a radius, or separate x and y - coordinates and a radius as its argument, and returns `True` if any portion of the two - `Circle` objects overlap, `False` otherwise. + Returns `True` if the given circle intersects with this `Circle`, `False` otherwise. + It takes either a `Circle` object, a tuple of (x, y) coordinates and a radius, or separate x and y + coordinates and a radius as its argument. .. note:: - If this method is called with a `Circle` object that is the same as the `Circle` - it is called on, it will always return `True`. + Calling this method with this circle as the argument will always return `True`. .. versionadded:: 2.4.0 .. ## Circle.collidecircle ## - .. method:: move - - | :sl:`moves the circle by a given amount` - | :sg:`move((x, y), /) -> Circle` - | :sg:`move(x, y, /) -> Circle` - | :sg:`move(vector2, /) -> Circle` - - The `move` method allows you to create a new `Circle` object that is moved by a given - offset from the original `Circle`. This is useful if you want to move a `Circle` without - modifying the original. The move method takes either a tuple of (x, y) coordinates, - two separate x and y coordinates, or a `Vector2` object as its argument, and returns - a new `Circle` object with the updated position. - - .. note:: - This method is equivalent(behaviour wise) to the following code: - - .. code-block:: python - - Circle((circle.x + x, circle.y + y), circle.r) - - .. versionadded:: 2.5.0 - - .. ## Circle.move ## - - .. method:: move_ip - - | :sl:`moves the circle by a given amount, in place` - | :sg:`move_ip((x, y), /) -> None` - | :sg:`move_ip(x, y, /) -> None` - | :sg:`move_ip(vector2, /) -> None` - - The `move_ip` method is similar to the move method, but it moves the `Circle` in place, - modifying the original `Circle` object. This method takes the same types of arguments - as move, and it always returns None. - - .. note:: - This method is equivalent(behaviour wise) to the following code: - - .. code-block:: python - - circle.x += x - circle.y += y - - .. versionadded:: 2.5.0 - - .. ## Circle.move_ip ## - .. method:: colliderect - | :sl:`checks if a rectangle intersects the circle` + | :sl:`test if a rectangle collides with this circle` | :sg:`colliderect(rect, /) -> bool` | :sg:`colliderect((x, y, width, height), /) -> bool` | :sg:`colliderect(x, y, width, height, /) -> bool` | :sg:`colliderect((x, y), (width, height), /) -> bool` - The `colliderect` method tests whether a given rectangle intersects the `Circle`. It - takes either a `Rect` object, a tuple of (x, y, width, height) coordinates, or separate - x, y coordinates and width, height as its argument. Returns `True` if any portion - of the rectangle overlaps with the `Circle`, `False` otherwise. + Returns `True` if the given rectangle intersects with this `Circle`, `False` otherwise. + Takes either a `Rect` object, a tuple of (x, y, width, height) coordinates, or separate + x, y coordinates and width, height as its argument. .. versionadded:: 2.4.0 @@ -262,7 +201,7 @@ .. method:: collideswith - | :sl:`check if a shape or point collides with the circle` + | :sl:`tests if a shape or point collides with this circle` | :sg:`collideswith(circle, /) -> bool` | :sg:`collideswith(rect, /) -> bool` | :sg:`collideswith((x, y), /) -> bool` @@ -283,15 +222,14 @@ .. method:: contains - | :sl:`check if a shape or point is inside the circle` + | :sl:`tests if a shape or point is inside the circle` | :sg:`contains(circle, /) -> bool` | :sg:`contains(rect, /) -> bool` | :sg:`contains((x, y), /) -> bool` | :sg:`contains(vector2, /) -> bool` - Checks whether a given shape or point is completely contained within the `Circle`. - Takes a single argument which can be a `Circle`, `Rect`, `FRect`, or a point. Returns `True` if the shape or point is completely contained, and `False` otherwise. + Takes a single argument which can be a `Circle`, `Rect`, `FRect`, or a point. .. note:: The shape argument must be an actual shape object (`Circle`, `Rect`, or `FRect`). @@ -302,6 +240,50 @@ .. ## Circle.contains ## + .. method:: move + + | :sl:`moves the circle by a given amount` + | :sg:`move((x, y), /) -> Circle` + | :sg:`move(x, y, /) -> Circle` + | :sg:`move(vector2, /) -> Circle` + + Returns a copy of this `Circle` that is moved by the given amount. + Takes either a tuple of (x, y) coordinates, two separate x and y coordinates, + or a `Vector2` object as its argument. + + .. note:: + This method is equivalent (behaviour wise) to the following code: + + .. code-block:: python + + Circle((circle.x + x, circle.y + y), circle.r) + + .. versionadded:: 2.5.0 + + .. ## Circle.move ## + + .. method:: move_ip + + | :sl:`moves the circle by a given amount, in place` + | :sg:`move_ip((x, y), /) -> None` + | :sg:`move_ip(x, y, /) -> None` + | :sg:`move_ip(vector2, /) -> None` + + Moves this `Circle` in place by the given amount + Takes the same types of arguments as move, and it always returns `None`. + + .. note:: + This method is equivalent (behaviour wise) to the following code: + + .. code-block:: python + + circle.x += x + circle.y += y + + .. versionadded:: 2.5.0 + + .. ## Circle.move_ip ## + .. method:: update | :sl:`updates the circle position and radius` @@ -313,7 +295,7 @@ y coordinates, and a radius as its arguments, and it always returns `None`. .. note:: - This method is equivalent(behaviour wise) to the following code: + This method is equivalent (behaviour wise) to the following code: .. code-block:: python @@ -331,10 +313,10 @@ | :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. + Returns a copy of this `Circle` rotated by the specified angle (in degrees) around a point. + Positive angles mean clockwise rotation, while negative angles mean counter-clockwise rotation. + The rotation point is optional and must be a valid 2D coordinate. If not provided, + the circle will be rotated around its center. .. versionadded:: 2.5.0 @@ -347,10 +329,10 @@ | :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. + Rotates the circle by a specified angle (in degrees) around a point. + Positive angles mean clockwise rotation, while negative angles mean counter-clockwise rotation. + The rotation point is optional and must be a valid 2D coordinate. If not provided, + the circle will be rotated around its center. .. versionadded:: 2.5.0 @@ -358,16 +340,13 @@ .. method:: as_rect - | :sl:`returns the smallest pygame.Rect object that contains the circle` + | :sl:`returns a Rect that contains the circle` | :sg:`as_rect() -> Rect` - The `as_rect` method returns a `pygame.Rect` object that represents the smallest - rectangle that completely contains the `Circle` object. This means that the `Rect` - object returned by as_rect will have dimensions such that it completely encloses - the `Circle`, with no part of the `Circle` extending outside of the `Rect`. + Returns the smallest `pygame.Rect` object containing this `Circle`. .. note:: - This method is equivalent(behaviour wise) to the following code: + This method is equivalent (behaviour wise) to the following code: .. code-block:: python @@ -379,16 +358,13 @@ .. method:: as_frect - | :sl:`returns the smallest pygame.FRect object that contains the circle` + | :sl:`returns an FRect that contains the circle` | :sg:`as_frect() -> FRect` - The `as_frect` method returns a `pygame.FRect` object that represents the smallest - rectangle that completely contains the `Circle` object. This means that the `FRect` - object returned by as_rect will have dimensions such that it completely encloses - the `Circle`, with no part of the `Circle` extending outside of the `FRect`. + Returns the smallest `pygame.FRect` object that contains this `Circle`. .. note:: - This method is equivalent(behaviour wise) to the following code: + This method is equivalent (behaviour wise) to the following code: .. code-block:: python @@ -400,12 +376,10 @@ .. method:: copy - | :sl:`returns a copy of the circle` + | :sl:`copies the circle` | :sg:`copy() -> Circle` - The `copy` method returns a new `Circle` object having the same position and radius - as the original `Circle` object. The function takes no arguments and returns the - new `Circle` object. + Returns a copy of this `Circle`. .. versionadded:: 2.4.0 From 10746c638505f2af992769b4cd5e39a35bc2457b Mon Sep 17 00:00:00 2001 From: itzpr3d4t0r <103119829+itzpr3d4t0r@users.noreply.github.com> Date: Wed, 7 Aug 2024 11:33:52 +0200 Subject: [PATCH 2/9] fixes --- docs/reST/ref/geometry.rst | 6 +++--- src_c/doc/geometry_doc.h | 14 +++++++------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/reST/ref/geometry.rst b/docs/reST/ref/geometry.rst index 3bc9e8bc34..34c7ac02e3 100644 --- a/docs/reST/ref/geometry.rst +++ b/docs/reST/ref/geometry.rst @@ -340,7 +340,7 @@ .. method:: as_rect - | :sl:`returns a Rect that contains the circle` + | :sl:`returns the smallest Rect containing the circle` | :sg:`as_rect() -> Rect` Returns the smallest `pygame.Rect` object containing this `Circle`. @@ -358,10 +358,10 @@ .. method:: as_frect - | :sl:`returns an FRect that contains the circle` + | :sl:`returns the smallest FRect containing the circle` | :sg:`as_frect() -> FRect` - Returns the smallest `pygame.FRect` object that contains this `Circle`. + Returns the smallest `pygame.FRect` object containing this `Circle`. .. note:: This method is equivalent (behaviour wise) to the following code: diff --git a/src_c/doc/geometry_doc.h b/src_c/doc/geometry_doc.h index 960714ff73..cf0bffe001 100644 --- a/src_c/doc/geometry_doc.h +++ b/src_c/doc/geometry_doc.h @@ -10,15 +10,15 @@ #define DOC_CIRCLE_AREA "area -> float\narea of the circle" #define DOC_CIRCLE_CIRCUMFERENCE "circumference -> float\ncircumference of the circle" #define DOC_CIRCLE_COLLIDEPOINT "collidepoint((x, y), /) -> bool\ncollidepoint(x, y, /) -> bool\ncollidepoint(vector2, /) -> bool\ntest if a point is inside the circle" -#define DOC_CIRCLE_COLLIDECIRCLE "collidecircle(circle, /) -> bool\ncollidecircle(x, y, radius, /) -> bool\ncollidecircle((x, y), radius, /) -> bool\ntest if two circles collide" +#define DOC_CIRCLE_COLLIDECIRCLE "collidecircle(circle, /) -> bool\ncollidecircle(x, y, radius, /) -> bool\ncollidecircle((x, y), radius, /) -> bool\ntest if a circle collides with this circle" +#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\ntest if a rectangle collides with this circle" +#define DOC_CIRCLE_COLLIDESWITH "collideswith(circle, /) -> bool\ncollideswith(rect, /) -> bool\ncollideswith((x, y), /) -> bool\ncollideswith(vector2, /) -> bool\ntests if a shape or point collides with this circle" +#define DOC_CIRCLE_CONTAINS "contains(circle, /) -> bool\ncontains(rect, /) -> bool\ncontains((x, y), /) -> bool\ncontains(vector2, /) -> bool\ntests if a shape or point is inside the circle" #define DOC_CIRCLE_MOVE "move((x, y), /) -> Circle\nmove(x, y, /) -> Circle\nmove(vector2, /) -> Circle\nmoves the circle by a given amount" #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_COLLIDESWITH "collideswith(circle, /) -> bool\ncollideswith(rect, /) -> bool\ncollideswith((x, y), /) -> bool\ncollideswith(vector2, /) -> bool\ncheck if a shape or point collides with the circle" -#define DOC_CIRCLE_CONTAINS "contains(circle, /) -> bool\ncontains(rect, /) -> bool\ncontains((x, y), /) -> bool\ncontains(vector2, /) -> bool\ncheck if a shape or point is inside 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" +#define DOC_CIRCLE_ASRECT "as_rect() -> Rect\nreturns a Rect that contains the circle" +#define DOC_CIRCLE_ASFRECT "as_frect() -> FRect\nreturns an FRect that contains the circle" +#define DOC_CIRCLE_COPY "copy() -> Circle\ncopies the circle" From c60c3815eb449d88ea5a126bfd820effdc8012d1 Mon Sep 17 00:00:00 2001 From: itzpr3d4t0r <103119829+itzpr3d4t0r@users.noreply.github.com> Date: Wed, 7 Aug 2024 11:34:29 +0200 Subject: [PATCH 3/9] fixes --- src_c/doc/geometry_doc.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src_c/doc/geometry_doc.h b/src_c/doc/geometry_doc.h index cf0bffe001..2295d99966 100644 --- a/src_c/doc/geometry_doc.h +++ b/src_c/doc/geometry_doc.h @@ -19,6 +19,6 @@ #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 a Rect that contains the circle" -#define DOC_CIRCLE_ASFRECT "as_frect() -> FRect\nreturns an FRect that contains the circle" +#define DOC_CIRCLE_ASRECT "as_rect() -> Rect\nreturns the smallest Rect containing the circle" +#define DOC_CIRCLE_ASFRECT "as_frect() -> FRect\nreturns the smallest FRect containing the circle" #define DOC_CIRCLE_COPY "copy() -> Circle\ncopies the circle" From ef3edfd5a1c7f00eb91e8ba2f7f8ae5307d1b878 Mon Sep 17 00:00:00 2001 From: itzpr3d4t0r <103119829+itzpr3d4t0r@users.noreply.github.com> Date: Wed, 7 Aug 2024 12:39:10 +0200 Subject: [PATCH 4/9] more changes: - now using math formulas to describe attributes - remove more self references - Simpler phrases - Add missing vector2 as params --- docs/reST/ref/geometry.rst | 57 ++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 30 deletions(-) diff --git a/docs/reST/ref/geometry.rst b/docs/reST/ref/geometry.rst index 34c7ac02e3..83b8eff80c 100644 --- a/docs/reST/ref/geometry.rst +++ b/docs/reST/ref/geometry.rst @@ -27,7 +27,7 @@ The `Circle` class provides many useful methods for collision, transformation, and intersection. A `Circle` can be created from a combination of a pair of coordinates that represent the center of the circle and a radius. Circles can also be created from python objects that - are already a `Circle` or have an attribute named "circle". + are already a `Circle` (effectively copying the circle) or have an attribute named "circle". Specifically, to construct a circle you can pass the x, y, and radius values as separate arguments or inside a sequence(list or tuple). @@ -39,11 +39,8 @@ ((x, y), radius) (x, y, radius) - The `Circle` class has both virtual and non-virtual attributes. Non-virtual attributes - are attributes that are stored in the `Circle` object itself. Virtual attributes are the - result of calculations that utilize the Circle's non-virtual attributes. - - Here is the list of all the attributes and methods of the Circle class: + The `Circle` class only stores the x, y and r attributes, everything else is calculated + on the fly based on them. **Circle Attributes** @@ -54,7 +51,7 @@ | :sl:`center x coordinate of the circle` | :sg:`x -> float` - The `x` coordinate of the center of the circle. It can be reassigned to move the circle. + The horizontal coordinate of the center of the circle. Reassigning it moves the circle. .. versionadded:: 2.4.0 @@ -65,7 +62,7 @@ | :sl:`center y coordinate of the circle` | :sg:`y -> float` - The `y` coordinate of the center of the circle. It can be reassigned to move the circle. + The vertical coordinate of the center of the circle. Reassigning it moves the circle. .. versionadded:: 2.4.0 @@ -76,8 +73,7 @@ | :sl:`radius of the circle` | :sg:`r -> float` - Represents how big the circle is. - It is not possible to set the radius to a negative value. It can be reassigned. + Represents how big the circle is. It can't be negative. Reassigning it scales the circle. .. versionadded:: 2.4.0 @@ -91,8 +87,7 @@ | :sl:`radius of the circle squared` | :sg:`r_sqr -> float` - It's equivalent to `r*r`. If reassigned, the radius of the circle will be changed - to the square root of the new value. + It's equivalent to :math:`r^2`. Reassigning it changes the radius to :math:`r = \sqrt{r_{sqr}}`. .. versionadded:: 2.4.0 @@ -104,7 +99,7 @@ | :sg:`center -> (float, float)` It's a tuple containing the circle's `x` and `y` coordinates representing its center. - If reassigned, the circle will be moved to the new position. + Reassigning it moves the circle to the new position. .. versionadded:: 2.4.0 @@ -115,8 +110,8 @@ | :sl:`diameter of the circle` | :sg:`diameter -> float` - It's calculated using the `d=2*r` formula. If reassigned the radius will be changed - to half the diameter. + It's equivalent to :math:`2 \cdot r`. It can't be negative. Reassigning it + changes the radius to :math:`r = \frac{d}{2}`. .. versionadded:: 2.4.0 @@ -127,8 +122,8 @@ | :sl:`area of the circle` | :sg:`area -> float` - It's calculated using the `area=pi*r*r` formula. If reassigned the circle radius - will be changed to produce a circle with matching area. + It's equivalent to :math:`\pi \cdot r^2`. It can't be negative. Reassigning it + changes the radius to :math:`r = \sqrt{\frac{area}{\pi}}` producing a circle with matching area. .. versionadded:: 2.4.0 @@ -139,8 +134,9 @@ | :sl:`circumference of the circle` | :sg:`circumference -> float` - It's calculated using the `circumference=2*pi*r` formula. If reassigned the circle - radius will be changed to produce a circle with matching circumference. + It's equivalent to :math:`2 \cdot \pi \cdot r`. It can't be negative. Reassigning it + changes the radius to :math:`r = \frac{circumference}{2\pi}` producing a circle with + matching circumference. .. versionadded:: 2.4.0 @@ -171,6 +167,7 @@ | :sg:`collidecircle(circle, /) -> bool` | :sg:`collidecircle(x, y, radius, /) -> bool` | :sg:`collidecircle((x, y), radius, /) -> bool` + | :sg:`collidecircle(vector2, radius, /) -> bool` Returns `True` if the given circle intersects with this `Circle`, `False` otherwise. It takes either a `Circle` object, a tuple of (x, y) coordinates and a radius, or separate x and y @@ -190,6 +187,7 @@ | :sg:`colliderect((x, y, width, height), /) -> bool` | :sg:`colliderect(x, y, width, height, /) -> bool` | :sg:`colliderect((x, y), (width, height), /) -> bool` + | :sg:`colliderect(vector2, (width, height), /) -> bool` Returns `True` if the given rectangle intersects with this `Circle`, `False` otherwise. Takes either a `Rect` object, a tuple of (x, y, width, height) coordinates, or separate @@ -207,9 +205,8 @@ | :sg:`collideswith((x, y), /) -> bool` | :sg:`collideswith(vector2, /) -> bool` - The `collideswith` method checks if a shape or point overlaps with a `Circle` object. - It takes a single argument which can be a `Circle`, `Rect`, `FRect`, or a point. - It returns `True` if there's an overlap, and `False` otherwise. + Returns `True` if the given shape or point intersects with this `Circle`, `False` otherwise. + The shape can be a `Circle`, `Rect`, `FRect`. .. note:: The shape argument must be an actual shape object (`Circle`, `Rect`, or `FRect`). @@ -228,8 +225,8 @@ | :sg:`contains((x, y), /) -> bool` | :sg:`contains(vector2, /) -> bool` - Returns `True` if the shape or point is completely contained, and `False` otherwise. - Takes a single argument which can be a `Circle`, `Rect`, `FRect`, or a point. + Returns `True` if the shape or point is completely contained within this `Circle`, `False` otherwise. + The shape can be a `Circle`, `Rect`, `FRect`. .. note:: The shape argument must be an actual shape object (`Circle`, `Rect`, or `FRect`). @@ -269,7 +266,7 @@ | :sg:`move_ip(x, y, /) -> None` | :sg:`move_ip(vector2, /) -> None` - Moves this `Circle` in place by the given amount + Moves this `Circle` in place by the given amount. Takes the same types of arguments as move, and it always returns `None`. .. note:: @@ -289,10 +286,10 @@ | :sl:`updates the circle position and radius` | :sg:`update((x, y), radius, /) -> None` | :sg:`update(x, y, radius, /) -> None` + | :sg:`update(vector2, radius, /) -> None` - The `update` method allows you to set the position and radius of a `Circle` object in - place. This method takes either a tuple of (x, y) coordinates, two separate x and - y coordinates, and a radius as its arguments, and it always returns `None`. + Sets the position and radius of this `Circle` to the provided values. + It always returns `None`. .. note:: This method is equivalent (behaviour wise) to the following code: @@ -314,7 +311,7 @@ | :sg:`rotate(angle, /) -> Circle` Returns a copy of this `Circle` rotated by the specified angle (in degrees) around a point. - Positive angles mean clockwise rotation, while negative angles mean counter-clockwise rotation. + Positive angles rotate the circle clockwise, counter-clockwise otherwise. The rotation point is optional and must be a valid 2D coordinate. If not provided, the circle will be rotated around its center. @@ -330,7 +327,7 @@ Rotates the circle by a specified angle (in degrees) around a point. - Positive angles mean clockwise rotation, while negative angles mean counter-clockwise rotation. + Positive angles rotate the circle clockwise, counter-clockwise otherwise. The rotation point is optional and must be a valid 2D coordinate. If not provided, the circle will be rotated around its center. From 7cff3f24f7cd6c2b5f8cb69136f8b355404f178e Mon Sep 17 00:00:00 2001 From: itzpr3d4t0r <103119829+itzpr3d4t0r@users.noreply.github.com> Date: Wed, 7 Aug 2024 12:45:55 +0200 Subject: [PATCH 5/9] fixes --- docs/reST/ref/geometry.rst | 7 +++---- src_c/doc/geometry_doc.h | 6 +++--- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/reST/ref/geometry.rst b/docs/reST/ref/geometry.rst index 83b8eff80c..f554618dca 100644 --- a/docs/reST/ref/geometry.rst +++ b/docs/reST/ref/geometry.rst @@ -73,12 +73,11 @@ | :sl:`radius of the circle` | :sg:`r -> float` - Represents how big the circle is. It can't be negative. Reassigning it scales the circle. + Represents the size of the circle. It can't be negative. Reassigning it scales the circle. .. versionadded:: 2.4.0 - .. versionchanged:: 2.5.1 It is allowed to create degenerate circles with radius - equal to ``0``. This also applies to virtual attributes. + .. versionchanged:: 2.5.1 It is now allowed to create degenerate circles with :math:`r = 0`. .. ## Circle.r ## @@ -87,7 +86,7 @@ | :sl:`radius of the circle squared` | :sg:`r_sqr -> float` - It's equivalent to :math:`r^2`. Reassigning it changes the radius to :math:`r = \sqrt{r_{sqr}}`. + It's equivalent to :math:`r^2`. It can't be negative. Reassigning it changes the radius to :math:`r = \sqrt{r_{sqr}}`. .. versionadded:: 2.4.0 diff --git a/src_c/doc/geometry_doc.h b/src_c/doc/geometry_doc.h index 2295d99966..49e7144b74 100644 --- a/src_c/doc/geometry_doc.h +++ b/src_c/doc/geometry_doc.h @@ -10,13 +10,13 @@ #define DOC_CIRCLE_AREA "area -> float\narea of the circle" #define DOC_CIRCLE_CIRCUMFERENCE "circumference -> float\ncircumference of the circle" #define DOC_CIRCLE_COLLIDEPOINT "collidepoint((x, y), /) -> bool\ncollidepoint(x, y, /) -> bool\ncollidepoint(vector2, /) -> bool\ntest if a point is inside the circle" -#define DOC_CIRCLE_COLLIDECIRCLE "collidecircle(circle, /) -> bool\ncollidecircle(x, y, radius, /) -> bool\ncollidecircle((x, y), radius, /) -> bool\ntest if a circle collides with this circle" -#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\ntest if a rectangle collides with this circle" +#define DOC_CIRCLE_COLLIDECIRCLE "collidecircle(circle, /) -> bool\ncollidecircle(x, y, radius, /) -> bool\ncollidecircle((x, y), radius, /) -> bool\ncollidecircle(vector2, radius, /) -> bool\ntest if a circle collides with this circle" +#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\ncolliderect(vector2, (width, height), /) -> bool\ntest if a rectangle collides with this circle" #define DOC_CIRCLE_COLLIDESWITH "collideswith(circle, /) -> bool\ncollideswith(rect, /) -> bool\ncollideswith((x, y), /) -> bool\ncollideswith(vector2, /) -> bool\ntests if a shape or point collides with this circle" #define DOC_CIRCLE_CONTAINS "contains(circle, /) -> bool\ncontains(rect, /) -> bool\ncontains((x, y), /) -> bool\ncontains(vector2, /) -> bool\ntests if a shape or point is inside the circle" #define DOC_CIRCLE_MOVE "move((x, y), /) -> Circle\nmove(x, y, /) -> Circle\nmove(vector2, /) -> Circle\nmoves the circle by a given amount" #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_UPDATE "update((x, y), radius, /) -> None\nupdate(x, y, radius, /) -> None\nupdates the circle position and radius" +#define DOC_CIRCLE_UPDATE "update((x, y), radius, /) -> None\nupdate(x, y, radius, /) -> None\nupdate(vector2, 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 Rect containing the circle" From 496ad477810a07ea5398be8c88cb1a52369013b6 Mon Sep 17 00:00:00 2001 From: itzpr3d4t0r <103119829+itzpr3d4t0r@users.noreply.github.com> Date: Wed, 7 Aug 2024 13:00:14 +0200 Subject: [PATCH 6/9] remove (behaviour wise), add one extra case for good circle-like param, add actual link to move method inside move_ip --- docs/reST/ref/geometry.rst | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/reST/ref/geometry.rst b/docs/reST/ref/geometry.rst index f554618dca..94b57710cd 100644 --- a/docs/reST/ref/geometry.rst +++ b/docs/reST/ref/geometry.rst @@ -38,6 +38,7 @@ ((x, y), radius) (x, y, radius) + (vector2, radius) The `Circle` class only stores the x, y and r attributes, everything else is calculated on the fly based on them. @@ -248,7 +249,7 @@ or a `Vector2` object as its argument. .. note:: - This method is equivalent (behaviour wise) to the following code: + This method is equivalent to the following code: .. code-block:: python @@ -266,10 +267,10 @@ | :sg:`move_ip(vector2, /) -> None` Moves this `Circle` in place by the given amount. - Takes the same types of arguments as move, and it always returns `None`. + Takes the same types of arguments as :meth:`move` and it always returns `None`. .. note:: - This method is equivalent (behaviour wise) to the following code: + This method is equivalent to the following code: .. code-block:: python @@ -291,7 +292,7 @@ It always returns `None`. .. note:: - This method is equivalent (behaviour wise) to the following code: + This method is equivalent to the following code: .. code-block:: python @@ -311,8 +312,7 @@ Returns a copy of this `Circle` rotated by the specified angle (in degrees) around a point. Positive angles rotate the circle clockwise, counter-clockwise otherwise. - The rotation point is optional and must be a valid 2D coordinate. If not provided, - the circle will be rotated around its center. + The rotation point is optional and defaults to the circle's center. .. versionadded:: 2.5.0 @@ -324,11 +324,9 @@ | :sg:`rotate_ip(angle, rotation_point=Circle.center, /) -> None` | :sg:`rotate_ip(angle, /) -> None` - Rotates the circle by a specified angle (in degrees) around a point. Positive angles rotate the circle clockwise, counter-clockwise otherwise. - The rotation point is optional and must be a valid 2D coordinate. If not provided, - the circle will be rotated around its center. + The rotation point is optional and defaults to the circle's center. .. versionadded:: 2.5.0 @@ -342,7 +340,7 @@ Returns the smallest `pygame.Rect` object containing this `Circle`. .. note:: - This method is equivalent (behaviour wise) to the following code: + This method is equivalent to the following code: .. code-block:: python @@ -360,7 +358,7 @@ Returns the smallest `pygame.FRect` object containing this `Circle`. .. note:: - This method is equivalent (behaviour wise) to the following code: + This method is equivalent to the following code: .. code-block:: python From 2f0ffff595716d812fadc75e3269c7c87492d676 Mon Sep 17 00:00:00 2001 From: itzpr3d4t0r <103119829+itzpr3d4t0r@users.noreply.github.com> Date: Wed, 7 Aug 2024 13:02:52 +0200 Subject: [PATCH 7/9] uniform s --- docs/reST/ref/geometry.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reST/ref/geometry.rst b/docs/reST/ref/geometry.rst index 94b57710cd..7b03e6d2f2 100644 --- a/docs/reST/ref/geometry.rst +++ b/docs/reST/ref/geometry.rst @@ -24,7 +24,7 @@ | :sg:`Circle((x, y), radius) -> Circle` | :sg:`Circle(x, y, radius) -> Circle` - The `Circle` class provides many useful methods for collision, transformation, and intersection. + The `Circle` class provides many useful methods for collision testing, transformation and intersection. A `Circle` can be created from a combination of a pair of coordinates that represent the center of the circle and a radius. Circles can also be created from python objects that are already a `Circle` (effectively copying the circle) or have an attribute named "circle". @@ -148,7 +148,7 @@ .. method:: collidepoint - | :sl:`test if a point is inside the circle` + | :sl:`tests if a point is inside the circle` | :sg:`collidepoint((x, y), /) -> bool` | :sg:`collidepoint(x, y, /) -> bool` | :sg:`collidepoint(vector2, /) -> bool` @@ -163,7 +163,7 @@ .. method:: collidecircle - | :sl:`test if a circle collides with this circle` + | :sl:`tests if a circle collides with this circle` | :sg:`collidecircle(circle, /) -> bool` | :sg:`collidecircle(x, y, radius, /) -> bool` | :sg:`collidecircle((x, y), radius, /) -> bool` @@ -182,7 +182,7 @@ .. method:: colliderect - | :sl:`test if a rectangle collides with this circle` + | :sl:`tests if a rectangle collides with this circle` | :sg:`colliderect(rect, /) -> bool` | :sg:`colliderect((x, y, width, height), /) -> bool` | :sg:`colliderect(x, y, width, height, /) -> bool` From 126cf47277aa9c3e5f58d026dbd0c7c14e20c11e Mon Sep 17 00:00:00 2001 From: itzpr3d4t0r <103119829+itzpr3d4t0r@users.noreply.github.com> Date: Wed, 7 Aug 2024 13:03:11 +0200 Subject: [PATCH 8/9] fix docs h --- src_c/doc/geometry_doc.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src_c/doc/geometry_doc.h b/src_c/doc/geometry_doc.h index 49e7144b74..e179cbf874 100644 --- a/src_c/doc/geometry_doc.h +++ b/src_c/doc/geometry_doc.h @@ -9,9 +9,9 @@ #define DOC_CIRCLE_DIAMETER "diameter -> float\ndiameter of the circle" #define DOC_CIRCLE_AREA "area -> float\narea of the circle" #define DOC_CIRCLE_CIRCUMFERENCE "circumference -> float\ncircumference of the circle" -#define DOC_CIRCLE_COLLIDEPOINT "collidepoint((x, y), /) -> bool\ncollidepoint(x, y, /) -> bool\ncollidepoint(vector2, /) -> bool\ntest if a point is inside the circle" -#define DOC_CIRCLE_COLLIDECIRCLE "collidecircle(circle, /) -> bool\ncollidecircle(x, y, radius, /) -> bool\ncollidecircle((x, y), radius, /) -> bool\ncollidecircle(vector2, radius, /) -> bool\ntest if a circle collides with this circle" -#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\ncolliderect(vector2, (width, height), /) -> bool\ntest if a rectangle collides with this circle" +#define DOC_CIRCLE_COLLIDEPOINT "collidepoint((x, y), /) -> bool\ncollidepoint(x, y, /) -> bool\ncollidepoint(vector2, /) -> bool\ntests if a point is inside the circle" +#define DOC_CIRCLE_COLLIDECIRCLE "collidecircle(circle, /) -> bool\ncollidecircle(x, y, radius, /) -> bool\ncollidecircle((x, y), radius, /) -> bool\ncollidecircle(vector2, radius, /) -> bool\ntests if a circle collides with this circle" +#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\ncolliderect(vector2, (width, height), /) -> bool\ntests if a rectangle collides with this circle" #define DOC_CIRCLE_COLLIDESWITH "collideswith(circle, /) -> bool\ncollideswith(rect, /) -> bool\ncollideswith((x, y), /) -> bool\ncollideswith(vector2, /) -> bool\ntests if a shape or point collides with this circle" #define DOC_CIRCLE_CONTAINS "contains(circle, /) -> bool\ncontains(rect, /) -> bool\ncontains((x, y), /) -> bool\ncontains(vector2, /) -> bool\ntests if a shape or point is inside the circle" #define DOC_CIRCLE_MOVE "move((x, y), /) -> Circle\nmove(x, y, /) -> Circle\nmove(vector2, /) -> Circle\nmoves the circle by a given amount" From 0e7cb7c512b8d52b1ec7043a16451a64c8b75075 Mon Sep 17 00:00:00 2001 From: itzpr3d4t0r <103119829+itzpr3d4t0r@users.noreply.github.com> Date: Wed, 7 Aug 2024 13:13:26 +0200 Subject: [PATCH 9/9] moved equivalent code outside of notes --- docs/reST/ref/geometry.rst | 45 +++++++++++++++++--------------------- 1 file changed, 20 insertions(+), 25 deletions(-) diff --git a/docs/reST/ref/geometry.rst b/docs/reST/ref/geometry.rst index 7b03e6d2f2..dc16f6dec3 100644 --- a/docs/reST/ref/geometry.rst +++ b/docs/reST/ref/geometry.rst @@ -244,16 +244,15 @@ | :sg:`move(x, y, /) -> Circle` | :sg:`move(vector2, /) -> Circle` - Returns a copy of this `Circle` that is moved by the given amount. + Returns a copy of this `Circle` moved by the given amounts. Takes either a tuple of (x, y) coordinates, two separate x and y coordinates, or a `Vector2` object as its argument. - .. note:: - This method is equivalent to the following code: + This method is equivalent to the following code: - .. code-block:: python + .. code-block:: python - Circle((circle.x + x, circle.y + y), circle.r) + Circle((circle.x + x, circle.y + y), circle.r) .. versionadded:: 2.5.0 @@ -266,16 +265,15 @@ | :sg:`move_ip(x, y, /) -> None` | :sg:`move_ip(vector2, /) -> None` - Moves this `Circle` in place by the given amount. + Moves this `Circle` in place by the given amounts. Takes the same types of arguments as :meth:`move` and it always returns `None`. - .. note:: - This method is equivalent to the following code: + This method is equivalent to the following code: - .. code-block:: python + .. code-block:: python - circle.x += x - circle.y += y + circle.x += x + circle.y += y .. versionadded:: 2.5.0 @@ -291,14 +289,13 @@ Sets the position and radius of this `Circle` to the provided values. It always returns `None`. - .. note:: - This method is equivalent to the following code: + This method is equivalent to the following code: - .. code-block:: python + .. code-block:: python - circle.x = x - circle.y = y - circle.r = radius + circle.x = x + circle.y = y + circle.r = radius .. versionadded:: 2.4.0 @@ -339,12 +336,11 @@ Returns the smallest `pygame.Rect` object containing this `Circle`. - .. note:: - This method is equivalent to the following code: + This method is equivalent to the following code: - .. code-block:: python + .. code-block:: python - Rect(circle.x - circle.r, circle.y - circle.r, circle.r * 2, circle.r * 2) + Rect(circle.x - circle.r, circle.y - circle.r, circle.r * 2, circle.r * 2) .. versionadded:: 2.5.0 @@ -357,12 +353,11 @@ Returns the smallest `pygame.FRect` object containing this `Circle`. - .. note:: - This method is equivalent to the following code: + This method is equivalent to the following code: - .. code-block:: python + .. code-block:: python - FRect(circle.x - circle.r, circle.y - circle.r, circle.r * 2, circle.r * 2) + FRect(circle.x - circle.r, circle.y - circle.r, circle.r * 2, circle.r * 2) .. versionadded:: 2.5.0