scitools.easyviz.movie

class scitools.easyviz.movie.MovieEncoder(input_files, **kwargs)

Bases: object

Class for turning a series of filenames with frames in a movie into a movie file.

Methods

encode()

Encode a series of images to a movie.

__class__

alias of type

__delattr__

x.__delattr__(‘name’) <==> del x.name

__dict__ = dict_proxy({'__module__': 'scitools.easyviz.movie', '_get_aspect_ratio': <function _get_aspect_ratio at 0x3e66050>, '_ppmtompeg': <function _mpeg_encode at 0x3e5ce60>, '_any2any': <function _any2any at 0x3e5cf50>, '__dict__': <attribute '__dict__' of 'MovieEncoder' objects>, '_mpeg_encode': <function _mpeg_encode at 0x3e5ce60>, '_ffmpeg': <function _ffmpeg at 0x3e5cde8>, '_convert': <function _convert at 0x3e5ccf8>, '__weakref__': <attribute '__weakref__' of 'MovieEncoder' objects>, '__init__': <function __init__ at 0x3e5cc08>, '_legal_file_types': ['png', 'gif', 'jpg', 'ps', 'eps', 'bmp', 'tif', 'tga', 'pnm'], '_legal_encoders': ['convert', 'mencoder', 'ffmpeg', 'mpeg_encode', 'ppmtompeg', 'mpeg2enc', 'html'], '_local_prop': {'output_file': None, 'qmax': 31, 'gop_size': None, 'pqscale': None, 'vbitrate': None, 'qmin': 2, 'aspect': None, 'qscale': None, 'pattern': 'I', 'preferred_package': 'ImageMagick', 'overwrite_output': True, 'vbuffer': None, 'force_conversion': False, 'fps': 25, 'size': None, 'bqscale': None, 'iqscale': None, 'encoder': None, 'input_files': None, 'vcodec': 'mpeg4', 'quiet': False, 'cleanup': True}, '_mencoder': <function _mencoder at 0x3e5cd70>, '_get_size': <function _get_size at 0x3e660c8>, '_mpeg2enc': <function _mpeg2enc at 0x3e5ced8>, 'encode': <function encode at 0x3e5cc80>, '__doc__': '\n Class for turning a series of filenames with frames in a movie into\n a movie file.\n '})

__format__()

default object formatter

__getattribute__

x.__getattribute__(‘name’) <==> x.name

__hash__() <==> hash(x)

__init__(input_files, **kwargs)

__module__ = 'scitools.easyviz.movie'

static __new__(S, ...) → a new object with type S, a subtype of T

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__() <==> repr(x)

__setattr__

x.__setattr__(‘name’, value) <==> x.name = value

__sizeof__() → int

size of object in memory, in bytes

__str__() <==> str(x)

static __subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__

list of weak references to the object (if defined)

encode()

Encode a series of images to a movie.

scitools.easyviz.movie.html_movie(plotfiles, interval_ms=300, width=800, height=600, casename='movie')

Takes a list plotfiles which should be for example of the form:

[‘frame00.png’, ‘frame01.png’, ... ]

where each string should be the name of an image file and they should be in the proper order for viewing as an animation.

The result is html text strings that incorporate javascript to loop through the plots one after another. The html text also features buttons for controlling the movie. The parameter iterval_ms is the time interval between loading successive images and is in milliseconds.

The width and height parameters do not seem to have any effect for reasons not understood.

The following strings are returned: header, javascript code, form with movie and buttons, and footer. Concatenating these strings and dumping to an html file yields a kind of movie file to be viewed in a browser. The images variable in the javascript code is unique for each movie, because it is annotated by the casename string, so several such javascript sections can be used in the same html file.

This function is based on code written by R.J. LeVeque, based on a template from Alan McIntyre.

scitools.easyviz.movie.movie(input_files, **kwargs)

Make a movie from a series of image files.

This function makes it very easy to create a movie file from a series of image files. Several different encoding tools can be used, such as an HTML file, MEncoder, FFmpeg, mpeg_encode, ppmtompeg (Netpbm), mpeg2enc (MJPEGTools), and convert (ImageMagick), to combine the image files together. The encoding tool will be chosen automatically among these if more than one is installed on the machine in question (unless it is specified as a keyword argument to the movie function).

Suppose we have some image files named image_0000.eps, image_0001.eps, image_0002.eps, ... Note that the zero-padding, obtained by the printf format 04d in this case, ensures that the files are listed in correct numeric order when using a wildcard notation like image_*.eps. We want to make a movie out of these files, where each file constitutes a frame in the movie. This task can be accomplished by the simple call:

movie('image_*.eps')

