Quick-start guide

This page will guide you through the syntax and feature of Diplotocus.

First, here are a few terms we will be using:

  • a Timeline is the main object of a project. It holds the figure, axes, and is responsible for running animations and rendering the video (See Timeline for more information).

  • a plot object is any matplotlib plotting function you are familiar with: plot(), scatter(), hist(), text()… (See Plot objects for more information).

  • an animation is what is applied to plot objects to animate it: translate(),rotate(),tween… (See Animations for more information).

  • an easing is a mapping between frame number and time, that might not be linear (See Easings for more information).

The basic steps involved in creating animations are the following:

  1. Create a Timeline object. Optionally, you can give it an existing figure, or define its initial properties.

  2. Create plot objects, like a scatter, plot, hist…

  3. Define animations for these plot objects, like a translation, a rotation, a tween…

  4. Render the animations to images using Timeline.animate(plot_objects), where plot_objects is a list of the plot objects you created at step 2.

  5. Render the animation to a video file using Timeline.save_video().



Let’s go through the example on the main page step by step:

First, we import our modules. By convention, we import diplotocus as dpl, à la import matplotlib.pyplot as plt.

import diplotocus as dpl
import numpy as np

Next, we create our Timeline object. Here, we don’t pass an existing figure, so it will create one for us. We can give the initial X and Y limits of its axis.

tl = dpl.Timeline(xlim=(0,6*np.pi),ylim=(-1,1))

We create our datapoints, and create our plot object.

x = np.linspace(0,6*np.pi,200)
y = np.cos(x)

p = dpl.plot(x=x,y=y)

Next, we want our plot to appear gradually, each point being added frame after frame.

p.draw(duration=100)

Now we can render our animation to images. We call Timeline.animate() and we pass our plot objects. Here we only have one, so we can just pass it directly.

tl.animate(p)

After the plot has fully been animated, we want to wait a few frames before animating our axis.

tl.wait(duration=25)

We want to animate our axis, by zooming out and moving its center to (0,0), simultaneously. We define our two animations, axis_zoom and axis_move, and we animate them through our Timeline.

az = dpl.axis_zoom(zoom=0.5,duration=50)
am = dpl.axis_move(end_pos=(0,0),duration=50)
tl.animate((az,am))

For the final part of our animation, we want to fade out our plot. For that, we call plot.hide(), and we render it.

p.hide(duration=100)
tl.animate(p)

That’s it! The only thing left to do is render our sequence of images to a video file.

tl.save_video(path='../_static/demo.mp4')

Et voilà! This is a very simple example, but Diplotocus is capable of much more. You might want to add easing functions to your animation to make them feel more natural and smooth. You can also render your animations without axes, with a transparent background, with white axes for a dark presentation…

If your animation gets complex, you might want to try the GUI version of Diplotocus, which lets you build a timeline in your browser with simple controls.