Animation

CircuitPython Animation Class to make it easy to move around displayio and vectorio graphical elements.

  • Author(s): Kevin Matocha

Implementation Notes

Hardware:

Software and Dependencies:

class displayio_animation.Animation(**kwargs)

An Animation class to make it easy to making moving animations with CircuitPython’s displayio and vectorio graphical elements.

After instancing an Animation() object, use Animation.add_entry() to add frame animation sections. Once all your animation entries are added, then perform the frame animation using Animation.execute_frame().

add_entry(group, frame_start, frame_end, function, **kwargs)

Adds an animation entry into the Animation list.

Parameters

  • group (displayio.Group) – the displayio Group that will be animated within this frame range

  • frame_start (float) – the starting frame position for this animation

  • frame_end (float) – the ending frame position for this animation

  • function – the name of the function to be called to mutate the group during the frame range

  • **kwargs – the additional arguments that should be passed to function when Animation.execute_frame() is called to trigger the animation to execute

Note: See the definition of Animation.execute_frame() to understand what other parameters are sent to function during animations.

execute_frame(frame)

The function that performs the actual frame animation execution.

This function searches through all Entry items that have been added to the Animation instance to determine if this frame is within the window of frame_start to frame_end. If the requested frame is within the window, this calls the Entry.function with several “internal” parameters along with the additional “user” parameters that were input as additional arguments in the Animation.add_entry() function.

The parameters that are sent to Entry.function() are: - float position: a value between 0.0 and 1.0 representing the current frame distance within the window of frame_start and frame_end. For example, if the current frame is equal to frame_start, then position is 0.0. - displayio.Group group: the group to be animated using function - int x0: the x-position of the group at frame_start - int y0: the y-position of the group at frame_start - float frame: the current frame that is being executed - float frame_start: the starting frame for this frame window - float frame_end: the ending frame for this frame window - **kwargs: any other parameters that were defined in the Entry

The function should be designed to ignore any unneeded input parameters by including **kwargs as one of the input parameters. This will cause the function to ignore excess arguments.

Note: If a function requires the (x0,y0) values, you must initally perform Animation.execute_frame() at frame == frame_start. The Animation.execute_frame() initializes the (x0, y0) values only when called with the value of frame_start.

Other Note: The frame window is “exclusive”, so no animation is performed when frame == frame_end.

Parameters

frame (float) – The frame to be displayed. Note: This is a float, so subframes can be animated.

class displayio_animation.Entry(group, frame_start, frame_end, function, kwargs)

This Entry class is a holder for the conditions that define an animated frame range. This holds the group, the “augmentation” function and arguments that are run at each call of Animation.execute_frame.

Before running your loop with Animation.execute_frame, add all of your entries to the Animation object using Animation.add_entry(). Any excess arguments that are not handled by Animation.execute_frame will be passed to the function parameter (see notes on using the kwargs notation).

Here is a code example. Append some display elements into group1, create an Animation instance and then add an animation entry:

group1=displayio.Group(max_size=1)

animation=Animation()

animation.add_entry(group=group1,
 frame_start=5, frame_end=20,
 function=translate,
 x1=50, y1=20, x2=50, y2=50,
 easing_function_x=quadratic_easeinout,
 easing_function_y=quadratic_easeinout)
Parameters

  • group (displayio.Group) – the group that is animated in this set of frames

  • frame_start (float) – the starting frame for this animation

  • frame_end (float) – the ending frame for this animation

  • function – the function that mutates the group to cause the animation

  • kwargs – a set of additional arguments that will be passed to the function during the animation

displayio_animation.color_morph_label(*, color_start, color_end, label, position, **kwargs)

Performs color morphing for a text label between the color_start and color_end values based on the position parameter.

Parameters

  • color_start (int) – the starting color

  • color_end (int) – the ending_color

  • label – the label whose color is to be morphed

  • position (float) – float position: a linear interpolation of the current frame’s position between frame_start and frame_end. If using Animation.execute_frame() the position parameter will be included automatically.

displayio_animation.color_morph_palette(*, palette_start, color_end, palette_target, position, **kwargs)

Performs color morphing for a color palette between the palette_start and a single color_end value based on the position parameter. At the final position=1.0, the palette_target will be filled with the color_end value.

Parameters

  • palette_start (displayio.palette) – the starting palette for the image

  • color_end (int) – the single ending_color for all the colors in the palette

  • palette_target (displayio.palette) – the destination palette to be “morphed” to the ending_color

  • position (float) – float position: a linear interpolation of the current frame’s position between frame_start and frame_end. If using Animation.execute_frame() the position parameter will be included automatically.

displayio_animation.color_morph_vector_shape(*, color_start, color_end, vector_shape, position, **kwargs)