The result is a movie file with a default name such as movie.html, movie.avi, movie.mpeg, or movie.gif, depending on the encoding tool chosen by the movie function. The file resides in the current working directory. The movie function checks a list of encoders and chooses the first it finds installed on the computer.

Note: We strongly recommend to always clean up previously generated files for the frames in movies:

for f in glob.glob('image_*.eps'):
    os.remove(f)

Otherwise, there is a danger of mixing old and new files in the movie!

One can easily specify the name of the movie file and explicitly specify the encoder. For example, an animated GIF movie can be created by:

movie('image_*.eps', encoder='convert',
      output_file='../wave2D.gif')

The encoder here is the convert program from the ImageMagick suite of image manipulation tools. The resulting movie file will be named ‘wave2D.gif’ and placed in the parent directory.

Another convenient encoder is simply to make an HTML file that can play a series of image files:

movie('image_*.png', encoder='html',
      output_file='../wave2D.html')

Just load the output file into a web browser and play the movie.

If you want to create an MPEG movie by using the MEncoder tool, you can do this with the following command:

movie('image_*.eps', encoder='mencoder',
      output_file='/home/johannr/wave2D.mpeg',
      vcodec='mpeg2video', vbitrate=2400, qscale=4, fps=10)

Here, we have also specified the video codec to be mpeg2video, the video bitrate to be 2400 kbps, the quantization scale (quality) to be 4, and the number of frames per second to be 10.

Demo programs showing various use of the movie function can be found as the files movie_demo*.py files in the examples directory of the scitools source code tree.

Suitable movie players are vlc for MPEG and AVI formats, and animate for animated GIF files.

Below follows a more detailed description of the various arguments that are available in this function.

Required arguments:

input_files: Specifies the image files which will be used to make the movie. The argument must be given either as a string, e.g., ‘image_*.png’ or a list/tuple of strings, e.g., glob.glob(‘image_*.png’).

Notes:

• When using the FFmpeg or the Mpeg2enc tools, the image files should be given (if possible) as a string on the format ‘{1}%{2}d{3}’, where the name components are as follows:

  • {1} filename prefix (e.g. image_)
  • {2} counting placeholder (like in C, printf, e.g. 04)
  • {3} file extension (e.g. .png or .jpg)

  Example of a correct description of the input files is image_%04d.png. If the input files are not given on the correct format, there will automatically be made copies of these files which will then be renamed to the required filename format.

• MEncoder, FFmpeg, and Mpeg2enc supports only .jpg and .png image files. So, if the input files are on another format, there will automatically be made copies which in turn will be converted to the correct format.

Optional arguments:

output_file: Sets the name of the output movie. If not set, a default name like movie.avi, movie.mpeg, or movie.gif (depending on the output format) will be given.

Note: When using the convert tool to combine the images, the extension of the file name is used to determine the file format of the final movie. For example, if a name like movie.gif is given, the resulting movie will become an animated gif file. Other supported movie formats are MPEG (.mpg, .mpeg, or .m2v) and MNG (Multiple-image Network Graphics).

overwrite_output: If True, the file given in the output_file argument above will be overwritten without warning (if it already exists). The default is True.

encoder: Sets the encoder tool to be used. Currently the following encoders are supported: ‘html’, ‘mencoder’, ‘ffmpeg’, ‘mpeg_encode’, ‘ppmtompeg’ (from the Netpbm package), ‘mpeg2enc’ (from the MJPEGTools package), and ‘convert’ (from the ImageMagick package). Note: ‘ppmtompeg’ and ‘mpeg_encode’ is the same tool.

vbitrate: Sets the bit rate of the movie. The default is 800 kbps when using the FFmpeg and MEncoder encoders. For mpeg_encode, ppmtompeg, and mpeg2enc, this option is by default not specified. This option has no effect on the convert tool from ImageMagick.

vbuffer: Sets the video buffer size. The default is to use the current encoding tools default video buffer size. In some cases it might be necessary to push this up to 500K or more.

fps: Sets the number of frames per second for the final movie. The default is 25 fps.

Notes:

• The ‘mpeg_encode’, ‘ppmtompeg’, and ‘mpeg2enc’ tools only supports the following frame rates: 23.976, 24, 25, 29.97, 30, 50, 59.94, and 60 fps.
• Not all video codecs have support for arbitrary frame rates (e.g., ‘mpeg1video’ and ‘mpeg2video’).

vcodec: Sets the video codec to be used. Some of the possible codecs are:

