pyglet.shapes

2D shapes.

This module provides classes for a variety of simplistic 2D shapes, such as Rectangles, Circles, and Lines. These shapes are made internally from OpenGL primitives, and provide excellent performance when drawn as part of a Batch. Convenience methods are provided for positioning, changing color, opacity, and rotation. The Python in operator can be used to check whether a point is inside a shape. (This is approximated with some shapes, such as Star).

If the shapes in this module don’t suit your needs, you have two options:

Your Goals	Best Approach
Simple shapes like those here	Subclass `ShapeBase`
Complex & optimized shapes	See Shaders and Rendering to learn about the low-level graphics API.

A simple example of drawing shapes:

import pyglet
from pyglet import shapes

window = pyglet.window.Window(960, 540)
batch = pyglet.graphics.Batch()

circle = shapes.Circle(700, 150, 100, color=(50, 225, 30), batch=batch)
square = shapes.Rectangle(200, 200, 200, 200, color=(55, 55, 255), batch=batch)
rectangle = shapes.Rectangle(250, 300, 400, 200, color=(255, 22, 20), batch=batch)
rectangle.opacity = 128
rectangle.rotation = 33
line = shapes.Line(100, 100, 100, 200, width=19, batch=batch)
line2 = shapes.Line(150, 150, 444, 111, width=4, color=(200, 20, 20), batch=batch)
star = shapes.Star(800, 400, 60, 40, num_spikes=20, color=(255, 255, 0), batch=batch)

@window.event
def on_draw():
    window.clear()
    batch.draw()

pyglet.app.run()

Note

Some Shapes, such as Line and Triangle, have multiple coordinates.

These shapes treat their position as their primary coordinate. Changing it or its components (the x or y properties) also moves all secondary coordinates by the same offset from the previous position value. This allows you to move these shapes without distorting them.

New in version 1.5.4.

class ShapeBase

Base class for all shape objects.

A number of default shapes are provided in this module. Curves are approximated using multiple vertices.

If you need shapes or functionality not provided in this module, you can write your own custom subclass of ShapeBase by using the provided shapes as reference.

Methods

draw() → None: Debug method to draw a single shape at its current position. :rtype: None

Warning

Avoid this inefficient method for everyday use!

Regular drawing should add shapes to a Batch and call its draw() method.

delete() → None

Force immediate removal of the shape from video memory.

You should usually call this whenever you delete a shape. Unless you are using manual garbage collection, Python might not call the finalizer as soon as the sprite falls out of scope.

Manual garbage collection is a very advanced technique. See Python’s gc module documentation to learn more.

Return type:: None

Attributes

x

Get/set the X coordinate of the shape’s position.

To update both x and y, use position instead.
Shapes may vary slightly in how they use position

See position to learn more.

y

Get/set the Y coordinate of the shape’s position.

This property has the following pitfalls:

To update both x and y, use position instead.
Shapes may vary slightly in how they use position

See position to learn more.

position

Get/set the (x, y) coordinates of the shape.

Tip

This is more efficient than setting x and y separately!

All shapes default to rotating around their position. However, the way they do so varies.

Shapes with a radius property will use this as their center:

Circle
Ellipse
Arc
Sector
Star

Others default to using it as their lower left corner.

rotation

Get/set the shape’s clockwise rotation in degrees.

All shapes rotate around their anchor_position. For most shapes, this defaults to both:

The shape’s first vertex of the shape
The lower left corner

Shapes with a radius property rotate around the point the radius is measured from. This will be either their center or the center of the circle they’re cut from:

These shapes rotate around their center:

Circle
Ellipse
Star

These shapes rotate around the point of their angles:

Arc
Sector

anchor_x

Get/set the X coordinate of the anchor point.

If you need to set both this and anchor_x, use anchor_position instead.

anchor_y

Get/set the Y coordinate of the anchor point.

If you need to set both this and anchor_x, use anchor_position instead.

anchor_position

Get/set the anchor’s (x, y) offset from position

