Objects and shapes

Draw and manipulate pyDraw shapes, images, lines, text, pens, and compound objects.

Objects in the PyDraw library

(Author: Noah Coetsee)

class pydraw.objects.CustomPolygon(screen: Screen, vertices: list, color: Color = black, border: Color = None, fill: bool = True, rotation: float = 0, visible: bool = True)

Bases: CustomRenderable

An Irregular Polygon that is passed a list of vertices that can be rotated and translated!

clone() → CustomPolygon

Clone this CustomPolygon!

Returns:: a CustomPolygon

height(height: float = None) → float

Get the height of the Polygon

Parameters:: height – The new height to scale to in px.
Returns:: the height of the object

move(dx: float, dy: float) → None

move(location: Location) → None

move(dxy: Tuple[float, float]) → None

move(*, dx: float = ..., dy: float = ...) → None

Can take either a tuple, Location, or two numbers (dx, dy)

Returns:: None

moveto(x: float, y: float) → None

moveto(location: Location) → None

moveto(xy: Tuple[float, float]) → None

moveto(*, x: float = ..., y: float = ...) → None

Move to a new location takes a Location, tuple, or two numbers (x, y)

Returns:: None

rotate(angle_diff: float = 0) → None

Rotate the angle of the object by a difference, in degrees

Parameters:: angle_diff – the angle difference to rotate by
Returns:: None

rotation(angle: float = None) → float

Gets or sets the rotation of the CustomPolygon.

Parameters:: angle – the angle to rotate the polygon to
Returns:: the angle that was set

update(): To be overriden.

vertices() → list

Returns the list of vertices for the Renderable. (The vertices will be returned clockwise, starting from the top-leftmost point)

Returns:: a list of Locations representing the vertices

width(width: float = None) → float

Get the width of the CustomPolygon

Parameters:: width – the new width to scale to in pixels, if any
Returns:: the width of the object

class pydraw.objects.CustomRenderable(screen: Screen, x: float = 0, y: float = 0, width: float = 10, height: float = 10, color: Color = black, border: Color, fill: bool = True, rotation: float = 0, visible: bool = True, location: Location = None)

Bases: Renderable

A wrapper class to distintify classes that extend Renderable but have some custom functionality.

class pydraw.objects.Image

Bases: Renderable

Image class. Supports basic formats: PNG, GIF, JPG, PPM, images.

NOTE: This class supports the basic displaying of images, but also supports much more, such as image modification (width, height, color, etc) if you have PIL (Pillow) installed! You can install PIL/Pillow by running: pip install pillow in a terminal!

border(color: Color = None) → Color

Add or get the border of the image

Parameters:: color – the color to set the border too, set to Color.NONE to remove border
Returns:: The Color of the border

center(x: float, y: float, *, centroid: bool = ...) → Location

center(location: Location, *, centroid: bool = ...) → Location

center(*, move_to: Location = ..., x: float = ..., y: float = ..., centroid: bool = ...) → Location

Returns the location of the center

Parameters:

move_to – if defined, Move the center to a new Location (Easily center objects!)
x – if defined, move the center x-coordinate to the specified value
y – if defined, move the center y-coordinate to the specified value

Returns:

Location object representing center of Image

clone() → Image

Clone this renderable!

Returns:: a Renderable

color(color: Color = None, alpha: int = 123) → Color

Retrieves or applies a color-mask to the image

Parameters:

color – the color to mask to, if any
alpha – The alpha level of the mask, defaults to 123 (half of 255)

Returns:

the mask-color of the object

fill(fill: bool = None) → bool: Unsupported: This doesn’t make sense for images.

flip(axis: str = 'y') → None

Flip the image across an axis.

Flipping across the x-axis reverses the image vertically; flipping across the y-axis reverses it horizontally. Calling this method again with the same axis restores the original orientation.

Requires PIL/Pillow.

Parameters:: axis – the axis to flip across, either 'x' or 'y'
Returns:: None

frame(frame: int = None) → int

Set the current frame.

Parameters:: frame – the frame-index to set to
Returns:: the current frame

frames() → int

