pygame.geometry

Warning

Experimental Module

This module is a work in progress. Refrain from relying on any features provided by this module, as they are subject to change or removal without prior notice.

pygame object for representing a circle

New in pygame-ce 2.4.0.

pygame module for the Circle, Line, and Polygon objects
pygame.Circle
pygame object for representing a circle
Circle((x, y), radius) -> Circle
Circle(x, y, radius) -> Circle
center x coordinate of the circle
center y coordinate of the circle
radius of the circle
radius of the circle squared
x and y coordinates of the center of the circle
diameter of the circle
area of the circle
circumference of the circle
tests if a point is inside the circle
tests if a circle collides with this circle
tests if a rectangle collides with this circle
tests if a shape or point collides with this circle
tests if a shape or point is inside the circle
moves the circle by a given amount
moves the circle by a given amount, in place
finds intersections between the circle and a shape
updates the circle position and radius
rotates the circle
rotates the circle in place
returns the smallest Rect containing the circle
returns the smallest FRect containing the circle
copies the circle

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".

Specifically, to construct a circle you can pass the x, y, and radius values as separate arguments or inside a sequence(list or tuple).

Functions that require a Circle argument may also accept these values as Circles:

((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.

Circle Attributes


x
center x coordinate of the circle
x -> float

The horizontal coordinate of the center of the circle. Reassigning it moves the circle.

New in pygame-ce 2.4.0.

y
center y coordinate of the circle
y -> float

The vertical coordinate of the center of the circle. Reassigning it moves the circle.

New in pygame-ce 2.4.0.

r
radius of the circle
r -> float

Represents the size of the circle. It can't be negative. Reassigning it scales the circle.

New in pygame-ce 2.4.0.

Changed in pygame-ce 2.5.1: It is now allowed to create degenerate circles with \(r = 0\).

r_sqr
radius of the circle squared
r_sqr -> float

It's equivalent to \(r^2\). It can't be negative. Reassigning it changes the radius to \(r = \sqrt{r_{sqr}}\).

New in pygame-ce 2.4.0.

center
x and y coordinates of the center of the circle
center -> (float, float)

It's a tuple containing the circle's x and y coordinates representing its center. Reassigning it moves the circle to the new position.

New in pygame-ce 2.4.0.

diameter
diameter of the circle
diameter -> float

It's equivalent to \(2 \cdot r\). It can't be negative. Reassigning it changes the radius to \(r = \frac{d}{2}\).

New in pygame-ce 2.4.0.

area
area of the circle
area -> float

It's equivalent to \(\pi \cdot r^2\). It can't be negative. Reassigning it changes the radius to \(r = \sqrt{\frac{area}{\pi}}\) producing a circle with matching area.

New in pygame-ce 2.4.0.

circumference
circumference of the circle
circumference -> float

It's equivalent to \(2 \cdot \pi \cdot r\). It can't be negative. Reassigning it changes the radius to \(r = \frac{circumference}{2\pi}\) producing a circle with matching circumference.

New in pygame-ce 2.4.0.

Circle Methods


collidepoint()
tests if a point is inside the circle
collidepoint((x, y), /) -> bool
collidepoint(x, y, /) -> bool
collidepoint(vector2, /) -> bool

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.

New in pygame-ce 2.4.0.

collidecircle()
tests if a circle collides with this circle
collidecircle(circle, /) -> bool
collidecircle(x, y, radius, /) -> bool
collidecircle((x, y), radius, /) -> bool
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 coordinates and a radius as its argument.

Note

Calling this method with this circle as the argument will always return True.

New in pygame-ce 2.4.0.

colliderect()
tests if a rectangle collides with this circle
colliderect(rect, /) -> bool
colliderect((x, y, width, height), /) -> bool
colliderect(x, y, width, height, /) -> bool
colliderect((x, y), (width, height), /) -> bool
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 x, y coordinates and width, height as its argument.

New in pygame-ce 2.4.0.

collideswith()
tests if a shape or point collides with this circle
collideswith(circle, /) -> bool
collideswith(rect, /) -> bool
collideswith((x, y), /) -> bool
collideswith(vector2, /) -> bool

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). You can't pass a tuple or list of coordinates representing the shape (except for a point), because the shape type can't be determined from the coordinates alone.

New in pygame-ce 2.5.0.

contains()
tests if a shape or point is inside the circle
contains(circle, /) -> bool
contains(rect, /) -> bool
contains((x, y), /) -> bool
contains(vector2, /) -> bool

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). You can't pass a tuple or list of coordinates representing the shape (except for a point), because the shape type can't be determined from the coordinates alone.

New in pygame-ce 2.5.0.

move()
moves the circle by a given amount
move((x, y), /) -> Circle
move(x, y, /) -> Circle
move(vector2, /) -> Circle

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.

This method is equivalent to the following code:

Circle((circle.x + x, circle.y + y), circle.r)

New in pygame-ce 2.5.0.

move_ip()
moves the circle by a given amount, in place
move_ip((x, y), /) -> None
move_ip(x, y, /) -> None
move_ip(vector2, /) -> None

Moves this Circle in place by the given amounts. Takes the same types of arguments as move() and it always returns None.

This method is equivalent to the following code:

circle.x += x
circle.y += y

New in pygame-ce 2.5.0.

intersect()
finds intersections between the circle and a shape
intersect(circle, /) -> list

Finds and returns a list of intersection points between the circle and another shape. The other shape must be a Circle object. If the circle does not intersect or has infinite intersections, an empty list is returned.

Note

The shape argument must be an instance of the Circle class. Passing a tuple or list of coordinates representing the shape is not supported, as the type of shape cannot be determined from coordinates alone.

New in pygame-ce 2.5.2.

update()
updates the circle position and radius
update((x, y), radius, /) -> None
update(x, y, radius, /) -> None
update(vector2, radius, /) -> None

Sets the position and radius of this Circle to the provided values. It always returns None.

This method is equivalent to the following code:

circle.x = x
circle.y = y
circle.r = radius

New in pygame-ce 2.4.0.

rotate()
rotates the circle
rotate(angle, rotation_point=Circle.center, /) -> Circle
rotate(angle, /) -> Circle

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 defaults to the circle's center.

New in pygame-ce 2.5.0.

rotate_ip()
rotates the circle in place
rotate_ip(angle, rotation_point=Circle.center, /) -> None
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 defaults to the circle's center.

New in pygame-ce 2.5.0.

as_rect()
returns the smallest Rect containing the circle
as_rect() -> Rect

Returns the smallest pygame.Rect object containing this Circle.

This method is equivalent to the following code:

Rect(circle.x - circle.r, circle.y - circle.r, circle.r * 2, circle.r * 2)

New in pygame-ce 2.5.0.

as_frect()
returns the smallest FRect containing the circle
as_frect() -> FRect

Returns the smallest pygame.FRect object containing this Circle.

This method is equivalent to the following code:

FRect(circle.x - circle.r, circle.y - circle.r, circle.r * 2, circle.r * 2)

New in pygame-ce 2.5.0.

copy()
copies the circle
copy() -> Circle

Returns a copy of this Circle.

New in pygame-ce 2.4.0.




Edit on GitHub