This defines the point a shape rotates around. By default, it is (0.0, 0.0). However:

Its behavior may vary between shape classes.
On many shapes, you can set the anchor or its components (anchor_x and anchor_y) to custom values.

Since all anchor updates recalculate a shape’s vertices on the CPU, this property is faster than updating anchor_x and anchor_y separately.

color

Get/set the shape’s color.

The color may set to:

An RGBA tuple of integers (red, green, blue, alpha)
An RGB tuple of integers (red, green, blue)

If an RGB color is set, the current alpha will be preserved. Otherwise, the new alpha value will be used for the shape. Each color component must be in the range 0 (dark) to 255 (saturated).

opacity

Get/set the blend opacity of the shape.

Tip

To toggle visibility on/off, visible may be more efficient!

Opacity is implemented as the alpha component of a shape’s color. When part of a group with a default blend mode of (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA), opacities below 255 draw with fractional opacity over the background:

Example Values & Effects
Opacity	Effect
`255` (Default)	Shape is fully opaque
`128`	Shape looks translucent
`0`	Invisible

visible

Get/set whether the shape will be drawn at all.

For absolute showing / hiding, this is

group

Get/set the shape’s Group.

You can migrate a shape from one group to another by setting this property. Note that it can be an expensive (slow) operation.

If batch isn’t None, setting this property will also trigger a batch migration.

batch

Get/set the Batch for this shape.

Warning

Setting this to None currently breaks things!

Known issues include group breaking.

You can migrate a shape from one batch to another by setting this property, but it can be an expensive (slow) operation.

__init__()

__new__(**kwargs)

class Arc

Bases: ShapeBase

angle: Get/set the angle of the arc in radians.

start_angle: Get/set the start angle of the arc in radians.

thickness

__init__( x: float, y: float, radius: float, segments: int | None = None, angle: float = 6.283185307179586, start_angle: float = 0.0, closed: bool = False, thickness: float = 1.0, color=(255, 255, 255, 255), batch: Batch | None = None, group: Group | None = None, )

Create an Arc.

The Arc’s anchor point (x, y) defaults to its center.

Parameters:

x (float) – X coordinate of the circle.
y (float) – Y coordinate of the circle.
radius (float) – The desired radius.
segments (int | None) – You can optionally specify how many distinct line segments the arc should be made from. If not specified it will be automatically calculated using the formula: max(14, int(radius / 1.25)).
angle (float) – The angle of the arc, in radians. Defaults to tau (pi * 2), which is a full circle.
start_angle (float) – The start angle of the arc, in radians. Defaults to 0.
closed (bool) – If True, the ends of the arc will be connected with a line. defaults to False.
thickness (float) – The desired thickness or width of the line used for the arc.
color – The RGB or RGBA color of the arc, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having opacity of 255.
batch (Batch | None) – Optional batch to add the circle to.
group (Group | None) – Optional parent group of the circle.

__new__(**kwargs)

class BezierCurve

Bases: ShapeBase

points: Get/set the control points of the Bézier curve.

t: Get/set the t in 100*t percent of the curve to draw.

thickness: Get/set the line thickness for the Bézier curve.

__init__( *points: tuple[float, float], t: float = 1.0, segments: int = 100, thickness: int = 1.0, color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255), batch: Batch | None = None, group: Group | None = None, )

Create a Bézier curve.

The curve’s anchor point (x, y) defaults to its first control point.

Parameters:

points (tuple[float, float]) – Control points of the curve. Points can be specified as multiple lists or tuples of point pairs. Ex. (0,0), (2,3), (1,9)
t (float) – Draw 100*t percent of the curve. 0.5 means the curve is half drawn and 1.0 means draw the whole curve.
segments (int) – You can optionally specify how many line segments the curve should be made from.
thickness (int) – The desired thickness or width of the line used for the curve.
color (tuple[int, int, int, int] | tuple[int, int, int]) – The RGB or RGBA color of the curve, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
batch (Batch | None) – Optional batch to add the curve to.
group (Group | None) – Optional parent group of the curve.