Returns how many frames there are, returns -1 if not animated, 0 if corrupted file.

Returns:

height(height: float = None) → float

Get or set the height of the image

Parameters:: height – the height to set to, if any
Returns:: the height

load() → None

Load animated GIF (reads frames)

Returns:: None

next() → None

Changes frame to the next frame (Can only be used with animated GIFs)

Returns:

rotate(angle_diff: float) → None

Rotate the angle of the image by a difference, in degrees

Parameters:: angle_diff – the angle difference to rotate by
Returns:: None

rotation(angle: float = None) → float

Get or set the rotation of the image.

Parameters:: angle – the angle to set the rotation to in degrees, if any
Returns:: the angle of the image’s rotation in degrees

smooth(smooth: bool = None) → bool

Get or set the resampling quality used when resizing/rotating the image.

True (default) uses smooth filters (LANCZOS/BILINEAR); False uses NEAREST, which is dramatically faster (~13x on rotation) and crisp for pixel-art sprites - ideal in a game loop.

Parameters:: smooth – True for smooth, False for fast/nearest, if setting
Returns:: whether smooth resampling is enabled

transform(transform: tuple = None) → tuple

Get or set the transform of the Image. Transforms represent the width, height, and rotation of the Image.

You can retrieve a Transform from an Image with this method and set the transform the same way.

Parameters:: transform – the transform to set to, if any.
Returns:: the transform

update(updated: bool = False): To be overriden.

vertices() → list

Returns the list of vertices for the Renderable. (The vertices will be returned clockwise, starting from the top-leftmost point)

Returns:: a list of Locations representing the vertices

width(width: float = None) → float

Get or set the width of the image (REQUIRES: PIL or Pillow)

Parameters:: width – the width to set to, if any
Returns:: None

class pydraw.objects.Line(screen: Screen, *args, color: Color = black, thickness: int = 1, dashes=None, visible: bool = True)

Bases: Object

clone()

Clone a new line!

Returns:: A clone of this line

color(color: Color = None) → Color

Get or set the color of the line

Parameters:: color – the color to set to, if any
Returns:: the color of the line

dashes(dashes: int | tuple = None) → int | tuple

Retrieve or enable/disable the dashes for the line

On systems which support only a limited set of dash patterns, the dash pattern will be displayed as the closest dash pattern that is available. For example, on Windows only a few dash patterns are available, most of which do not allow for special dash-spacing (if passing in a tuple).

Parameters:: dashes – the visibility to set to, if any
Returns:: the toggle-state of dashes

intersects(obj) → bool

Check if a line intersects with another line or Renderable

Parameters:: obj – Line, Renderable, or List/Tuple
Returns:: Whether the line intersects with the object

length() → float

Get the length of the line

Returns:: the length of the line

location() → tuple

Returns the locations of both the endpoints

Returns:: the locations of both the endpoints

lookat(location: Location | Tuple[float, float], point: int = ...) → None

lookat(x: float, y: float, point: int = ...) → None

Make the line look at the given point by moving the second point.

Returns:: None

move(dx: float, dy: float) → None

move(location: Location) → None

move(dxy: Tuple[float, float]) → None

move(*, dx: float = ..., dy: float = ...) → None

Move both endpoints by the same dx and dy

Can take either a tuple, Location, or two numbers (dx, dy)

Parameters:

dx – the distance x to move
dy – the distance y to move
point – affect only one of the endpoints options: (1, 2), default=0 (Must be 1 or 2)

Returns:

None

moveto(x: float, y: float) → None

moveto(location: Location) → None

moveto(xy: Tuple[float, float]) → None

moveto(*, x: float = ..., y: float = ...) → None

Move both of the endpoints to new locations.

Parameters:: args – Either two locations, tuples, or four numbers (x1, y1, x2, y2).
Returns:: None

pos1() → Location

pos1(__location: Location | Tuple[float, float]) → Location

pos1(__x: float, __y: float) → Location

Get or set the position of the first endpoint.

Parameters:: args – Either a location or two numbers (x, y) may be passed here.
Returns:: the position of the first endpoint.

pos2() → Location

pos2(__location: Location | Tuple[float, float]) → Location

