##### pygame-ce documentation

Pygame-ce Home || Help Contents || Reference Index

Most useful stuff: Color | display | draw | event | font | image | key | locals | mixer | mouse | Rect | Surface | time | music | pygame

Advanced stuff: cursors | joystick | mask | sprite | transform | BufferProxy | freetype | gfxdraw | midi | PixelArray | pixelcopy | sndarray | surfarray | math

Other: camera | controller | examples | scrap | system | tests | touch | typing | version | Window

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

  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

    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

    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.

    project()

      > projects the line onto the given line
      > project(point: tuple[float, float], clamp=False) -> tuple[float, float]

      > This method takes in a point and one boolean keyword argument clamp. It outputs an orthogonally projected point onto the line. If clamp is True it makes sure that the outputted point will be on the line segment (which might not be orthogonal), and if it is False (the default) then any point on the infinitely extended line may be outputted. This method can be used to find the closest point on a line to the given point. The output is the unique point on the line or line segment that is the smallest distance away from the given point.

      > Example of how it projects the point onto the line. The red point is the point we want to project and the blue point is what you would get as a result.

      > Example of what the clamp argument changes. If it is True, the point is bounded between the line segment ends.

      > WARNING: If the line has no length (i.e. the start and end points are the same) then the returned point of this function will be the same point as both ends of the line.

      > New in pygame-ce 2.5.6.

Edit on GitHub