@@ -234,12 +234,14 @@ def grab_frame(self, **savefig_kwargs):
234234 # frame format and dpi.
235235 self .fig .savefig (self ._frame_sink (), format = self .frame_format ,
236236 dpi = self .dpi , ** savefig_kwargs )
237- except RuntimeError :
237+ except ( RuntimeError , IOError ) as e :
238238 out , err = self ._proc .communicate ()
239239 verbose .report ('MovieWriter -- Error '
240240 'running proc:\n %s\n %s' % (out ,
241241 err ), level = 'helpful' )
242- raise
242+ raise IOError ('Error saving animation to file (cause: {0}) '
243+ 'Stdout: {1} StdError: {2}. It may help to re-run '
244+ 'with --verbose-debug.' .format (e , out , err ))
243245
244246 def _frame_sink (self ):
245247 'Returns the place to which frames should be written.'
@@ -684,13 +686,28 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
684686 If nothing is passed, the value of the rcparam `animation.writer` is
685687 used.
686688
689+ *dpi* controls the dots per inch for the movie frames. This combined
690+ with the figure's size in inches controls the size of the movie.
691+
692+ *savefig_kwargs* is a dictionary containing keyword arguments to be
693+ passed on to the 'savefig' command which is called repeatedly to save
694+ the individual frames. This can be used to set tight bounding boxes,
695+ for example.
696+
697+ *extra_anim* is a list of additional `Animation` objects that should
698+ be included in the saved movie file. These need to be from the same
699+ `matplotlib.Figure` instance. Also, animation frames will just be
700+ simply combined, so there should be a 1:1 correspondence between
701+ the frames from the different animations.
702+
703+ These remaining arguments are used to construct a :class:`MovieWriter`
704+ instance when necessary and are only considered valid if *writer* is
705+ not a :class:`MovieWriter` instance.
706+
687707 *fps* is the frames per second in the movie. Defaults to None,
688708 which will use the animation's specified interval to set the frames
689709 per second.
690710
691- *dpi* controls the dots per inch for the movie frames. This combined
692- with the figure's size in inches controls the size of the movie.
693-
694711 *codec* is the video codec to be used. Not all codecs are supported
695712 by a given :class:`MovieWriter`. If none is given, this defaults to the
696713 value specified by the rcparam `animation.codec`.
@@ -708,18 +725,21 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
708725 *metadata* is a dictionary of keys and values for metadata to include
709726 in the output file. Some keys that may be of use include:
710727 title, artist, genre, subject, copyright, srcform, comment.
711-
712- *extra_anim* is a list of additional `Animation` objects that should
713- be included in the saved movie file. These need to be from the same
714- `matplotlib.Figure` instance. Also, animation frames will just be
715- simply combined, so there should be a 1:1 correspondence between
716- the frames from the different animations.
717-
718- *savefig_kwargs* is a dictionary containing keyword arguments to be
719- passed on to the 'savefig' command which is called repeatedly to save
720- the individual frames. This can be used to set tight bounding boxes,
721- for example.
722728 '''
729+ # If the writer is None, use the rc param to find the name of the one
730+ # to use
731+ if writer is None :
732+ writer = rcParams ['animation.writer' ]
733+ elif (not is_string_like (writer ) and
734+ any (arg is not None
735+ for arg in (fps , codec , bitrate , extra_args , metadata ))):
736+ raise RuntimeError ('Passing in values for arguments for arguments '
737+ 'fps, codec, bitrate, extra_args, or metadata '
738+ 'is not supported when writer is an existing '
739+ 'MovieWriter instance. These should instead be '
740+ 'passed as arguments when creating the '
741+ 'MovieWriter instance.' )
742+
723743 if savefig_kwargs is None :
724744 savefig_kwargs = {}
725745
@@ -735,11 +755,6 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
735755 # Convert interval in ms to frames per second
736756 fps = 1000. / self ._interval
737757
738- # If the writer is None, use the rc param to find the name of the one
739- # to use
740- if writer is None :
741- writer = rcParams ['animation.writer' ]
742-
743758 # Re-use the savefig DPI for ours if none is given
744759 if dpi is None :
745760 dpi = rcParams ['savefig.dpi' ]
0 commit comments