Layer Tasks

Layer tasks are special, decorated methods within user-defined sequence classes. They allow to “draw an image” once per frame. Similar to prepare task methods, they are evaluated in a certain order, the z-index. A pool of z-index-values is managed by bewegung.Video.zindex once per video. Layer tasks can request parameters on demand.

Layers can be configured to use a certain backend for drawing. DrawingBoard is the default backend, see here. It does not matter what kind of object a layer method returns as long as it is recognized by one of the currently loaded backends. If the canvas was provided by bewegung, a layer method usually does not need to return it - bewegung will keep a reference on it. There are exceptions however: The datashader backend for instance requires the user to convert the canvas to an image before the user must in fact return the image from the layer method.

Layers may have an offset from the top-left corner of the video frame, where the y-axes is positive downwards. The size, i.e. width and height, of a layer must be configured through its backend via the bewegung.Video.canvas() method.

Layers can be post-processed by an arbitrary number of Effects. Effects are special decorator classes which are stacked on top of the bewegung.Video.layer() decorator method.

The Video.layer Decorator

This method is used to decorate layer task methods within user-defined sequence classes. See bewegung.Video.layer() method for further details.

The Layer Class


Do not work with this class directly. Use the bewegung.Video.layer() method instead.

class bewegung.animation.Layer(method, zindex, video, canvas=None, offset=None)

Callable layer method wrapper (decorator), managing rendering and application of effects. Do not instantiate this class or derive from it - use the bewegung.Video.layer() decorator instead!


  • method (Callable) – Wrapped layer method from a user-defined sequence class

  • zindex (int) – A number, managed by an bewegung.IndexPool object (bewegung.Video.zindex), representing the relative position within a stack of layer tasks.

  • video (VideoABC) – Parent video object

  • canvas (Optional[Callable]) – A function pointer to a factory function, generating a new canvas once per frame for the layer task. The pointer is typically generated by the bewegung.Video.canvas() method.

  • offset (Optional[Vector2D]) – The layer’s offset relative to the top-left corner of the video. The y-axis is downwards positive.

__call__(sequence, time)

Wraps layer method from a user-defined sequence class. This method determines what parameters the user-defined layer method requested. Possible options are:

  • time: The absolute time within the parent video

  • reltime: The relative time within the parent sequence

  • canvas: An empty canvas

Subsequently, the user-defined layer method is called with the requested parameters. It then converts the returned canvas to a Pillow Image object by making the currently loaded backends recognize the returned canvas type. Finally, effects are applied and the Pillow Image object is returned.

  • sequence (SequenceABC) – Parent sequence

  • time (TimeABC) – Time within video

Return type



Detects the datatype of the canvas returned by the user-defined layer method and tries to convert it to a Pillow Image. Raises a type error if none of the currently loaded backends recognizes the canvas type.


obj (Any) – A canvas object

Return type



Interface used by effects decorators to register themselves. See bewegung.EffectBase.__call__().


effect (EffectABC) – Configured effect object

property zindex_tag: int

z-index of layer

Return type