Merge pull request #7208 from efiring/h264_default

tacaswell · web-flow · commit b1af0529102d · 2016-10-24T15:29:58.000-04:00
API: change dflt animation codec to h264
diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -216,6 +216,18 @@ Support for HiDPI (Retina) displays in the NbAgg and WebAgg backends
 The NbAgg and WebAgg backends will now use the full resolution of your
 high-pixel-density display.
 
+Change in the default animation codec
+-------------------------------------
+
+The default animation codec has been changed from ``mpeg4`` to ``h264``,
+which is more efficient. It can be set via the ``animation.codec`` rcParam.
+
+Deprecated support for mencoder in animation
+--------------------------------------------
+
+The use of mencoder for writing video files with mpl is problematic;
+switching to ffmpeg is strongly advised.  All support for mencoder
+will be removed in version 2.2.
 
 
 Previous Whats New
diff --git a/lib/matplotlib/animation.py b/lib/matplotlib/animation.py
@@ -36,7 +36,7 @@
 import contextlib
 import tempfile
 import warnings
-from matplotlib.cbook import iterable, is_string_like
+from matplotlib.cbook import iterable, is_string_like, deprecated
 from matplotlib.compat import subprocess
 from matplotlib import verbose
 from matplotlib import rcParams, rcParamsDefault, rc_context
@@ -60,6 +60,12 @@
 # how-to-encode-series-of-images-into-h264-using-x264-api-c-c )
 
 
+def adjusted_figsize(w, h, dpi, n):
+    wnew = int(w * dpi / n) * n / dpi
+    hnew = int(h * dpi / n) * n / dpi
+    return wnew, hnew
+
+
 # A registry for available MovieWriter classes
 class MovieWriterRegistry(object):
     def __init__(self):
@@ -134,10 +140,6 @@ class MovieWriter(object):
         The format used in writing frame data, defaults to 'rgba'
     '''
 
-    # Specifies whether the size of all frames need to be identical
-    # i.e. whether we can use savefig.bbox = 'tight'
-    frame_size_can_vary = False
-
     def __init__(self, fps=5, codec=None, bitrate=None, extra_args=None,
                  metadata=None):
         '''
