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.
- draw() - Draw the object on the surface.
- 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.
- unhides the instance at the start frame. This does not have an end frame in the arguments as the operations is performed on a single frame.
- end_show(start, current)
- hides the instance at the start frame. This does not have an end frame in the arguments as the operation is performed on a single frame.
AnimActor (Sprites)
Creates a Pygame Zero Actor class with additional keyframe and tween animations methods.
The first argument must include the image filename. It uses the Pygame Zero loader, so if the file exists in the images directory then it does not require an explicit pathname. If the file ends with .png or .jpg then no extension is required.
Optional arguments are: pos, anchor, hide and angle (explained in PGZAnimation class). Any additional Actor parameters can be passed as kwargs.
AnimLine
The AnimLine class is used to draw a line. These can be straight lines or may include different styles (such as dash). The constructor must have the start, end and color. Other attributes are optional.
- start - x, y co-ordinates of start position
- end - x, y co-ordinates of the end position
- anchor - anchor position for rotation
- width - width of the line (in pixels)
- style - style of the line (solid or dashed)
- spacing - when style is set to dashed then this is the ratio of on to off.
- dashoffset - Number of pixels for offset (normally used for animated lines
- dashanimate - How far to animate stylized lines
- animateenable - True to enable the animation (eg. dash animation), False to stop animation
The following attributes can also be used.
- scale - Scale using (xscale, yscale)
- rect - Returns a bounding rectangle based on current rotation. Useful for collidepoint test.
The following methods are available in addition to the standard methods.
- move_rel(delta) - Move relative to current position.
- scale_tween(start, end, current, newscale) - Tween scale from current scale to newscale
- reveal_tween(start, end, current) - Draws the line a bit at a time. Reveal will override hide, so by hiding first then reveal it will appear to draw.
More information
See the Introduction to PGZAnimation
Also see my other programming guides at:
