pygame.geometry — pygame-ce v2.5.3 documentation

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)

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.

top¶: top coordinate of the circle

top -> (float, float)

It's 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)

It's 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)

It's 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)

It's 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.copy	—	copies the line

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)

It's 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)

It's 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.

Line Methods

copy()¶: copies the line

copy() -> Line

Returns a copy of this Line.

New in pygame-ce 2.5.2.

Edit on GitHub

pygame-ce documentation