PGZ Animation - Guide to the PGZAnimation classes

PGZ Animation is a library for creating animations in Pygame Zero, which can then be exported as png image files. These can then be combined into a video animation.

This document introduces the methods of the PGZAnimation class and various sub classes.

How Animations Work

Animations are created by creating an object instance. These are normally stored in one of the following lists/dictionaries.

shape_groups - This is normally a dictionary of dictionaries. This allows multiple instances which can be acted on simultaneously. It is often simpler to use the shapes list instead, but this can be useful to reduce coding for objects that are grouped together. All items in these groups are displayed unless otherwise disabled (through their hide attribute) and are regularly updated through their update method (which defaults to pass in the PGZAnimation parent class).
shapes - The simpler way to handle objects. This is normally a dictionary of objects. It could be replaced with a list if the labels aren't required, but the labels are often useful to make it clear which object is which. All shapes are displayed (unless disabled through their hide attribute) and updated through their update method.

These are also slide templates which can be used, but these are covered in the PGZ Animation - Slide Templates documentation

Once created the objects can be manipulated using one of the animation methods. Normally these take a minimum of three arguments as listed below:

start - The first frame when the method will perform the animation operation.
end - The last frame when the method will perform the animation operation.
current - The current frame held in the global variable frame.

Occassionally one or more of these parameters may be omitted depending upon the sub class and operation. The method will often take one or more additional arguments to describe the requested operations.

PGZAnimation - Common Methods

The parent class is called PGZAnimation. It should not be used directly, but is instead sub classed by the other animation classes. The attributes and methods listed in this section apply to all sub classes (unless otherwise mentioned).

init

The __init__ constructor method must be called by all subclasses. This must include a color attribute. The other attributes are anchor, hide and angle, which have default values if not provided. These are explained in more details in the respective classes.

color - A Pygame color. Typically this is a tuple with the (R,G,B) colors.
anchor - The position that the object is anchored around. This is important for rotation and other transformation operations. This should be provided as a tuple using words for the x and the y location. This defaults to ('center', center'). Other options for the x component are 'left' and 'right', for the y component these can be 'top' and 'bottom'.
hide - Used to hide the object. When hidden it does not display on the screen and will not be included in any animations.
angle - Rotational angle. The default is 0, but can be replaced with a angle in degrees. The angle is interpretted as degress from the horizontal in a counter-clockwise direction (the same as Pygame Zero).

These attributes can be accessed publically, although some are handled through getters and setters as appropriate.

The constructor creates the internal attribute self._surface which holds the Pygame Zero surface used for displaying images.

The following attributes are handled by PGZAnimation, but are dependant upon the subclasses.

pos - Position of the instance. This is provided as a tuple (x,y). If set then the object will move immediately to that position. The position is based on the anchor position.
The following methods must be provided by the sub classes.
- move(new_pos) - Move immediately to new_pos. The new_pos must be a tuple of (x, y).
- rotate(new_value) - Immediately rotates to the new angle (and saves the new angle position). Rotation is in degrees counter-clockwise.
- calc_pos() - Updates the _pos position based on the anchor position. Does not change the display position of the object.
- _transform() - Calculates positions required to take into consideration anchor and transformations (scale and angle)
The following methods are provided by the PGZAnimation class and as such are available to all subclasses. These may be overridden by the sub class if required.
- show(start, current)
- unhides the instance at the start frame.