`matplotlib`: what is the purpose of an artist's animated state?

Question

Artists in matplotlib have methods to set/get their animated state (a boolean). I can't seem to find documentation to explain the purpose of the "animated state" variable. Can you explain, or point me to an appropriate resource?

Answer 1

I'm not sure it's thoroughly documented anywhere, but the animated state of an artist controls whether or not it's included when drawing the plot.

If animated is True, then the artist will not be drawn when fig.draw() is called. Instead, it will only be drawn when you manually call draw_artist(artist_with_animated_set). This allows for simplification of blitting functions.

Note: This does not apply to all backends! I think it applies to almost all interactive backends, but it doesn't apply to non-interactive backends. It's intended to be used in combination with blitting, so backends that don't support blitting don't support the animated flag.

For example, if we do something similar to this:

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot(range(10), animated=True)
plt.show()

We'll get a blank plot -- the line will not be drawn. (Note: If you save this figure, the line will show up. See the caveat about non-interactive backends above. Matplotlib temporarily switches to a non interactive backend to save a figure.)

To get a sense of why this is useful, suppose you were making an animation or interactive gui (and weren't using the new animation framework). You'll want to use blitting to make the animation appear "smooth".

However, whenever the figure is resized, etc, the animation's background will need to be updated. The best way to handle this is to connect a callback to the draw event. Without the animated flag, you'll have to redraw the plot inside your draw callback, which will cause an infinite loop. (The workaround is to disconnect and reconnect the draw event callback, but that's a bit of a pain.)

At any rate, the animated flag simplifies this process quite a bit. For example, you might use the animated flag in something similar to the following:

import numpy as np
import matplotlib.pyplot as plt

class AnimatedSinWave(object):
    def __init__(self, speed=0.1, interval=25):
        self.fig, self.ax = plt.subplots()
        self.x = np.linspace(0, 6 * np.pi, 200)
        self.i, self.speed = 0.0, speed

        self.line, = self.ax.plot(self.x, np.sin(self.x), animated=True)
        self.ax.set_title('Try resizing the figure window')

        self.fig.canvas.mpl_connect('draw_event', self.update_background)
        self.t = self.fig.canvas.new_timer(interval, [(self.update, [], {})])
        self.t.start()

    def update_background(self, event):
        self._background = self.fig.canvas.copy_from_bbox(self.ax.bbox)

    def update(self):
        self.fig.canvas.restore_region(self._background)

        self.line.set_ydata(np.sin(self.i * self.speed + self.x))
        self.ax.draw_artist(self.line)
        self.i += 1

        self.fig.canvas.blit(self.ax.bbox)

    def show(self):
        plt.show()

AnimatedSinWave().show()

Note: For various reasons, you'll have some odd things happen on the OSX and qt*Agg backends. If the background is black when the window first pops up, move or focus the window, and it should fix itself.

At any rate, without the animated flag (or the newer animation framework), that example becomes much more complex.