__new__(**kwargs)

class Circle

Bases: ShapeBase

radius: Gets/set radius of the circle.

__init__( x: float, y: float, radius: float, segments: int | None = None, color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255), batch: Batch | None = None, group: Group | None = None, )

Create a circle.

The circle’s anchor point (x, y) defaults to the center of the circle.

Parameters:

x (float) – X coordinate of the circle.
y (float) – Y coordinate of the circle.
radius (float) – The desired radius.
segments (int | None) – You can optionally specify how many distinct triangles the circle should be made from. If not specified it will be automatically calculated using the formula: max(14, int(radius / 1.25)).
color (tuple[int, int, int, int] | tuple[int, int, int]) – The RGB or RGBA color of the circle, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
batch (Batch | None) – Optional batch to add the circle to.
group (Group | None) – Optional parent group of the circle.

__new__(**kwargs)

class Ellipse

Bases: ShapeBase

a: Get/set the semi-major axes of the ellipse.

b: Get/set the semi-minor axes of the ellipse.

__init__( x: float, y: float, a: float, b: float, segments: int | None = None, color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255), batch: Batch | None = None, group: Group | None = None, )

Create an ellipse.

The ellipse’s anchor point (x, y) defaults to the center of the ellipse.

Parameters:

x (float) – X coordinate of the ellipse.
y (float) – Y coordinate of the ellipse.
a (float) – Semi-major axes of the ellipse.
b (float) – Semi-minor axes of the ellipse.
color (tuple[int, int, int, int] | tuple[int, int, int]) – The RGB or RGBA color of the ellipse, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
batch (Batch | None) – Optional batch to add the circle to.
group (Group | None) – Optional parent group of the circle.

__new__(**kwargs)

class Sector

Bases: ShapeBase

angle: Get/set the angle of the sector in radians.

start_angle: Get/set the start angle of the sector in radians.

radius

Get/set the radius of the sector.

By default, this is in screen pixels. Your drawing / GL settings may alter how this is drawn.

__init__( x: float, y: float, radius: float, segments: int | None = None, angle: float = 6.283185307179586, start_angle: float = 0.0, color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255), batch: Batch | None = None, group: Group | None = None, )

Create a Sector of a circle.

By default, (x, y) is used as: * The sector’s anchor point * The center of the circle the sector is cut from

Parameters:

x (float) – X coordinate of the sector.
y (float) – Y coordinate of the sector.
radius (float) – The desired radius.
segments (int | None) – You can optionally specify how many distinct triangles the sector should be made from. If not specified it will be automatically calculated using the formula: max(14, int(radius / 1.25)).
angle (float) – The angle of the sector, in radians. Defaults to tau (pi * 2), which is a full circle.
start_angle (float) – The start angle of the sector, in radians. Defaults to 0.
color (tuple[int, int, int, int] | tuple[int, int, int]) – The RGB or RGBA color of the circle, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
batch (Batch | None) – Optional batch to add the sector to.
group (Group | None) – Optional parent group of the sector.

__new__(**kwargs)

class Line

Bases: ShapeBase

x2: Get/set the 2nd X coordinate of the line.

y2: Get/set the 2nd Y coordinate of the line.

__init__( x: float, y: float, x2: float, y2: float, width: float = 1.0, color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255), batch: Batch | None = None, group: Group | None = None, )

Create a line.

The line’s anchor point defaults to the center of the line’s width on the X axis, and the Y axis.

Parameters:

x (float) – The first X coordinate of the line.
y (float) – The first Y coordinate of the line.
x2 (float) – The second X coordinate of the line.
y2 (float) – The second Y coordinate of the line.
width (float) – The desired width of the line.
color (tuple[int, int, int, int] | tuple[int, int, int]) – The RGB or RGBA color of the line, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
batch (Batch | None) – Optional batch to add the line to.
group (Group | None) – Optional parent group of the line.