Performs color morphing for a vector shape, with color between the color_start and color_end values based on the position parameter.

Parameters

  • color_start (int) – the starting color

  • color_end (int) – the ending_color

  • vector_shape (vectorio.VectorShape) – the VectorShape whose palette color index 1 should be morphed.

  • position (float) – float position: a linear interpolation of the current frame’s position between frame_start and frame_end. If using Animation.execute_frame() the position parameter will be included automatically.

displayio_animation.translate(*, x1, y1, x2, y2, easing_function_x=adafruit_displayio_layout.widgets.easing.linear_interpolation, easing_function_y=adafruit_displayio_layout.widgets.easing.linear_interpolation, group, position, **kwargs)

Performs a translation animation between two endpoints. Use two different easing functions to get all kinds of variety of cool motion.

Parameters

  • x1 (int) – initial x-position of group

  • y1 (int) – initial y-position of group

  • x2 (int) – final x-position of group

  • y2 (int) – final y-position of group

  • easing_function_x (function) – easing function that modifies the position value for the x-motion (default: linear_interpolation)

  • easing_function_y (function) – easing function that modifies the position value for the y-motion (default: linear_interpolation)

  • group (displayio.Group) – the display group that is sent to the function. If using Animation.execute_frame() the group input parameter will be included automatically from the Entry.

  • position (float) – float position: a linear interpolation of the current frame’s position between frame_start and frame_end. If using Animation.execute_frame() the position parameter will be included automatically.

displayio_animation.translate_relative(*, delta_x, delta_y, easing_function_x=adafruit_displayio_layout.widgets.easing.linear_interpolation, easing_function_y=adafruit_displayio_layout.widgets.easing.linear_interpolation, group, x0, y0, position, **kwargs)

Performs a relative translation animation between two endpoints. Use two different easing functions to get all kinds of variety of cool motion.

Note: To use relative translations, be sure to run execute_frame at frame_start first so the initial (x0, y0) position is stored. For example, if you run the frames in reverse, you must run execute_frame at frame_start at least once initialize the initial (x0, y0) position.

Special note: Relative translations can get complicated. If you want to tightly control predefined positions, then translate is the best approach. By combining overlapping relative translations, you can probably come up with all kinds of clever and confusing animations. Perhaps the translate_relative function is an avenue to create animated “generative art” projects.

Parameters

  • x2 (int) – final x-position of group

  • y2 (int) – final y-position of group

  • easing_function_x (function) – easing function that modifies the position value for the x-motion (default: linear_interpolation)

  • easing_function_y (function) – easing function that modifies the position value for the y-motion (default: linear_interpolation)

  • group (displayio.Group) – the display group that is sent to the function. If using Animation.execute_frame() the group input parameter will be included automatically from the Entry.

  • x0 (int) – initial x-position of group. If using Animation.execute_frame() the x0 input parameter will be included automatically from the Entry.

  • y0 (int) – initial y-position of group. If using Animation.execute_frame() the y0 input parameter will be included automatically from the Entry.

  • position (float) – float position: a linear interpolation of the current frame’s position between frame_start and frame_end. If using Animation.execute_frame() the position parameter will be included automatically.

displayio_animation.wiggle(*, delta_x=0, delta_y=0, xsteps=None, ysteps=None, group, x0, y0, frame_start, frame, **kwargs)

Performs a nervous wiggling animation around the starting point. To achieve a random-looking wiggle, set xsteps and ysteps to two different prime numbers.

Note: To use wiggle, be sure to run execute_frame at frame_start first so the initial (x0, y0) position is stored. For example, if you run the frames in reverse, you must run execute_frame at frame_start at least once initialize the initial (x0, y0) position.

Parameters

  • delta_x (int) – amount of x-movement, in pixels (default = 0)

  • delta_y (int) – amount of y-movement, in pixels (default = 0)

  • xsteps (int) – number of frame steps it takes to make a full x-direction wiggle

  • ysteps (int) – number of frame steps it takes to make a full y-direction wiggle

  • group (displayio.Group) – the display group that is sent to the function. If using Animation.execute_frame() the group input parameter will be included automatically from the Entry.

  • x0 (int) – initial x-position of group. If using Animation.execute_frame() the x0 input parameter will be included automatically from the Entry.

  • y0 (int) – initial y-position of group. If using Animation.execute_frame() the y0 input parameter will be included automatically from the Entry.

  • frame_start (float) – the starting frame of this animation entry. If using Animation.execute_frame() the frame_start parameter will be included automatically from the Entry.

  • frame (float) – the current frame being animated. If using Animation.execute_frame() the frame parameter will be included automatically.