@@ -189,8 +191,20 @@ def __init__(self, fps=5, codec=None, bitrate=None, extra_args=None,
     @property
     def frame_size(self):
         'A tuple (width,height) in pixels of a movie frame.'
-        width_inches, height_inches = self.fig.get_size_inches()
-        return width_inches * self.dpi, height_inches * self.dpi
+        w, h = self.fig.get_size_inches()
+        return int(w * self.dpi), int(h * self.dpi)
+
+    def _adjust_frame_size(self):
+        if self.codec == 'h264':
+            wo, ho = self.fig.get_size_inches()
+            w, h = adjusted_figsize(wo, ho, self.dpi, 2)
+            if not (wo, ho) == (w, h):
+                self.fig.set_size_inches(w, h, forward=True)
+                verbose.report('figure size (inches) has been adjusted '
+                               'from %s x %s to %s x %s' % (wo, ho, w, h),
+                               level='helpful')
+        verbose.report('frame size in pixels is %s x %s' % self.frame_size,
+                       level='debug')
 
     def setup(self, fig, outfile, dpi):
         '''
@@ -207,6 +221,7 @@ def setup(self, fig, outfile, dpi):
         self.outfile = outfile
         self.fig = fig
         self.dpi = dpi
+        self._adjust_frame_size()
 
         # Run here so that grab_frame() can write the data to a pipe. This
         # eliminates the need for temp files.
@@ -316,10 +331,6 @@ def isAvailable(cls):
 class FileMovieWriter(MovieWriter):
     '`MovieWriter` subclass that handles writing to a file.'
 
-    # In general, if frames are writen to files on disk, it's not important
-    # that they all be identically sized
-    frame_size_can_vary = True
-
     def __init__(self, *args, **kwargs):
         MovieWriter.__init__(self, *args, **kwargs)
         self.frame_format = rcParams['animation.frame_format']
@@ -345,6 +356,8 @@ def setup(self, fig, outfile, dpi, frame_prefix='_tmp', clear_temp=True):
         self.fig = fig
         self.outfile = outfile
         self.dpi = dpi
+        self._adjust_frame_size()
+
         self.clear_temp = clear_temp
         self.temp_prefix = frame_prefix
         self._frame_counter = 0  # used for generating sequential file names
@@ -500,7 +513,7 @@ class FFMpegFileWriter(FileMovieWriter, FFMpegBase):
     def _args(self):
         # Returns the command line parameters for subprocess to use
         # ffmpeg to create a movie using a collection of temp images
-        return [self.bin_path(), '-r', str(self.fps),
+        return [self.bin_path(),  # -r option is not needed before -i option
                 '-i', self._base_temp_name(),
                 '-vframes', str(self._frame_counter),
                 '-r', str(self.fps)] + self.output_args
@@ -560,9 +573,20 @@ def output_args(self):
         return args
 
 
-# Combine Mencoder options with pipe-based writing
+# The message must be a single line; internal newlines cause sphinx failure.
+mencoder_dep = ("Support for mencoder is only partially functional, "
+                "and will be removed entirely in 2.2. "
+                "Please use ffmpeg instead.")
+
+
 @writers.register('mencoder')
 class MencoderWriter(MovieWriter, MencoderBase):
+
+    @deprecated('2.0', message=mencoder_dep)
+    def __init__(self, *args, **kwargs):
+        with rc_context(rc={'animation.codec': 'mpeg4'}):
+            super(MencoderWriter, self).__init__(*args, **kwargs)
+
     def _args(self):
         # Returns the command line parameters for subprocess to use
         # mencoder to create a movie
@@ -577,6 +601,11 @@ def _args(self):
 class MencoderFileWriter(FileMovieWriter, MencoderBase):
     supported_formats = ['png', 'jpeg', 'tga', 'sgi']
 
+    @deprecated('2.0', message=mencoder_dep)
+    def __init__(self, *args, **kwargs):
+        with rc_context(rc={'animation.codec': 'mpeg4'}):
+            super(MencoderFileWriter, self).__init__(*args, **kwargs)
+
     def _args(self):
         # Returns the command line parameters for subprocess to use
         # mencoder to create a movie
@@ -788,7 +817,7 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
         elif (not is_string_like(writer) and
                 any(arg is not None
                     for arg in (fps, codec, bitrate, extra_args, metadata))):
-            raise RuntimeError('Passing in values for arguments for arguments '
+            raise RuntimeError('Passing in values for arguments '
                                'fps, codec, bitrate, extra_args, or metadata '
                                'is not supported when writer is an existing '
                                'MovieWriter instance. These should instead be '
@@ -844,26 +873,16 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
                                                         metadata=metadata)
                 except IndexError:
                     raise ValueError("Cannot save animation: no writers are "
-                                     "available. Please install mencoder or "
+                                     "available. Please install "
                                      "ffmpeg to save animations.")
 
         verbose.report('Animation.save using %s' % type(writer),
                        level='helpful')
 
-        # FIXME: Using 'bbox_inches' doesn't currently work with
-        # writers that pipe the data to the command because this
-        # requires a fixed frame size (see Ryan May's reply in this
-        # thread: [1]). Thus we drop the 'bbox_inches' argument if it
-        # exists in savefig_kwargs.
-        #
-        # [1] (http://matplotlib.1069221.n5.nabble.com/
-        # Animation-class-let-save-accept-kwargs-which-
-        # are-passed-on-to-savefig-td39627.html)
-        #
-        if 'bbox_inches' in savefig_kwargs and not writer.frame_size_can_vary:
+        if 'bbox_inches' in savefig_kwargs:
             warnings.warn("Warning: discarding the 'bbox_inches' argument in "
-                          "'savefig_kwargs' as it not supported by "
-                          "{0}).".format(writer.__class__.__name__))
+                          "'savefig_kwargs' as it may cause frame size "
+                          "to vary, which is inappropriate for animation.")
             savefig_kwargs.pop('bbox_inches')
 
         # Create a new sequence of frames for saved data. This is different
@@ -873,12 +892,10 @@ def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
         # since GUI widgets are gone. Either need to remove extra code to
         # allow for this non-existent use case or find a way to make it work.
         with rc_context():
-            # See above about bbox_inches savefig kwarg
-            if (not writer.frame_size_can_vary and
-                    rcParams['savefig.bbox'] == 'tight'):
-                verbose.report("Disabling savefig.bbox = 'tight', as it is "
-                               "not supported by "
-                               "{0}.".format(writer.__class__.__name__),
+            if (rcParams['savefig.bbox'] == 'tight'):
+                verbose.report("Disabling savefig.bbox = 'tight', as it "
+                               "may cause frame size to vary, which "
+                               "is inappropriate for animation.",
                                level='helpful')
                 rcParams['savefig.bbox'] = None
             with writer.saving(self._fig, filename, dpi):
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -1324,7 +1324,7 @@ def validate_animation_writer_path(p):
     # Animation settings
     'animation.html':         ['none', validate_movie_html_fmt],
     'animation.writer':       ['ffmpeg', validate_movie_writer],
-    'animation.codec':        ['mpeg4', six.text_type],
+    'animation.codec':        ['h264', six.text_type],
     'animation.bitrate':      [-1, validate_int],
     # Controls image format when frames are written to disk
     'animation.frame_format': ['png', validate_movie_frame_fmt],
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -597,7 +597,7 @@ backend      : $TEMPLATE_BACKEND
                                    # the IPython notebook. 'html5' uses
                                    # HTML5 video tag.
 #animation.writer : ffmpeg         # MovieWriter 'backend' to use
-#animation.codec : mpeg4           # Codec to use for writing movie
+#animation.codec : h264            # Codec to use for writing movie
 #animation.bitrate: -1             # Controls size/quality tradeoff for movie.
                                    # -1 implies let utility auto-determine
 #animation.frame_format: 'png'     # Controls frame format used by temp files