__new__(**kwargs)

class Rectangle

Bases: ShapeBase

width

Get/set width of the rectangle.

The new left and right of the rectangle will be set relative to its anchor_x value.

height

Get/set the height of the rectangle.

The bottom and top of the rectangle will be positioned relative to its anchor_y value.

__init__( x: float, y: float, width: float, height: float, color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255), batch: Batch | None = None, group: Group | None = None, )

Create a rectangle or square.

The rectangle’s anchor point defaults to the (x, y) coordinates, which are at the bottom left.

Parameters:

x (float) – The X coordinate of the rectangle.
y (float) – The Y coordinate of the rectangle.
width (float) – The width of the rectangle.
height (float) – The height of the rectangle.
color (tuple[int, int, int, int] | tuple[int, int, int]) – The RGB or RGBA color of the circle, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
batch (Batch | None) – Optional batch to add the rectangle to.
group (Group | None) – Optional parent group of the rectangle.

__new__(**kwargs)

class Box

Bases: ShapeBase

width

Get/set the width of the box.

Setting the width will position the left and right sides relative to the box’s anchor_x value.

height

Get/set the height of the Box.

Setting the height will set the bottom and top relative to the box’s anchor_y value.

__init__( x: float, y: float, width: float, height: float, thickness: float = 1.0, color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255), batch: Batch | None = None, group: Group | None = None, )

Create an unfilled rectangular shape, with optional thickness.

The box’s anchor point defaults to the (x, y) coordinates, which are placed at the bottom left. Changing the thickness of the box will extend the walls inward; the outward dimesions will not be affected.

Parameters:

x (float) – The X coordinate of the box.
y (float) – The Y coordinate of the box.
width (float) – The width of the box.
height (float) – The height of the box.
thickness (float) – The thickness of the lines that make up the box.
color (tuple[int, int, int, int] | tuple[int, int, int]) – The RGB or RGBA color of the box, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
batch (Batch | None) – Optional batch to add the box to.
group (Group | None) – Optional parent group of the box.

__new__(**kwargs)

class BorderedRectangle

Bases: ShapeBase

width

Get/set width of the bordered rectangle.

The new left and right of the rectangle will be set relative to its anchor_x value.

height

Get/set the height of the bordered rectangle.

The bottom and top of the rectangle will be positioned relative to its anchor_y value.

border_color

Get/set the bordered rectangle’s border color.

To set the color of the interior fill, see color.

You can set the border color to either of the following:

An RGBA tuple of integers (red, green, blue, alpha)
An RGB tuple of integers (red, green, blue)

Setting the alpha on this property will change the alpha of the entire shape, including both the fill and the border.

Each color component must be in the range 0 (dark) to 255 (saturated).

__init__( x: float, y: float, width: float, height: float, border: float = 1.0, color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255), border_color: tuple[int, int, int, int] | tuple[int, int, int] = (100, 100, 100), batch: Batch | None = None, group: Group | None = None, )

Create a bordered rectangle.

The rectangle’s anchor point defaults to the (x, y) coordinates, which are at the bottom left.

Parameters:

x (float) – The X coordinate of the rectangle.
y (float) – The Y coordinate of the rectangle.
width (float) – The width of the rectangle.
height (float) – The height of the rectangle.
border (float) – The thickness of the border.
color (tuple[int, int, int, int] | tuple[int, int, int]) – The RGB or RGBA fill color of the rectangle, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
border_color (tuple[int, int, int, int] | tuple[int, int, int]) –
The RGB or RGBA fill color of the border, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.

The alpha values must match if you pass RGBA values to both this argument and border_color. If they do not, a ValueError will be raised informing you of the ambiguity.
batch (Batch | None) – Optional batch to add the rectangle to.
group (Group | None) – Optional parent group of the rectangle.

__new__(**kwargs)

class Triangle

Bases: ShapeBase

x2: Get/set the X coordinate of the triangle’s 2nd vertex.

