@@ -305,12 +305,14 @@ def grab_frame(self, **savefig_kwargs):
305305 # frame format and dpi.
306306 self .fig .savefig (self ._frame_sink (), format = self .frame_format ,
307307 dpi = self .dpi , ** savefig_kwargs )
308- except RuntimeError :
308+ except ( RuntimeError , IOError ) as e :
309309 out , err = self ._proc .communicate ()
310310 verbose .report ('MovieWriter -- Error '
311311 'running proc:\n %s\n %s' % (out ,
312312 err ), level = 'helpful' )
313- raise
313+ raise IOError ('Error saving animation to file (cause: {0}) '
314+ 'Stdout: {1} StdError: {2}. It may help to re-run '
315+ 'with --verbose-debug.' .format (e , out , err ))
314316
315317 def _frame_sink (self ):
316318 'Returns the place to which frames should be written.'
@@ -787,13 +789,28 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
787789 'mencoder'. If nothing is passed, the value of the rcparam
788790 `animation.writer` is used.
789791
792+ *dpi* controls the dots per inch for the movie frames. This combined
793+ with the figure's size in inches controls the size of the movie.
794+
795+ *savefig_kwargs* is a dictionary containing keyword arguments to be
796+ passed on to the 'savefig' command which is called repeatedly to save
797+ the individual frames. This can be used to set tight bounding boxes,
798+ for example.
799+
800+ *extra_anim* is a list of additional `Animation` objects that should
801+ be included in the saved movie file. These need to be from the same
802+ `matplotlib.Figure` instance. Also, animation frames will just be
803+ simply combined, so there should be a 1:1 correspondence between
804+ the frames from the different animations.
805+
806+ These remaining arguments are used to construct a :class:`MovieWriter`
807+ instance when necessary and are only considered valid if *writer* is
808+ not a :class:`MovieWriter` instance.
809+
790810 *fps* is the frames per second in the movie. Defaults to None,
791811 which will use the animation's specified interval to set the frames
792812 per second.
793813
794- *dpi* controls the dots per inch for the movie frames. This combined
795- with the figure's size in inches controls the size of the movie.
796-
797814 *codec* is the video codec to be used. Not all codecs are supported
798815 by a given :class:`MovieWriter`. If none is given, this defaults to the
799816 value specified by the rcparam `animation.codec`.
@@ -811,18 +828,21 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
811828 *metadata* is a dictionary of keys and values for metadata to include
812829 in the output file. Some keys that may be of use include:
813830 title, artist, genre, subject, copyright, srcform, comment.
814-
815- *extra_anim* is a list of additional `Animation` objects that should
816- be included in the saved movie file. These need to be from the same
817- `matplotlib.Figure` instance. Also, animation frames will just be
818- simply combined, so there should be a 1:1 correspondence between
819- the frames from the different animations.
820-
821- *savefig_kwargs* is a dictionary containing keyword arguments to be
822- passed on to the 'savefig' command which is called repeatedly to save
823- the individual frames. This can be used to set tight bounding boxes,
824- for example.
825831 '''
832+ # If the writer is None, use the rc param to find the name of the one
833+ # to use
834+ if writer is None :
835+ writer = rcParams ['animation.writer' ]
836+ elif (not is_string_like (writer ) and
837+ any (arg is not None
838+ for arg in (fps , codec , bitrate , extra_args , metadata ))):
839+ raise RuntimeError ('Passing in values for arguments for arguments '
840+ 'fps, codec, bitrate, extra_args, or metadata '
841+ 'is not supported when writer is an existing '
842+ 'MovieWriter instance. These should instead be '
843+ 'passed as arguments when creating the '
844+ 'MovieWriter instance.' )
845+
826846 if savefig_kwargs is None :
827847 savefig_kwargs = {}
828848
@@ -838,11 +858,6 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
838858 # Convert interval in ms to frames per second
839859 fps = 1000. / self ._interval
840860
841- # If the writer is None, use the rc param to find the name of the one
842- # to use
843- if writer is None :
844- writer = rcParams ['animation.writer' ]
845-
846861 # Re-use the savefig DPI for ours if none is given
847862 if dpi is None :
848863 dpi = rcParams ['savefig.dpi' ]
0 commit comments