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

—

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

pygame.Circle.x	—	center x coordinate of the circle
pygame.Circle.y	—	center y coordinate of the circle
pygame.Circle.r	—	radius of the circle
pygame.Circle.r_sqr	—	radius of the circle squared
pygame.Circle.center	—	x and y coordinates of the center of the circle
pygame.Circle.diameter	—	diameter of the circle
pygame.Circle.area	—	area of the circle
pygame.Circle.circumference	—	circumference of the circle
pygame.Circle.collidepoint	—	tests if a point is inside the circle
pygame.Circle.collidecircle	—	tests if a circle collides with this circle
pygame.Circle.colliderect	—	tests if a rectangle collides with this circle
pygame.Circle.collideswith	—	tests if a shape or point collides with this circle
pygame.Circle.contains	—	tests if a shape or point is inside the circle
pygame.Circle.move	—	moves the circle by a given amount
pygame.Circle.move_ip	—	moves the circle by a given amount, in place
pygame.Circle.intersect	—	finds intersections between the circle and a shape
pygame.Circle.update	—	updates the circle position and radius
pygame.Circle.rotate	—	rotates the circle
pygame.Circle.rotate_ip	—	rotates the circle in place
pygame.Circle.as_rect	—	returns the smallest Rect containing the circle
pygame.Circle.as_frect	—	returns the smallest FRect containing the circle
pygame.Circle.copy	—	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