y2: Get/set the Y coordinate of the triangle’s 2nd vertex.

x3: Get/set the X coordinate of the triangle’s 3rd vertex.

y3: Get/set the Y value of the triangle’s 3rd vertex.

__init__( x: float, y: float, x2: float, y2: float, x3: float, y3: float, color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255), batch: Batch | None = None, group: Group | None = None, )

Create a triangle.

The triangle’s anchor point defaults to the first vertex point.

Parameters:

x (float) – The first X coordinate of the triangle.
y (float) – The first Y coordinate of the triangle.
x2 (float) – The second X coordinate of the triangle.
y2 (float) – The second Y coordinate of the triangle.
x3 (float) – The third X coordinate of the triangle.
y3 (float) – The third Y coordinate of the triangle.
color (tuple[int, int, int, int] | tuple[int, int, int]) – The RGB or RGBA color of the triangle, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
batch (Batch | None) – Optional batch to add the triangle to.
group (Group | None) – Optional parent group of the triangle.

__new__(**kwargs)

class Star

Bases: ShapeBase

outer_radius: Get/set outer radius of the star.

inner_radius: Get/set the inner radius of the star.

num_spikes: Number of spikes of the star.

__init__( x: float, y: float, outer_radius: float, inner_radius: float, num_spikes: int, rotation: float = 0.0, color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255), batch: Batch | None = None, group: Group = None, ) → None

Create a star.

The star’s anchor point (x, y) defaults to the on-screen center of the star.

Parameters:

x (float) – The X coordinate of the star.
y (float) – The Y coordinate of the star.
outer_radius (float) – The desired outer radius of the star.
inner_radius (float) – The desired inner radius of the star.
num_spikes (int) – The desired number of spikes of the star.
rotation (float) – The rotation of the star in degrees. A rotation of 0 degrees will result in one spike lining up with the X axis in positive direction.
color (tuple[int, int, int, int] | tuple[int, int, int]) – The RGB or RGBA color of the star, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
batch (Batch | None) – Optional batch to add the star to.
group (Group) – Optional parent group of the star.

__new__(**kwargs)

class Polygon

Bases: ShapeBase

__init__( *coordinates: tuple[float, float] | Sequence[float], color: tuple[int, int, int, int] | tuple[int, int, int] = (255, 255, 255, 255), batch: Batch | None = None, group: Group | None = None, )

Create a convex polygon.

The polygon’s anchor point defaults to the first vertex point.

Parameters:

coordinates (tuple[float, float] | Sequence[float]) – The coordinates for each point in the polygon. Each one must be able to unpack to a pair of float-like X and Y values.
color (tuple[int, int, int, int] | tuple[int, int, int]) – The RGB or RGBA color of the polygon, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
batch (Batch | None) – Optional batch to add the polygon to.
group (Group | None) – Optional parent group of the polygon.

__new__(**kwargs)

class MultiLine

Bases: ShapeBase

thickness: Get/set the line thickness of the multi-line.

__init__( *coordinates: tuple[float, float] | Sequence[float], closed: bool = False, thickness: float = 1.0, color: tuple[int, int, int, int] = (255, 255, 255, 255), batch: Batch | None = None, group: Group | None = None, )

Create multiple connected lines from a series of coordinates.

The shape’s anchor point defaults to the first vertex point.

Parameters:

coordinates (tuple[float, float] | Sequence[float]) – The coordinates for each point in the shape. Each must unpack like a tuple consisting of an X and Y float-like value.
closed (bool) – Set this to True to add a line connecting the first and last points. The default is False
thickness (float) – The desired thickness or width used for the line segments.
color (tuple[int, int, int, int]) – The RGB or RGBA color of the shape, specified as a tuple of 3 or 4 ints in the range of 0-255. RGB colors will be treated as having an opacity of 255.
batch (Batch | None) – Optional batch to add the shape to.
group (Group | None) – Optional parent group of the shape.

__new__(**kwargs)