pos2(__x: float, __y: float) → Location

Get or set the position of the second endpoint.

Parameters:: args – Either a location or two numbers (x, y) may be passed here.
Returns:: the position of the second endpoint.

rotate(angle_diff: float, point: int = 1) → float

Rotate the line around one of its vertices (1 by default)

Parameters:

angle_diff – the angle to rotate by
point – the point to serve as the origin.

Returns:

the new angle

rotation(angle: float = None)

Get or set the rotation of the line (works via pos2()).

Parameters:: angle – the angle in degrees to rotate by, if any
Returns:: the angle of the line

thickness(thickness: int = None) → int

Get or set the thickness of the line

Parameters:: thickness – the thickness to set to, if any
Returns:: the thickness of the line

transform(transform: tuple = None)

Copy the line’s length and angle!

Parameters:: transform
Returns:

update(): To be overriden.

visible(visible: bool = None) → bool

Get or set the visibility of the line

Parameters:: visible – the visibility to set to, if any
Returns:: the visibility of the line

class pydraw.objects.Object(screen: Screen, x: float = 0, y: float = 0, location: Location = None)

Bases: object

A base object containing a location and screen. This ensures coordinates are done with the root in the top left corner, and not at the center.

back() → None

Brings the object to the back of the Screen (Imagine moving backward on the Z axis)

Returns:: None

front() → None

Brings the object to the front of the Screen (Imagine moving forward on the Z axis)

Returns:: None

location() → Location

move(dx: float, dy: float) → None

move(location: Location) → None

move(dxy: Tuple[float, float]) → None

move(*, dx: float = ..., dy: float = ...) → None

Can take either a tuple, Location, or two numbers (dx, dy)

Returns:: None

moveto(x: float, y: float) → None

moveto(location: Location) → None

moveto(xy: Tuple[float, float]) → None

moveto(*, x: float = ..., y: float = ...) → None

Move to a new location takes a Location, tuple, or two numbers (x, y)

Returns:: None

pen(color: Color = black, width: int = 2, top: bool = False) → Pen

pen_clear() → None

pen_stop() → bool

pen_top(top: bool = None) → bool

pen_width(width: int = None) → int

remove() → None

update() → None: To be overriden.

x(x: float = None) → float

y(y: float = None) → float

class pydraw.objects.Oval

Bases: Renderable

height(height: float = None) → float

Get or set the height of the object.

Parameters:: height – the width to set to in pixels, if any
Returns:: the height of the object

slices() → list

Gets the slices of the Oval based on wedges. Note that this generates slices that are not tied to the oval, these are simply slices of the oval based on its wedges. You can use them how you see fit.

Returns:: a tuple (immutable list) of CustomPolygons

wedges(wedges: int = None) → int

width(width: float = None) → float

Get or set the width of the object.

Parameters:: width – the width to set to in pixels, if any
Returns:: the width of the object

class pydraw.objects.Pen(screen: Screen, x: float, y: float, color: Color = black, width: int = 2, top: bool = False)

Bases: object

clear(): Clear the line from the screen and all history (coordinates).

color(color: Color = None) → Color

coordinates(*coords: Location | Tuple[float, float]) → List[Location]

drawing(drawing: bool = None) → bool

location() → Location

move(dx: float, dy: float) → Location

move(location: Location) → Location

move(dxy: Tuple[float, float]) → Location

move(*, dx: float = ..., dy: float = ...) → Location

Adds a new coordinate to the pen line with a passed difference from the previous coordinate. Requires coordinates to be len > 0.

Can take two numbers (dx, dy), a tuple, or a Location

Parameters:

dx – the dx to move by
dy – the dy to move by

Returns:

the location (after change)

moveto(x: float, y: float) → Location

moveto(location: Location) → Location

moveto(xy: Tuple[float, float]) → Location

moveto(*, x: float = ..., y: float = ...) → Location

Adds a new coordinate to the pen line.

Can take two coordinates (x, y), a tuple, or a Location

Parameters:

x – the x to move to
y – the y to move to

Returns:

the location (after change)

start()

stop()

toggle() → bool

top(top: bool = None) → bool

