Image Quick Reference

01

Creating Images

Create an Image from an asset path. Its x and y coordinates anchor the unrotated top-left corner. Omit both dimensions for the asset's natural size, or provide one to resize proportionally.

Image(screen, source, x=0, y=0, width=None, height=None, color=None, border=Color.NONE, rotation=0, visible=True)

Create an Image from an asset path and optional coordinates.

Image(screen, source, location, width=None, height=None, color=None, border=Color.NONE, rotation=0, visible=True)

Create the same Image from a Location.

Example

logo = Image(screen, "images/logo.png", 30, 30)

Proportional width

banner = Image(
    screen, "images/banner.png",
    40, 50, width=320
)

Explicit size

player = Image(
    screen, "images/player.png",
    Location(120, 90), 64, 48
)

02

Position & size

Move an Image like any other Renderable. The constructor preserves the source aspect ratio when only width or height is supplied. After creation, the dimensions can be changed independently.

image.x(value=None) · image.y(value=None) · image.location()

Read the top-left anchor, or replace either coordinate.

image.move(dx, dy) · image.moveto(x, y)

Move by an offset or move to an absolute position.

image.center() · image.center(x, y)

Read the center or move it to a new position.

image.width(value=None) · image.height(value=None)

Read or change the displayed dimensions.

image.transform() · image.transform((width, height, rotation))

Read or replace size and rotation as one tuple.

Example

player.center(screen.center())
player.move(8, 0)
player.width(96)
player.height(72)

Copy a transform

saved = player.transform()
shadow.transform(saved)

03

Rotation, flips & smoothing

Rotate around the center, mirror the bitmap, or choose between smooth resampling and crisp nearest-neighbor pixels.

image.rotation(angle=None) · image.rotate(angle_difference)

Read or set absolute rotation, or turn by a relative number of degrees.

image.flip(axis="y")

Toggle a flip across the x- or y-axis; call it again with the same axis to restore the original orientation.

image.smooth(value=None)

Read or change resampling: True for smooth filtering, False for nearest-neighbor pixels.

Example

ship.rotate(4)
ship.flip("y")

Pixel art

sprite.smooth(False)
sprite.width(128)
sprite.height(128)

04

Tint, border & visibility

Apply a luminance-preserving color tint, add a simple border, or change visibility and drawing order without reloading the asset.

image.color(value=None, alpha=123)

Read the current tint Color or apply one at an intensity from 0 through 255; use Color.NONE to restore the untinted asset.

image.border(value=None)

Read or change the border Color; use Color.NONE to remove it.

image.visible(value=None)

Read or change whether the Image is drawn.

image.front() · image.back()

Move the Image to the front or back of the Screen's drawing order.

image.remove()

Detach the Image from its Screen; use screen.add(image) to restore it.

Example

portrait.color(Color("blue"), alpha=160)
portrait.border(Color("navy"))
portrait.front()

Restore the source

portrait.color(Color.NONE)
portrait.border(Color.NONE)

05

Geometry & collision

Image geometry is the rectangular displayed area of the asset, including movement, resizing, and rotation—not the transparency or painted outline of individual pixels.

image.vertices() · image.bounds()

Read the four rotated corners or the axis-aligned bounds.

image.contains(point) · image.overlaps(renderable)

Test a point or another Renderable against the image rectangle.

image.distance(object_or_location)

Measure from the Image center to another object or point.

image.clone()

Create an active copy on the same Screen with the same source and core visual settings.

ALSO SUPPORTS

angleto()lookat()forward()backward()pen()

Example

if player.overlaps(obstacle):
    player.moveto(start)

if player.contains(screen.mouse()):
    player.color(Color("yellow"))

Clone

ghost = player.clone()
ghost.move(20, 20)
ghost.color(Color("light blue"))
ghost.back()

06

Animated GIFs

GIF animation is program-controlled. Load the frame sequence once, then advance or select frames from the same global loop that updates the rest of the program.

image.load()

Decode an animated GIF and select frame 0.

image.frames()

Return the decoded frame count, or -1 before an animation is loaded.

image.frame(value=None)

Read or select a zero-based frame index.

image.next()

Advance one frame and wrap from the final frame back to frame 0.

Example

animation = Image(screen, "images/walk.gif", 100, 80)
animation.load()

while True:
    animation.next()
    screen.update()
    screen.sleep(0.08)

Select a frame

animation.frame(0)
last = animation.frames() - 1
animation.frame(last)