• ‘mjpeg’ - Motion JPEG
• ‘ljpeg’ - Lossless JPEG
• ‘h263’ - H.263
• ‘h263p’ - H.263+
• ‘mpeg4’ - MPEG-4 (DivX 4/5)
• ‘msmpeg4’ - DivX 3
• ‘msmpeg4v2’ - DivX 3
• ‘msmpeg4v2’ - MS MPEG4v2
• ‘wmv1’ - Windows Media Video, version 1 (AKA WMV7)
• ‘wmv2’ - Windows Media Video, version 2 (AKA WMV8)
• ‘rv10’ - an old RealVideo codec
• ‘mpeg1video’ - MPEG-1 video
• ‘mpeg2video’ - MPEG-2 video
• ‘huffyuv’ - HuffYUV
• ‘ffvhuff’ - nonstandard 20% smaller HuffYUV using YV12
• ‘asv1’ - ASUS Video v1
• ‘asv2’ - ASUS Video v2
• ‘ffv1’ - FFmpeg’s lossless video codec

The default codec is ‘mpeg4’ for mencoder/ffmpeg and ‘mpeg1video’ for mpeg2enc.

Notes:

• Run ‘ffmpeg -formats’ for a longer list of available codecs.
• The mencoder tool can also use the ‘xvid’ codec.
• Only ‘mpeg1video’ and ‘mpeg2video’ are available when using the mpeg2enc tool.
• This option has no effect when using mpeg_encode, ppmtompeg, or convert as the encoding tool.

qscale: The quantization scale value (qscale) give a trade-off between quality and compression. A lower value means better quality but larger files. Larger values gives better compression, but worse quality. The qscale value must be an integer between 1 and 31. The default is to not set the qscale option.

Note: When using mpeg_encode or ppmtompeg it is possible to have different qscale values for I, P, and B frames (see the iqscale, pqscale, and bqscale options below).

qmin: Sets the minimum quantization scale value. Must be given as an integer between 1 and 31. The default is 2.

qmax: Sets the maximum quantization scale value. Must be given as an integer between 1 and 31. The default is 31.

iqscale: Sets the quantization scale value (see qscale) for I frames. This option only affects mpeg_encode and ppmtompeg. The default is to use the same value as in qscale. If qscale is not given, then 8 is the default value for iqscale.

pqscale: Same as iqscale, but for P frames. If qscale is not given, then 10 is the default value for pqscale.

bqscale: Same as iqscale, but for B frames. If qscale is not given, then 25 is the default value for bqscale.

pattern: Sets the pattern (sequence) of I, P, and B frames. The default pattern is ‘I’ which gives good quality (but worse compression). Another standard sequence is ‘IBBPBBPBBPBBPBB’. This option has only an effect when using mpeg_encode or ppmtompeg as the encoding tool.

size: Sets the size of the final movie. The size must be given as a tuple/list (e.g. (640,480)) or as a string. The format of the string must be ‘wxh’ (e.g. ‘320x240’), but the following abbreviations are also recognized:

• ‘sqcif’ - 128x96
• ‘qcif’ - 176x144
• ‘cif’ - 352x288
• ‘4cif’ - 704x576

The default is to use the same size as the input images.

aspect: Sets the aspect ratio of the movie (e.g. 4/3 or 16/9).

Notes:

• ‘mpeg_encode’ and ‘ppmtompeg’ only support the following aspect ratios: 1.0, 0.6735, 0.7031, 0.7615,0.8055, 0.8437, 0.8935, 0.9157, 0.9815, 1.0255, 1.0695, 1.0950, 1.1575, and 1.2015.
• ‘mpeg2enc’ only supports the following aspect ratios: 1.0, 1.33, 1.77, and 2.21.

preferred_package: Sets whether to prefer the Netpbm package or the ImageMagick package if both of them are installed. Must be given as a string, i.e, either ‘imagemagick’ (default) or ‘netpbm’.

Notes:

• If only one of the packages is installed, then that package will be used.
• If none of the packages are installed, then some operations might stop in lack of needed programs.

gop_size: Sets the number of frames in a group of pictures (GOP). The default is to use the chosen encoding tools default value.

quiet: If True, then the operations will run quietly and only complain on errors. The default is False.

cleanup: If True (default), all temporary files that are created during the execution of the movie command will be deleted.

force_conversion: Forces conversion of images. This is a hack that can be used if the encoding tool has problems reading the input image files. If this is set to True, the images will be converted even if they are in a format recognized by the encoding tool. The default is False.

Known issues:

• JPEG images created by the Vtk backend does not seem to work with the MEncoder and FFmpeg tools. This can be fixed by setting the force_conversion argument to True. This will force conversion of the JPEG files to PNG files which in turn should successfully create the movie.
• Aspect ratio in mpeg_encode does not seem to work.