width(width: int = None) → int

class pydraw.objects.Polygon

Bases: Renderable

clone() → Polygon

Clone this Polygon!

:return a Polygon

update(): To be overriden.

class pydraw.objects.Rectangle: Bases: Renderable

class pydraw.objects.Renderable(screen: Screen, x: float = 0, y: float = 0, width: float = 10, height: float = 10, color: Color = black, border: Color, fill: bool = True, rotation: float = 0, visible: bool = True, location: Location = None)

Bases: Object

Test class for new itemconfigure-based pyDraw objects.

Update method is now only used for changes in position (and possibly changes that cannot be configured and require the item to be remade)

angleto(obj) → float

Retrieve the angle between this object and another (based on 0 degrees at 12 o’clock)

Parameters:: obj – the Object/Location to get the angle to.
Returns:: the angle in degrees as a float

backward(distance: float) → None

Move the Renderable backward by distance at its current heading (rotation/angle)

Parameters:: distance – the distance to move backward (hypotenuse)
Returns:: None

border(color: Color = None, width: float = None, fill: bool = None) → Color

Add or get the border of the object

Parameters:

color – the color to set the border too, set to Color.NONE to remove border
width – the width of the border
fill – whether to fill the polygon.

Returns:

The Color of the border

border_width(width: float = None) → float

Gets or sets the border width

Parameters:: width – the border width to set to
Returns:: the border width

bounds() -> (<class 'pydraw.location.Location'>, <class 'float'>, <class 'float'>)

Get the location and dimensions of a bounding box that contains the entire shape

Returns:: a tuple containing the Location, width, and height.

center(x: float, y: float, *, centroid: bool = ...) → Location

center(location: Location, *, centroid: bool = ...) → Location

center(*, move_to: Location = ..., x: float = ..., y: float = ..., centroid: bool = ...) → Location

Returns the location of the center

Parameters:

move_to – if defined, Move the center to a new Location (Easily center objects!)
x – if defined, move the center x-coordinate to the specified value
y – if defined, move the center y-coordinate to the specified value

Returns:

Location object representing center of Renderable

clone()

Clone this renderable!

Returns:: a Renderable

color(color: Color = None) → Color

Get or set the color of the object

Parameters:: color – the color to set to, if any
Returns:: the color of the object

contains(__x: float, __y: float) → bool

contains(__location: Location) → bool

contains(__xy: Tuple[float, float]) → bool

Returns whether a Location is contained within the object.

Parameters:: args – You may pass in either two numbers, a Location, or a tuple containing and x and y point.
Returns:: a boolean value representing whether the point is within the vertices of the object.

distance(obj) → float

Returns the distance between two objs or locations in pixels (center to center)

Parameters:: obj – the Renderable/location to check distance between
Returns:: the distance between this obj and the passed Renderable/Location.

fill(fill: bool = None) → bool

Returns or sets the current fill boolean

Parameters:: fill – a new fill value, whether to fill the polygon
Returns:: the fill value

forward(distance: float) → None

Move the Renderable forward by distance at its current heading (rotation/angle)

Parameters:: distance – the distance to move forward (hypotenuse)
Returns:: None

height(height: float = None) → float

Get or set the height of the Renderable.

Parameters:: height – the height to set to in pixels, if any
Returns:: the height of the object

location() → Location

lookat(obj) → None

Look at another object (Objects or Locations)

Parameters:: obj – the Object/Location to look at.
Returns:: None

move(dx: float, dy: float) → None

move(location: Location) → None

move(dxy: Tuple[float, float]) → None

move(*, dx: float = ..., dy: float = ...) → None

Can take either a tuple, Location, or two numbers (dx, dy)

Returns:: None

moveto(x: float, y: float) → None

moveto(location: Location) → None

moveto(xy: Tuple[float, float]) → None

moveto(*, x: float = ..., y: float = ...) → None

Move to a new location takes a Location, tuple, or two numbers (x, y)

Returns:: None

overlaps(other: Renderable) → bool

Returns if this object is overlapping with the passed object.

Parameters:: other – another Renderable instance.
Returns:: true if they are overlapping, false if not.

