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
pygame.Line
 — pygame object for representing a line

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.top
 — top coordinate of the circle
pygame.Circle.bottom
 — bottom coordinate of the circle
pygame.Circle.left
 — left coordinate of the circle
pygame.Circle.right
 — right coordinate 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.collidelist
 — test if a list of objects collide with the circle
pygame.Circle.collidelistall
 — test if all objects in a list collide with the 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)

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.

top
top coordinate of the circle
top -> (float, float)

A tuple containing the x and y coordinates that represent the top of the circle. Reassigning it moves the circle to the new position. The radius will not be affected.

New in pygame-ce 2.5.2.

bottom
bottom coordinate of the circle
bottom -> (float, float)

A tuple containing the x and y coordinates that represent the bottom of the circle. Reassigning it moves the circle to the new position. The radius will not be affected.

New in pygame-ce 2.5.2.

left
left coordinate of the circle
left -> (float, float)

A tuple containing the x and y coordinates that represent the left of the circle. Reassigning it moves the circle to the new position. The radius will not be affected.

New in pygame-ce 2.5.2.

right
right coordinate of the circle
right -> (float, float)

A tuple containing the x and y coordinates that represent the right of the circle. Reassigning it moves the circle to the new position. The radius will not be affected.

New in pygame-ce 2.5.2.

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.

collidelist()
test if a list of objects collide with the circle
collidelist(colliders) -> int

The collidelist method tests whether a given list of shapes or points collides (overlaps) with this Circle object. The function takes in a single argument, which must be a list of Circle, Rect, FRect, or a point. The function returns the index of the first shape or point in the list that collides with the Circle object, or -1 if there is no collision.

Note

The shapes must be actual shape objects, such as Circle, Rect or FRect instances. It is not possible to pass a tuple or list of coordinates representing the shape as an argument (except for a point), because the shape type can't be determined from the coordinates alone.

New in pygame-ce 2.5.2.

collidelistall()
test if all objects in a list collide with the circle
collidelistall(colliders) -> list

The collidelistall method tests whether a given list of shapes or points collides (overlaps) with this Circle object. The function takes in a single argument, which must be a list of Circle, Rect, FRect, or a point. The function returns a list containing the indices of all the shapes or points in the list that collide with the Circle object, or an empty list if there is no collision.

Note

The shapes must be actual shape objects, such as Circle, Rect or FRect instances. It is not possible to pass a tuple or list of coordinates representing the shape as an argument (except for a point), because the shape type can't be determined from the coordinates alone.

New in pygame-ce 2.5.2.

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.

pygame.Line
pygame object for representing a line
Line((ax, ay), (bx, by)) -> Line
Line(ax, ay, bx, by) -> Line
pygame.Line.ax
 — x coordinate of the start point of the line
pygame.Line.ay
 — y coordinate of the start point of the line
pygame.Line.bx
 — x coordinate of the end point of the line
pygame.Line.by
 — y coordinate of the end point of the line
pygame.Line.a
 — the first point of the line
pygame.Line.b
 — the second point of the line
pygame.Line.length
 — the length of the line
pygame.Line.copy
 — copies the line
pygame.Line.move
 — moves the line by a given amount
pygame.Line.move_ip
 — moves the line by a given amount
pygame.Line.update
 — updates the line's attributes
pygame.Line.scale
 — scales the line by the given factor from the given origin
pygame.Line.scale_ip
 — scales the line by the given factor from the given origin in place
pygame.Line.flip_ab
 — flips the line a and b points
pygame.Line.flip_ab_ip
 — flips the line a and b points, in place

New in pygame-ce 2.5.2.

The Line class provides many useful methods for collision testing, transformation and intersection. A Line can be created from a combination of two pairs of coordinates that represent the start and end points. Lines can also be created from python objects that are already a Line (effectively copying the line) or have an attribute named "line".

Specifically, to construct a Line you can pass the ax, ay, bx, and by values as separate arguments or inside a sequence(list or tuple).

As a special case you can also pass in pygame.Rect / pygame.FRect, in which case the line will be created with (x, y, width, height) as the start and end points.

You can create lines with the same start and end points, but beware that some methods may not work as expected or error out.

Functions that require a Line argument may also accept these values as Lines:

((ax, ay), (bx, by))
(ax, ay, bx, by)
(vector2, vector2)

The Line class only stores the ax, ay, bx, and by attributes, everything else is calculated on the fly based on them.

Line Attributes

ax
x coordinate of the start point of the line
ax -> float

The horizontal coordinate of the start point of the line. Reassigning it moves the line.

New in pygame-ce 2.5.2.

ay
y coordinate of the start point of the line
ay -> float

The vertical coordinate of the start point of the line. Reassigning it moves the line.

New in pygame-ce 2.5.2.

bx
x coordinate of the end point of the line
bx -> float

The horizontal coordinate of the end point of the line. Reassigning it moves the line.

New in pygame-ce 2.5.2.

by
y coordinate of the end point of the line
by -> float

The vertical coordinate of the end point of the line. Reassigning it moves the line.

New in pygame-ce 2.5.2.

a
the first point of the line
a -> (float, float)

A tuple containing the ax and ay attributes representing the line's first point. It can be reassigned to move the Line. If reassigned the ax and ay attributes will be changed to produce a Line with matching first point position. The bx and by attributes will not be affected.

New in pygame-ce 2.5.2.

b
the second point of the line
b -> (float, float)

A tuple containing bx and by attributes representing the line's second point. It can be reassigned to move the Line. If reassigned the bx and by attributes will be changed to produce a Line with matching second point position. The ax and ay attributes will not be affected.

New in pygame-ce 2.5.2.

length
the length of the line
length -> float

The length of the line. Calculated using the sqrt((bx-ax)**2 + (by-ay)**2) formula. This attribute is read-only, it cannot be reassigned. To change the line's length use the scale method or change its a or b attributes.

New in pygame-ce 2.5.3.

Line Methods

copy()
copies the line
copy() -> Line

Returns a copy of this Line.

New in pygame-ce 2.5.2.

move()
moves the line by a given amount
move((x, y)) -> Line
move(x, y) -> Line

Returns a new Line that is moved by the given offset. The original Line is not modified.

This method is equivalent to the following code:

Line(line.ax + x, line.ay + y, line.bx + x, line.by + y)

New in pygame-ce 2.5.3.

move_ip()
moves the line by a given amount
move_ip((x, y)) -> None
move_ip(x, y) -> None

Moves the Line by the given offset. The original Line is modified. Always returns None.

This method is equivalent to the following code:

line.ax += x
line.ay += y
line.bx += x
line.by += y

New in pygame-ce 2.5.3.

update()
updates the line's attributes
update((ax, ay), (bx, by)) -> None
update(ax, ay, bx, by) -> None
update(line) -> None

Updates the Line's attributes. The original Line is modified. Always returns None.

This method is equivalent to the following code:

line.ax = ax
line.ay = ay
line.bx = bx
line.by = by

New in pygame-ce 2.5.3.

scale()
scales the line by the given factor from the given origin
scale(factor, origin) -> Line
scale(factor_and_origin) -> Line

Returns a new Line which is scaled by the given factor from the specified origin with 0.0 being the starting point, 0.5 being the center and 1.0 being the end point. The original Line is not modified.

New in pygame-ce 2.5.3.

scale_ip()
scales the line by the given factor from the given origin in place
scale_ip(factor, origin) -> None
scale_ip(factor_and_origin) -> None

Scales the Line by the given factor from the specified origin with 0.0 being the starting point, 0.5 being the center and 1.0 being the end point. The original Line is modified. Always returns None.

New in pygame-ce 2.5.3.

flip_ab()
flips the line a and b points
flip_ab() -> Line

Returns a new Line that has the a and b points flipped. The original Line is not modified.

New in pygame-ce 2.5.3.

flip_ab_ip()
flips the line a and b points, in place
flip_ab_ip() -> None

Flips the Line's a and b points. The original Line is modified. Always returns None.

New in pygame-ce 2.5.3.



Edit on GitHub