Module animation

The animation module provides base classes upon which to build custom animation routines. Animations built from these classes can be run with only two lines of code an continue running based on a wide array of options. For example:

anim = StripChannelTest(led)
anim.run()

This will run StripChannelTest continuously and as fast as possible.

For more information on using the animation classes, see Writing an Animation.

Class BaseAnimation

BaseAnimation serves as the basis for BaseStripAnim and BaseMatrixAnim and should not be inherited from directly. It simply provides any code that is shared between BaseStripAnim and BaseMatrixAnim.

__init__(led)

• led - An instance of LEDMatrix or LEDStrip

preRun()

By default, preRun does nothing but can be overridden by any class that inherits from BaseStripAnim and BaseMatrixAnim. If overridden, if will always be called at the beginning of each call to run(). This is mainly provided as a way to always initialize to a proper state without the user of your animation class having to call anything except run().

step(amt = 1)

• amt - Amount to increment _step by after each call to step(). Increments by 1 by default. As step() is generally called by run(), this value will be set to whatever is passed into run(). This parameter is required by can be ignored by your step() implementation. Actually incrementing _step is the responsibility of the animation author.

step() MUST be overridden for an animation class otherwise it will throw an exception. This is where all of the work is actually done to generate the animation frame. The frame should only be generated here. Updating of the display will occur in run().

def step(self, amt = 1):
    self._led.fill((self._step, 0, 0))
    self._step += amt
    if self._step > 255:
        self._step = 0

The above step() implementation will fill the entire display with increasing brightness values of red, wrapping around to 0% once it reaches maximum brightness.

run(amt = 1, fps=None, sleep=None, max_steps = 0, untilComplete = False, max_cycles = 0)

• amt - Amount to increment _step after each frame is generated. Can be used to run the animation faster without changing the framerate by skipping frames.
• fps - Target frames per second to run the animation at. Guaranteed to not run faster but may not run as fast as set if the frame generation and display update takes too long. Ignored if sleep is set.
• sleep - Amount of time, in milliseconds, between each frame, including the time it takes to generate the frame and update the display. fps is ignored if sleep is set.
• max_steps - How many total steps to run the animation for before automatically quitting. This is incremented on its own and is not effected by amt.
• untilComplete - True/False: Run the animation until animComplete flag is set by the animation itself.
• max_cycles - Only used with untilComplete. If set above 0, the animation will run until animComplete flag has been set that many times.

Properties

---

_led

Instance of LEDMatrix or LEDStrip that was passed into the animation.

_step

The current frame step which can be used for keeping track of the animation state and is incremented in step()

_internalDelay

This can be set to a number of milliseconds by the animation itself to override any fps or sleep settings. Mainly it is to be used for animations that require variable timing between each frame.

animComplete

Set to True to flag the animation sequence as complete and use with the untilComplete option when running the animation.

Class BaseStripAnim

BaseStripAnimation is the basis for any animation that runs with an instance of LEDStrip and provides all the same methods and properties as BaseAnimation plus those below.

__init__(led, start=0, end=-1)

• led - An instance of LEDMatrix or LEDStrip
• start - Pixel index to start the animation at, defaults to 0
• end - Pixel index to end the animation at. It left at -1, it will default to the last pixel on the strip.

Note: The start and end parameters must be respected by the inheriting animation for them to do anything.

Properties

---

In addition to the properties provided by BaseAnimation, the following properties are available to classes that inherit from BaseStripAnim.

_start

Index of the first pixel to start the animation at. This does not have to be used by an animation class but it is recommended that it be respected.

_end

Index of the last pixel to end the animation at. This does not have to be used by an animation class but it is recommended that it be respected.

_size

The calculated size of the total animation space, (_end - _start)

Class BaseMatrixAnim

BaseStripAnimation is the basis for any animation that runs with an instance of LEDStrip and provides all the same methods and properties as BaseAnimation plus those below.

__init__(led, width=0, height=0, startX=0, startY=0)

• led - An instance of LEDMatrix or LEDStrip
• width - Width of the pixel matrix. If 0, width will be retrieved from the led instance.
• height - Height of the pixel matrix. If 0, height will be retrieved from the led instance.
• startX - X coordinate to start the animation at.
• startY - Y coordinate to start the animation at.

Note: The startX and startY parameters must be respected by the inheriting animation for them to do anything.

Properties

---

In addition to the properties provided by BaseAnimation, the following properties are available from BaseMatrixAnim.

width

Width of the pixel matrix.

height

Height of the pixel matrix.

startX

X coordinate to start the animation at. This does not have to be used by an animation class but it is recommended that it be respected.

startY

Y coordinate to start the animation at. This does not have to be used by an animation class but it is recommended that it be respected.