animator.scene.Scene

class animator.scene.Scene(width: int | str = 854, height: int = 480, fps: float = 30, scale: float | tuple[int, int] | str = 1)

Bases: object

The scene class. This is the main class for creating animations. It initializes a frame and a canvas to draw on, and provides methods for displaying and saving them.

Variables

  • width – The width of the frame/scene.

  • height – The height of the frame/scene.

  • fps – The FPS used for animations.

  • frame – The internal frame (array) used for drawing. The data type is in RGBA format.

  • canvas – The skia.Canvas used for drawing.

  • bgcolor – The background color of the scene. This is used when clearing the scene after each frame.

__init__(width: int | str = 854, height: int = 480, fps: float = 30, scale: float | tuple[int, int] | str = 1) → None
Parameters

  • width – The width of the frame/scene or a string representing a resolution. Resolutions can be one of ‘144p’, ‘240p’, ‘360p’, ‘480p’, ‘720p’, ‘hd’, ‘1080p’, ‘fhd’, ‘fullhd’, ‘1440p’, ‘2k’, ‘2160p’, ‘4k’, ‘uhd’, ‘ultrahd’. The resolution strings are case-insensitive and may contain whitespaces.

  • height – The height of the frame/scene.

  • fps – The FPS used for saving the animation. The FPS used for displaying the animation may be different.

  • scale – Amount to scale the frame up or down. This can be a float, in which case the frame is scaled by that amount, or a tuple of two integers, in which case the frame is scaled to that size. This can also be a string representing a resolution (see width parameter). During displaying animations a large frame may cause lag or not fit on the screen. This factor is used to scale the frame down. By specifying a value >1, the frame can also be scaled up. If the aspect ratio of the frame is different from that of the scene, the frame will be centered.

Methods

__init__([width, height, fps, scale])

param width

The width of the frame/scene or a string representing a resolution. Resolutions can be one of

add(*entities)

Add one or more entities to the scene.

animate(*animations)

Adds one or more animations to the scene.

clear()

Clears the frame and fills it with transparency.

clear_with_bgcolor()

Clears the frame and fills it with the background color.

play_frames([delay, keep_open])

Plays the animation by displaying each frame in the scene.

quickdraw()

A simple way to quickly draw something on the scene.

r2a(pos[, padding])

Convert a point from the scene's relative coordinate system to absolute coordinates.

r2a_bounds(bounds, pos[, anchor, padding])

Convert the position of a bounding box from the scene's relative coordinate system to absolute coordinates.

save_frame(path[, quality])

Saves the current frame to a file.

show_frame()

Displays the current frame.

update()

Updates the scene.

wait(seconds)

Waits for a specified amount of seconds before continuing.

Attributes

context2d

An instance of Context2d wrapping the canvas.
add(*entities: animator.entity.entity.Entity) → None

Add one or more entities to the scene.

Parameters

entities – The entities to add.

animate(*animations: animator.anim.anim.Anim) → None

Adds one or more animations to the scene.

Parameters

animations – The animations to add.

clear() → None

Clears the frame and fills it with transparency.

clear_with_bgcolor() → None

Clears the frame and fills it with the background color.

property context2d: animator.graphics.Context2d.Context2d

An instance of Context2d wrapping the canvas. A Context2d wraps a skia.Canvas and provides additional methods for drawing. A scene contains a single Context2d instance, which can be accessed through this method.

play_frames(delay: Optional[float] = None, keep_open: bool = True) → None

Plays the animation by displaying each frame in the scene.

Parameters

  • delay – The delay between frames in seconds. If None, the delay is set to 1 / fps. If 0, the animation is played as fast as possible.

  • keep_open – Whether to keep the animation open after playing. To close the animation, press Esc or close the window.

quickdraw() → Iterator[animator.graphics.Context2d.Context2d]

A simple way to quickly draw something on the scene. This method clears the scene and returns a Context2d for drawing. When the context manager exits, the frame is displayed.

>>> import animator as am
>>> scene = am.Scene()
>>> with scene.quickdraw() as ctx:
...     ctx.circle(scene.width / 2, scene.height / 2, 120)
...     ctx.fill()
>>> # A circle is drawn at the center with a black background.
r2a(pos: numpy.ndarray, padding: float = 25) → animator.skia.Point

Convert a point from the scene’s relative coordinate system to absolute coordinates.

Parameters

  • pos – The point in relative coordinates, a 2 element numpy array [x, y]. The coordinates are between -1 and 1, where -1 is the left/top edge of the scene and 1 is the right/bottom edge.

  • padding – The extra space around the scene, in pixels.

Returns

The point in absolute coordinates.

r2a_bounds(bounds: animator.skia.Rect, pos: numpy.ndarray, anchor: Optional[numpy.ndarray] = None, padding: float = 25) → animator.skia.Point

Convert the position of a bounding box from the scene’s relative coordinate system to absolute coordinates.

Parameters

  • bounds – The bounding box that is to be positioned.

  • pos – The position of the bounding box in relative coordinates, a 2 element numpy array [x, y]. The coordinates are between -1 and 1, where -1 is the left/top edge of the scene and 1 is the right/bottom edge.

  • anchor – The anchor point in the bounding box in relative coordinates, which will be positioned at pos. If None, it’ll be same as pos.

  • padding – The extra space around the scene, in pixels.

Returns

The position of the bounding box in absolute coordinates.

save_frame(path: str, quality: int = 100) → None

Saves the current frame to a file.

Parameters

  • path – The path to the file. The path may contain a {} placeholder, which will be replaced with the current frame number.

  • quality – The quality of the image, between 0 and 100. Defaults to 100.

show_frame() → None

Displays the current frame.

update() → bool

Updates the scene. This method is called before each frame is drawn. It draws all entities in the scene.

Returns

False if the animation should stop, True otherwise.

wait(seconds: float) → None

Waits for a specified amount of seconds before continuing.