rotate(angle_diff: float = 0) → None

Rotate the angle of the object by a difference, in degrees

Parameters:: angle_diff – the angle difference to rotate by
Returns:: None

rotation(angle: float = None) → float

Get or set the rotation of the object.

Parameters:: angle – the angle to set the rotation to in degrees, if any
Returns:: the angle of the object’s rotation in degrees

transform(transform: tuple = None) → tuple

Get or set the transform of the Renderable. Transforms represent the width, height, and rotation of Renderables.

You can retrieve a Transform from a Renderable with this method and set the transform the same way.

Parameters:: transform – the transform to set to, if any.
Returns:: the transform

update(): To be overriden.

vertices() → list

Returns the list of vertices for the Renderable. (The vertices will be returned clockwise, starting from the top-leftmost point)

Returns:: a list of Locations representing the vertices

visible(visible: bool = None) → bool

Get or set the visibility of the renderable.

Parameters:: visible – the new visibility value, if any
Returns:: the visibility value

width(width: float = None) → float

Get or set the width of the Renderable.

Parameters:: width – the width to set to in pixels, if any
Returns:: the width of the object

x(x: float = None) → float

y(y: float = None) → float

class pydraw.objects.RoundedRectangle

Bases: CustomRenderable

A rectangle with rounded corners.

clone() → RoundedRectangle

Clone this renderable!

Returns:: a Renderable

radius(radius: float = None) → float

Set the corner radius of the rounded shape in pixels.

Parameters:: radius – the radius to set
Returns:: the radius

update(): To be overriden.

class pydraw.objects.Text

Bases: CustomRenderable

align(align: str = None) → str

Get or set the alignment of the text, if a new value is passed it must be ‘left’, ‘center’, or ‘right’.

Parameters:: align – the alignment to set to, if any
Returns:: the alignment of the text

bold(bold: bool = None) → bool

Get or set the bold status of the text

Parameters:: bold – the bold status to set to, if any
Returns:: the bold status of the text

center(x: float, y: float, *, centroid: bool = ...) → Location

center(location: Location, *, centroid: bool = ...) → Location

center(*, move_to: Location = ..., x: float = ..., y: float = ..., centroid: bool = ...) → Location

Returns the location of the center

Parameters:

move_to – if defined, Move the center to a new Location (Easily center objects!)
x – if defined, move the center x-coordinate to the specified value
y – if defined, move the center y-coordinate to the specified value

Returns:

Location object representing center of Renderable

clone()

Clone this text!

Returns:: A cloned text object!

color(color: Color = None) → Color

Get or set the color of the text

Parameters:: color – the color to set to, if any
Returns:: the color of the text

font(font: str = None) → str

Get or set the font of the text

Parameters:: font – the font to set to, if any
Returns:: the font of the text

height() → float

Get the height of the text, (cannot be modified, although technically the font-size is the text’s height)

Returns:: the height of the text.

italic(italic: bool = None) → bool

Get or set the italic status of the text

Parameters:: italic – the italic status to set to, if any
Returns:: the italic status of the text

lookat(obj)

Look at another object (Objects or Locations)

Parameters:: obj – the Object/Location to look at.
Returns:: None

move(dx: float, dy: float) → None

move(location: Location) → None

move(dxy: Tuple[float, float]) → None

move(*, dx: float = ..., dy: float = ...) → None

Can take either a tuple, Location, or two numbers (dx, dy)

Returns:: None

moveto(x: float, y: float) → None

moveto(location: Location) → None

moveto(xy: Tuple[float, float]) → None

moveto(*, x: float = ..., y: float = ...) → None

Move to a new location takes a Location, tuple, or two numbers (x, y)

Returns:: None

rotate(angle_diff: float = 0) → None

Rotate the angle of the text by a difference, in degrees

Parameters:: angle_diff – the angle difference to rotate by
Returns:: Nonea

rotation(rotation: float = None) → float

Get or set the rotation of the text

Parameters:: rotation – the strikethrough to set to, if any
Returns:: the rotation of the text

size(size: int = None) → int

Get or set the size of the text

