Videos
bewegung.Video
objects define and structure animations. They hold information on the width, height, frames per second and length of the video. Once a bewegung.Video
object has been created, it exposes decorator methods for user-defined sequence classes, prepare task methods and layer task methods. After the decoration of all relevant user-defined classes and methods, a video can be rendered by calling bewegung.Video.render()
. Alternatively, individual frames can be extracted as still-images by calling bewegung.Video.render_frame()
. In the latter case, a bewegung.Video
object must be reset at least once in advance by calling bewegung.Video.reset()
. The rendering of videos is fully parallelized. bewegung.Video
objects can use different encoders for generating the actual video file.
bewegung.Video
objects provide access to different canvas types and backends, see bewegung.Video.canvas()
. bewegung.Video
objects can, if required, manage a context dictionary for user-defined information, see bewegung.Video.ctx
, which is exposed to all sequences, prepare tasks and layer tasks. bewegung.Video
objects also manage two bewegung.IndexPool
objects - one for prepare tasks, see bewegung.Video.preporder
, and one for layer tasks, see bewegung.Video.z-index
.
The Video
Class
- class bewegung.Video(width, height, ctx=None, fps=60, seconds=None, frames=None)
This class is the “core” of
bewegung
. It generates video objects. They manage sequences, layer tasks and prepare tasks Video objects are also responsible for rendering actual video files and individual frames.Video objects are mutable.
- Parameters
width (
int
) – Video width in pixelsheight (
int
) – Video width in pixelsctx (
Optional
[Dict
]) – Context, store for any type of video context datafps (
int
) – Frames per secondseconds (
Union
[float
,int
,None
]) – Duration of video in seconds (frames
andseconds
are mutually exclusive. Specify excactly one of two.)frames (
Optional
[int
]) – Duration of video as number of frames (frames
andseconds
are mutually exclusive. Specify excactly one of two.)
- __len__()
Duration of video as number of frames
- Return type
int
- __repr__()
String representation for interactive use
- Return type
str
- canvas(backend='drawingboard', **kwargs)
A method to create function pointers to factory functions generating new canvases. The pointers can be passed to the
canvas
parameter in thebewegung.Video.layer()
decorator method.- Parameters
backend (
str
) – Selected type of canvas, i.e. name of desired backend.kwargs – Keyword arguments of the selected backend’s canvas creation function.
- Return type
Callable
- property ctx: Dict
Context (mutable), store for any type of video context data
- Return type
Dict
- property fps: int
Frames per second
- Return type
int
- property height: int
Height of video in pixels
- Return type
int
- layer(zindex=None, canvas=None, offset=None)
A decorator for decorating
layer
methods (tasks) withinsequence
classes. Methods are wrapped with callablebewegung.core.layer.Layer
objects.- Parameters
zindex (
Optional
[int
]) – A number, managed by anbewegung.IndexPool
object (bewegung.Video.zindex
), representing the relative position within a stack oflayer
tasks. If not provided, the new layer will be created on top.canvas (
Optional
[Callable
]) – A function pointer to a factory function, generating a new canvas once per frame for thelayer
task. The pointer is typically generated by thebewegung.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.
- Return type
Callable
- property length: bewegung.animation._abc.TimeABC
Duration of video
- Return type
TimeABC
- prepare(preporder=None)
A decorator for decorating
prepare
methods (tasks) withinsequence
classes.- Parameters
preporder (
Optional
[int
]) – A number, managed by anbewegung.IndexPool
object (bewegung.Video.preporder
), representing the relative position within a set ofprepare
tasks. If not provided, the new task will be created at the end of the set.- Return type
Callable
- property preporder: bewegung.animation._indexpool.IndexPool
Prepare-order
bewegung.IndexPool
object for prepare tasks (mutable)- Return type
- render(processes=1, batchsize=256, encoder=None, frame_fn=None, video_fn=None)
A method for rendering the actual video file.
This function starts at least one Python sub-process (worker process) for rendering frames. Based on multiple worker processes, multiple frames can be rendered in parallel. If a filename for a video is specified, the rendered frames are streamed to a video encoder.
- Parameters
processes (
int
) – Number of parallel frame rendering (worker) processesbatchsize (
int
) – Maximum number of frames rendered by a worker process before the (old) worker is replaced by a new worker. This option helps to prevent long rendering jobs from running out of memory.encoder (
Optional
[EncoderABC
]) – A video encoder object. If omitted, abewegung.FFmpegH264Encoder
object will generated and used.frame_fn (
Optional
[str
]) – A Python string (representing a path) including an integer replacement field calledindex
. If specified, individual frames will be stored here. If omitted, no frames will be stored.video_fn (
Optional
[str
]) – Location and name (path) of where to store the video file. If omitted, no video will be rendered. However, indivual frames may in fact still be rendered ifframe_fn
has been specified.
- render_frame(time, return_frame=True, frame_fn=None)
A method for rendering individual frames of the video.
The frames can optionally be written to disk and/or returned to the caller. Before calling this method for the first time,
bewegung.Video.reset()
must be invoked!- Parameters
time (
Time
) – Time of the frame relative to the beginning of the videoreturn_frame (
bool
) – IfTrue
, the frame is returned to the caller of the method.frame_fn (
Optional
[str
]) – Location and name (path) of where to store the rendered frame. If omitted, the frame is not stored.
- Return type
Optional
[Image
]- Returns
If requested via
return_frame
, a pillow image object is returned.
- reset()
This method allows to reset a video object in preparation of a new render run. It is automatically invoked when calling
bewegung.Video.render()
. It may instead be used before rendering indivual frames withbewegung.Video.render_frame()
.
- sequence(start=None, stop=None, length=None)
A decorator for decorating user-defined
sequence
classes. New classes are created by makingbewegung.core.sequence.Sequence
inherit from the user-defined sequence classes.- Parameters
start (
Optional
[Time
]) – Time of start of sequence within the video. A negative time can be used to specify a time relative to the end of the video. Defaults to the beginning of the video.stop (
Optional
[Time
]) – Time of stop of sequence within the video. A negative time can be used to specify a time relative to the end of the video. Defaults to the end of the video.stop
andlength
are mutually exclusive. Specify one at most.length (
Optional
[Time
]) – Length of the sequence.stop
andlength
are mutually exclusive. Specify one at most.
- Return type
Callable
- time(index)
Generates a new
bewegung.Time
object from a given number of frames based on the video’s frames per second.- Parameters
index (
int
) – Number of frames- Return type
TimeABC
- time_from_seconds(seconds)
Generates a new
bewegung.Time
object from a given time in seconds based on the video’s frames per second.- Parameters
seconds (
Union
[float
,int
]) – Time in seconds- Return type
TimeABC
- property width: int
Width of video in pixels
- Return type
int
- property zindex: bewegung.animation._indexpool.IndexPool
Z-index
bewegung.IndexPool
object for layers (mutable)- Return type