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, thickness=19, batch=batch)
line2 = shapes.Line(150, 150, 444, 111, thickness=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.

Added 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

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.

classmethod __new__(*args, **kwargs)

class Arc

Bases: ShapeBase

angle: The angle of the arc, in degrees.

start_angle: The start angle of the arc, in degrees.

thickness: Get/set the thickness of the Arc.

classmethod __new__(*args, **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.

classmethod __new__(*args, **kwargs)

class Circle

Bases: ShapeBase

radius: Gets/set radius of the circle.

classmethod __new__(*args, **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.

classmethod __new__(*args, **kwargs)

class Sector

Bases: ShapeBase

angle: The angle of the sector, in degrees.

start_angle: The start angle of the sector, in degrees.

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.

classmethod __new__(*args, **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.

classmethod __new__(*args, **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.

classmethod __new__(*args, **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.

classmethod __new__(*args, **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).

classmethod __new__(*args, **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.

classmethod __new__(*args, **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.

classmethod __new__(*args, **kwargs)

class Polygon

Bases: ShapeBase

classmethod __new__(*args, **kwargs)

class MultiLine

Bases: ShapeBase

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

classmethod __new__(*args, **kwargs)