Parameters:: size – the size to set to, if any
Returns:: the size of the text

strikethrough(strikethrough: bool = None) → bool

Get or set the strikethrough status of the text

Parameters:: strikethrough – the strikethrough status to set to, if any
Returns:: the strikethrough status of the text

text(text: str = None) → str

Get or set the text. Use ‘n’ to separate lines.

Parameters:: text – text to set to (str), if any
Returns:: the text

transform(transform: tuple = None) → tuple

Retrieve the transform of the text

Parameters:: transform – Unsupported.
Returns:: a tuple with representing: (width, height, angle)

underline(underline: bool = None) → bool

Get or set the underline status of the text

Parameters:: underline – the underline status to set to, if any
Returns:: the underline status of the text

update() → None: To be overriden.

vertices() → list

Get the vertices of a Rectangle superposed in the same transform of the Text

Returns:: a list of Locations

visible(visible: bool = None) → bool

Get or set the visibility of the text

Parameters:: visible – the visibility to set to, if any
Returns:: the visibility of the text

width() → float

Get the width of the text (cannot be modified)

:return the width of the text

class pydraw.objects.Triangle: Bases: Renderable

Compound objects

class pydraw.compound.CompoundObject(*args: Object, **kwargs: Object)

Bases: Object

A compound group of objects that can be moved or modified together.

add(obj: Object, name=None) → None

Add another Object to the CompoundObject

Parameters:: obj – the Object to add
Returns:: None

back() → None

Brings the compound object to the back of the Screen (Imagine moving backward on the Z axis)

Returns:: None

center(centroid: bool = True) → Location

Calculate the center point of the CompoundObject

Centroid:: whether to use the centroid or the center of the bounding box
Returns:: Location of the center

color(color: Color): Change the color of all the objects in the compound object.

contains(__x: float, __y: float) → bool

contains(__location: Location) → bool

contains(__xy: Tuple[float, float]) → bool

Check if the CompoundObject contains a certain Location

Parameters:: args – the Location to check
Returns:: True if the CompoundObject contains the Location, False otherwise

front() → None

Brings the compound object to the front of the Screen (Imagine moving forward on the Z axis)

Returns:: None

height(height: float = None) → float

Get the height of the compound object

Parameters:: height – a new height, if provided
Returns:: a float

move(dx: float, dy: float) → None

move(location: Location) → None

move(dxy: Tuple[float, float]) → None

move(*, dx: float = ..., dy: float = ...) → None

Move the compound shape by a certain distance (dx, dy)

Returns:: None

moveto(x: float, y: float) → None

moveto(location: Location) → None

moveto(xy: Tuple[float, float]) → None

moveto(*, x: float = ..., y: float = ...) → None

Move the compound shape to a new location (x, y)

Returns:: None

object(name) → Object

Retrieve a specific object

Parameters:: name – the name of the object (can be a str, or another type of object)
Returns:: Object

objects() → tuple

Retrieve a tuple of all objects in the compound shape.

Returns:: a tuple

overlaps(other: Renderable) → bool

Returns if this compound object is overlapping with the passed object.

Parameters:: other – another Renderable instance.
Returns:: true if they are overlapping, false if not.

remove(obj: Object = None, name=None) → Object

Remove an object from the Compound Object

Parameters:

obj – the object to remove
name – the name the object is registered under

Returns:

the Object that got removed (or None)

rotate(angle_diff: float, pivot: Location = None) → None

Rotate the angle of the compound object by a difference, around a pivot point, in degrees

Parameters:

angle_diff – the angle difference to rotate by
pivot – the pivot point to rotate around

Returns:

None

rotation(angle: float = None) → float

Get the rotation of the compound object

Parameters:: angle – a new rotation, if provided
Returns:: a float

update(): Updates values of the compound object.

width(width: float = None) → float

Get the width of the compound object

Parameters:: width – a new width, if provided
Returns:: a float

x(x: float = None) → float

Get the x coordinate of the compound system.

Parameters:: x – a new x, if provided
Returns:: a float

y(y: float = None) → float

Get the y coordinate of the compound system.

Parameters:: y – a new y, if provided
Returns:: a float