Package: pympanim
Multiprocessed AnimationsSummaryThis library helps building movies in python from images. Specifically, it
intends to allow multiple threads to produce images which are stitched together
into movies with ffmpeg.Use-casesThis can be used to multithread the image creation process when using
matplotlib animations. FFMpeg will use multithreading to encode the images into
a video, however producing the images themselves is a bottleneck if you have
many cores available. Hence, this will vastly reduce the time it takes to
generate matplotlib animations.This can also be used for generating scenes withPIL.This library's goal is to make generating videos as simple as possible first,
then to go as fast as possible within those simple techniques. This gives fast
enough performance for many projects, and has the enormous benefit that you
can throw more hardware at the problem. Using ffmpeg directly without
multithreading image generation will not scale to more hardware.PerformanceWith ideal settings, the images should be generated at a rate that just barely
does not fill the ffmpeg process input pipe. This will ensure that images are
being generated as quickly as they can be encoded.By default, this library will attempt to find the settings that accomplish this
task. This takes a bit of time to accomplish, so the final settings are exposed
and it can be helpful to use those when re-running roughly the same task. The
correct settings will depend on how long it takes to generate images and how
long it takes to encode them which varies based on the image statistics.Installationpip install pympanimDependenciesThis depends on ffmpeg being installed. It can be installedhere. Other python dependencies will be
automatically installed by pip.Usage - ActsMotivationMany times you have something which is capable of rendering some underlying
state in a consistent way, and the video you want to produce is made up of
parts that manipulate the state that is sent to the renderer. This use case
is handled specifically bypympanim/acts.py.SummaryDefine the state that completely describes how to render things in a class that
subclassespympanim.acts.ActState. Then create the thing which can render
the given state to an image (described via rgba bytes or a Pillow Image).With these ready, create (one or more)Scenes, which are things that
manipulate the state you just created. A scene has some duration, and must be
able to set the state to correspond to a particular time within the scene.This library will provide common manipulations of scenes - nonlinear time
manipulations, cropping, reversing, and sequencing. To make the most use of
these manipulations, Scenes should be as simple as possible.Multiple Acts can be combined in much the same way. See Usage - Frame
Generators for details below.To produce the video, usepympanim.worker.produce, creating a frame generator
out of the scenes usingpympanim.acts.ActBoilerplateimportPIL.Imageimportpympanim.workeraspmawimportpympanim.actsasactsimportpympanim.frame_genasfgimportosclassMyActState(acts.ActState):passclassMyActRenderer(acts.ActRenderer):@propertydefframe_size(self):return(1920,1080)# in pixelsdefrender(self,act_state:MyActState)->bytes:returnfg.img_to_bytes(self.render_pil(act_state))defrender_pil(self,act_state:MyActState)->PIL.Image:# By default, render_pil delegates to render. It is shown reversed# here for completeness.returnPIL.Image.new('RGBA',self.frame_size,'white')classScene1(acts.Scene):@propertydefduration(self):return1# 1 millisecond; allows you to treat time_ms as % progressdefapply(self,act_state:MyActState,time_ms:float,dbg:bool=False):# dbg is passed across the scene heirarchy and will be false when# rendering the video. you may find it helpful to print some debug# information when it is truepassdef_scene():scene=Scene1()return(acts.FluentScene(scene).dilate(lambdax:x**2)# any easing works here. see# pympanim.easing and pytweening.time_rescale(1/10000)# 10s of real time corresponds to# 1ms of scene time.build())def_main():os.makedirs('out',exist_ok=True)act_state=MyActState()act_renderer=MyActRenderer()pmaw.produce(acts.Act(act_state,renderer,[_scene()]),fps=60,dpi=100,bitrate=-1,outfile='out/video.mp4')if__name__=='__main__':_main()For method-level documentation, use the built-inhelpcommand, i.e.,>python3
>>> import pympanim.acts
>>> help(pympanim.acts)
Help on module pympanim.acts in pympanim:
.. (omitted for readme brevity) ..Usage - Frame GeneratorsMotivationThe most novel part of this library is the boilerplate to generate videos where
the image generation itself is multithreaded. This is exposed in as raw a manner
as possible usingpympanim/frame_gen.pywhich is merely wrapped bypympanim/acts.py. This section discusses how to use this library with minimal
abstraction.SummaryCreate a subclass ofpympanim.frame_gen.FrameGenerator, which requires
defining a duration, frame size in pixels, and agenerate_atfunction which
can generate an image given just the time within the video.This library provides common manipulations of vidoes that you can wrap your
video with, such as cropping, time dilations, reversing time, and combinations
of frame generators.To produce the video, usepympanim.worker.produce. Everything else is handled
for you, including reasonable guesses for performance settings and runtime
performance tuning.BoilerplateimportPIL.Imageimportpympanim.frame_genasfgimportpympanim.workeraspmawimportosclassMyFrameGenerator(fg.FrameGenerator):@propertydefduration(self):return1# 1 ms, allows you to treat time_ms as % progress@propertydefframe_size(self):return(1920,1080)# in pixelsdefgenerate_at(self,time_ms):# by default generate_at_pil delegates to generate_at. we show the# reverse for completenessreturnfg.img_to_bytes(self.generate_at_pil(time_ms))defgenerate_at_pil(self,time_ms):# this from white to red, you can do whateverreturnPIL.Image.new('RGBA',self.frame_size,f'#{int(time_ms*255):02x}0000')def_fg():base=MyFrameGenerator()# random example of the stuff you can doreturn(fg.FluentFG(base).time_rescale(1/10000)# 10s long.then(# after currentfg.FluentFG(base)# play again.time_rescale(1/10000)# also 10s long.reverse()# but this time in reverse.build()).build())def_main():os.makedirs('out',exist_ok=True)pmaw.produce(_fg(),fps=60,dps=100,bitrate=-1,outfile='out/video.mp4')if__name__=='__main__':_main()ExamplesThe examples/ folder has the sourcecode for the following examples:python3 -m examples.redsquareProduceshttps://gfycat.com/digitalmaleflyingfishpython3 -m examples.mpl_lineProduceshttps://gfycat.com/wickedpracticalattwatersprairiechickenKnown IssuesIf processes are forked instead of spawned, text will appear spastic in
matplotlib. In general, matplotlib does not handle forked processes well.
The worker attempts to force spawning mode instead of fork-mode, but this
will fail if the process is already forked. If you are experiencing weird
or glitchy videos, include thisbefore any other importswhich might be
spawning processes (e.g. torch or torchvision).importmultiprocessingasmptry:mp.set_start_method('spawn')exceptRuntimeError:pass