diff --git a/doc/c_cpp_api.rst b/doc/c_cpp_api.rst
index 270e6455e657e19f64873067b556709bcbd857a7..88a6870aa92f65e77f30e7c3ab624f3b1b091845 100644
--- a/doc/c_cpp_api.rst
+++ b/doc/c_cpp_api.rst
@@ -68,6 +68,7 @@ Generic Functions
Returns ``0`` in case of failure, or a **new reference** to the tuple
described above in case of success.
+
Bob File Support
----------------
@@ -86,4 +87,120 @@ Bob File Support
A pointer to a file being read or written.
+.. cpp:type:: PyBobIoFileIteratorObject
+
+ The pythonic object representation for an iterator over a ``bob::io::File``
+ object.
+
+ .. code-block:: cpp
+
+ typedef struct {
+ PyObject_HEAD
+ PyBobIoFileObject* pyfile;
+ Py_ssize_t curpos;
+ } PyBobIoFileIteratorObject;
+
+ .. cpp:member:: PyBobIoFileObject* pyfile
+
+ A pointer to the pythonic representation of a file.
+
+ .. cpp:member:: Py_ssize_t curpos
+
+ The current position at the file being pointed to.
+
+
+Bob HDF5 Support
+----------------
+
+.. cpp:type:: PyBobIoHDF5FileObject
+
+ The pythonic object representation for a ``bob::io::HDF5File`` object.
+
+ .. code-block:: cpp
+
+ typedef struct {
+ PyObject_HEAD
+ boost::shared_ptr<bob::io::HDF5File> f;
+ } PyBobIoHDF5FileObject;
+
+ .. cpp:member:: boost::shared_ptr<bob::io::HDF5File> f
+
+ A pointer to a Bob object being used to read/write data into an HDF5
+ file.
+
+
+.. cpp:function:: int PyBobIoHDF5File_Check(PyObject* o)
+
+ Checks if the input object ``o`` is a ``PyBobIoHDF5FileObject``. Returns
+ ``1`` if it is, and ``0`` otherwise.
+
+
+.. cpp:function:: int PyBobIoHDF5File_Converter(PyObject* o, PyBobIoHDF5FileObject** a)
+
+ This function is meant to be used with :c:func:`PyArg_ParseTupleAndKeywords`
+ family of functions in the Python C-API. It checks the input object to be of
+ type ``PyBobIoHDF5FileObject`` and sets a **new reference** to it (in
+ ``*a``) if it is the case. Returns ``0`` in case of failure, ``1`` in case
+ of success.
+
+Bob VideoReader Support
+-----------------------
+
+.. note::
+
+ The video C-API (and Python) is only available if the package was compiled
+ with FFMPEG or LibAV support.
+
+.. cpp:type:: PyBobIoVideoReaderObject
+
+ The pythonic object representation for a ``bob::io::VideoReader`` object.
+
+ .. code-block:: cpp
+
+ typedef struct {
+ PyObject_HEAD
+ boost::shared_ptr<bob::io::VideoReader> v;
+ } PyBobIoVideoReaderObject;
+
+ .. cpp:member:: boost::shared_ptr<bob::io::VideoReader> v
+
+ A pointer to a Bob object being used to read the video contents
+
+.. cpp:type:: PyBobIoVideoReaderIteratorObject
+
+ The pythonic object representation for an iterator over a
+ ``bob::io::VideoReader`` object.
+
+ .. code-block:: cpp
+
+ typedef struct {
+ PyObject_HEAD
+ PyBobIoVideoReaderObject* pyreader;
+ boost::shared_ptr<bob::io::VideoReader::const_iterator> iter;
+ } PyBobIoFileIteratorObject;
+
+ .. cpp:member:: PyBobIoVideoReaderObject* pyreader
+
+ A pointer to the pythonic representation of the video reader.
+
+ .. cpp:member:: boost::shared_ptr<bob::io::VideoReader::const_iterator> iter
+
+ The current position at the file being pointed to, represented by a
+ formal iterator over the VideoReader.
+
+.. cpp:type:: PyBobIoVideoReaderObject
+
+ The pythonic object representation for a ``bob::io::VideoWriter`` object.
+
+ .. code-block:: cpp
+
+ typedef struct {
+ PyObject_HEAD
+ boost::shared_ptr<bob::io::VideoWriter> v;
+ } PyBobIoVideoWriterObject;
+
+ .. cpp:member:: boost::shared_ptr<bob::io::VideoWriter> v
+
+ A pointer to a Bob object being used to write contents to the video.
+
.. include:: links.rst
diff --git a/doc/conf.py b/doc/conf.py
index 1450d0a8ca967bbe1d540d46313911487276aeea..df9e2e3de93443b24260968f54519b64fb70bb05 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -244,6 +244,7 @@ latex_logo = ''
# Included after all input documents
rst_epilog = """
.. |version| replace:: %s
+.. |project| replace:: Bob
""" % (version,)
# -- Options for manual page output --------------------------------------------
diff --git a/doc/index.rst b/doc/index.rst
index 70de9db71e669d4cb9559950247865356c459db8..e20b85fd521fd3aa80673409c0d8213ae395a72a 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -3,30 +3,14 @@
.. Mon 4 Nov 20:58:04 2013 CET
..
.. Copyright (C) 2011-2013 Idiap Research Institute, Martigny, Switzerland
-..
-.. This program is free software: you can redistribute it and/or modify
-.. it under the terms of the GNU General Public License as published by
-.. the Free Software Foundation, version 3 of the License.
-..
-.. This program is distributed in the hope that it will be useful,
-.. but WITHOUT ANY WARRANTY; without even the implied warranty of
-.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-.. GNU General Public License for more details.
-..
-.. You should have received a copy of the GNU General Public License
-.. along with this program. If not, see <http://www.gnu.org/licenses/>.
-
-.. Master file, created by sphinx-quickstart on Mon Mar 21 18:07:34 2011. You
- can adapt this file completely to your liking, but it should at least contain
- the root `toctree` directive.
-=====================
- Bob's Core Routines
-=====================
+====================
+ Bob's I/O Routines
+====================
This module contains base functionality from Bob bound to Python, available in
-the C++ counter-part ``bob::core``. It includes basic conversion routines,
-random number generation and central logging facilities.
+the C++ counter-part ``bob::io``. It includes input and output operations to
+and from files.
Reference
---------
@@ -35,6 +19,7 @@ Reference
:maxdepth: 2
py_api
+ video
c_cpp_api
Indices and tables
diff --git a/doc/links.rst b/doc/links.rst
index 2a4f8df5169043f427831d3226f6dc722c097e69..8709c8706d9601abde3c8cf5dd0b069306e94ede 100644
--- a/doc/links.rst
+++ b/doc/links.rst
@@ -20,15 +20,61 @@
.. Place here references to all citations in lower case
+.. _argparse: http://code.google.com/p/argparse/
+.. _blitz++: http://www.oonumerics.org/blitz
+.. _bob's idiap guide: http://github.com/idiap/bob/wiki/Using-Bob-at-Idiap
+.. _bob's website: https://www.idiap.ch/software/bob
.. _boost: http://www.boost.org
+.. _buildbot: http://trac.buildbot.net
.. _buildout: http://pypi.python.org/pypi/zc.buildout/
.. _c++: http://www2.research.att.com/~bs/C++.html
+.. _cmake: http://www.cmake.org
+.. _doxygen: http://www.doxygen.org
+.. _dvipng: http://savannah.nongnu.org/projects/dvipng/
+.. _ffmpeg: http://ffmpeg.org
+.. _libav: http://libav.org
+.. _fftw: http://www.fftw.org/
+.. _fink: http://www.finkproject.org
+.. _git: http://git-scm.com/
+.. _github: http://github.com/
+.. _google perftools: http://code.google.com/p/google-perftools
+.. _hdf5: http://www.hdfgroup.org/HDF5
+.. _idiap: http://www.idiap.ch
+.. _ipython: http://ipython.scipy.org
+.. _lapack: http://www.netlib.org/lapack
+.. _latex: http://www.latex-project.org/
+.. _libjpeg: http://libjpeg.sourceforge.net/
+.. _libnetpbm: http://netpbm.sourceforge.net/doc/libnetpbm.html
+.. _libpng: http://libpng.org/pub/png/libpng.html
+.. _libsvm: http://www.csie.ntu.edu.tw/~cjlin/libsvm/
+.. _libtiff: http://www.remotesensing.org/libtiff/
+.. _giflib: http://giflib.sourceforge.net/
+.. _macports installation instructions: http://www.macports.org/install.php
+.. _macports: http://www.macports.org
+.. _matio: http://matio.sourceforge.net
+.. _matlab: http://www.mathworks.ch/products/matlab/
+.. _matplotlib: http://matplotlib.sourceforge.net
.. _numpy: http://numpy.scipy.org
.. _nose: http://nose.readthedocs.org
+.. _opencv: http://opencv.willowgarage.com/
+.. _pil: http://www.pythonware.com/products/pil/
+.. _pillow: https://pypi.python.org/pypi/Pillow/
+.. _python: http://www.python.org
.. _pypi: http://pypi.python.org
+.. _qt4: http://qt.nokia.com/
+.. _satellite packages: https://github.com/idiap/bob/wiki/Satellite-Packages
.. _scipy: http://www.scipy.org
.. _setuptools: http://trac.edgewall.org/wiki/setuptools
.. _sphinx: http://sphinx.pocoo.org
+.. _sqlalchemy: http://www.sqlalchemy.org/
+.. _sqlite: http://www.sqlite.org/
+.. _submit a new bug report: https://github.com/idiap/bob/issues
+.. _torch 3 vision: http://torch3vision.idiap.ch
+.. _torch 3: http://www.torch.ch
+.. _torch 5: http://torch5.sourceforge.net
+.. _torch: https://github.com/andresy/torch
+.. _vlfeat launchpad webpage: https://launchpad.net/~gezakovacs/+archive/vlfeat
+.. _vlfeat: http://www.vlfeat.org/
.. Place here references to licenses
diff --git a/doc/py_api.rst b/doc/py_api.rst
index d375d9e6f74d342547e3996be9493e86aed1a9be..d29149c641e8a39ce26d4c16ef64863092771ef7 100644
--- a/doc/py_api.rst
+++ b/doc/py_api.rst
@@ -11,14 +11,500 @@
User Guide
============
-Basic I/O
----------
+This section gives an overview of the operations for storing and retrieving the
+basic data structures in |project|, such as `NumPy`_ arrays. |project| uses
+`HDF5`_ format for storing binary coded data. Using the |project| support for
+`HDF5`_, it is very simple to import and export data.
+
+`HDF5`_ uses a neat descriptive language for representing the data in the HDF5
+files, called Data Description Language (`DDL`_).
+
+To perform the functionalities given in this section, you should have `NumPy`_
+and |project| loaded into the `Python`_ environment.
+
+.. testsetup:: *
+
+ import numpy
+ import xbob.io
+ import tempfile
+ import os
+
+ current_directory = os.path.realpath(os.curdir)
+ temp_dir = tempfile.mkdtemp(prefix='bob_doctest_')
+ os.chdir(temp_dir)
+
+HDF5 standard utilities
+-----------------------
+
+Before explaining the basics of reading and writing to `HDF5`_ files, it is
+important to list some `HDF5`_ standard utilities for checking the content of
+an `HDF5`_ file. These are supplied by the `HDF5`_ project.
+
+``h5dump``
+ Dumps the content of the file using the DDL.
+
+``h5ls``
+ Lists the content of the file using DDL, but does not show the data.
+
+``h5diff``
+ Finds the differences between HDF5 files.
+
+I/O operations using the class `xbob.io.HDF5File`
+-------------------------------------------------
+
+Writing operations
+------------------
+
+Let's take a look at how to write simple scalar data such as integers or
+floats.
+
+.. doctest::
+
+ >>> an_integer = 5
+ >>> a_float = 3.1416
+ >>> f = xbob.io.HDF5File('testfile1.hdf5', 'w')
+ >>> f.set('my_integer', an_integer)
+ >>> f.set('my_float', a_float)
+ >>> del f
+
+If after this you use the **h5dump** utility on the file ``testfile1.hdf5``,
+you will verify that the file now contains:
+
+.. code-block:: none
+
+ HDF5 "testfile1.hdf5" {
+ GROUP "/" {
+ DATASET "my_float" {
+ DATATYPE H5T_IEEE_F64LE
+ DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
+ DATA {
+ (0): 3.1416
+ }
+ }
+ DATASET "my_integer" {
+ DATATYPE H5T_STD_I32LE
+ DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
+ DATA {
+ (0): 5
+ }
+ }
+ }
+ }
+
+.. note::
+
+ In |project|, when you open a HDF5 file, you can choose one of the following
+ options:
+
+ **'r'** Open the file in reading mode; writing operations will fail (this is the default).
+
+ **'a'** Open the file in reading and writing mode with appending.
+
+ **'w'** Open the file in reading and writing mode, but truncate it.
+
+ **'x'** Read/write/append with exclusive access.
+
+The dump shows that there are two datasets inside a group named ``/`` in the
+file. HDF5 groups are like file system directories. They create namespaces for
+the data. In the root group (or directory), you will find the two variables,
+named as you set them to be. The variable names are the complete path to the
+location where they live. You could write a new variable in the same file but
+in a different directory like this:
+
+.. doctest::
+
+ >>> f = xbob.io.HDF5File('testfile1.hdf5', 'a')
+ >>> f.create_group('/test')
+ >>> f.set('/test/my_float', numpy.float32(6.28))
+ >>> del f
+
+Line 1 opens the file for reading and writing, but without truncating it. This
+will allow you to access the file contents. Next, the directory ``/test`` is
+created and a new variable is written inside the subdirectory. As you can
+verify, **for simple scalars**, you can also force the storage type. Where
+normally one would have a 64-bit real value, you can impose that this variable
+is saved as a 32-bit real value. You can verify the dump correctness with
+``h5dump``:
+
+.. code-block:: none
+
+ GROUP "/" {
+ ...
+ GROUP "test" {
+ DATASET "my_float" {
+ DATATYPE H5T_IEEE_F32LE
+ DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
+ DATA {
+ (0): 6.28
+ }
+ }
+ }
+ }
+
+Notice the subdirectory ``test`` has been created and inside it a floating
+point number has been stored. Such a float point number has a 32-bit precision
+as it was defined.
+
+.. note::
+
+ If you need to place lots of variables in a subfolder, it may be better to
+ setup the prefix folder before starting the writing operations on the
+ :py:class:`xbob.io.HDF5File` object. You can do this using the method
+ :py:meth:`HDF5File.cd`. Look up its help for more information and usage
+ instructions.
+
+Writing arrays is a little simpler as the :py:class:`numpy.ndarray` objects
+encode all the type information we need to write and read them correctly. Here
+is an example:
+
+.. doctest::
+
+ >>> A = numpy.array(range(4), 'int8').reshape(2,2)
+ >>> f = xbob.io.HDF5File('testfile1.hdf5', 'a')
+ >>> f.set('my_array', A)
+ >>> del f
+
+The result of running ``h5dump`` on the file ``testfile3.hdf5`` should be:
+
+.. code-block:: none
+
+ ...
+ DATASET "my_array" {
+ DATATYPE H5T_STD_I8LE
+ DATASPACE SIMPLE { ( 2, 2 ) / ( 2, 2 ) }
+ DATA {
+ (0,0): 0, 1,
+ (1,0): 2, 3
+ }
+ }
+ ...
+
+You don't need to limit yourself to single variables, you can also save lists
+of scalars and arrays using the function :py:meth:`xbob.io.HDF5.append` instead
+of :py:meth:`xbob.io.HDF5.set`.
+
+Reading operations
+------------------
+
+Reading data from a file that you just wrote to is just as easy. For this task
+you should use :py:meth:`xbob.io.HDF5File.read`. The read method will read all
+the contents of the variable pointed to by the given path. This is the normal
+way to read a variable you have written with :py:meth:`xbob.io.HDF5File.set`. If
+you decided to create a list of scalar or arrays, the way to read that up would
+be using :py:meth:`xbob.io.HDF5File.lread` instead. Here is an example:
+
+.. doctest::
+
+ >>> f = xbob.io.HDF5File('testfile1.hdf5') #read only
+ >>> f.read('my_integer') #reads integer
+ 5
+ >>> print(f.read('my_array')) # reads the array
+ [[0 1]
+ [2 3]]
+ >>> del f
+
+Now let's look at an example where we have used
+:py:meth:`xbob.io.HDF5File.append` instead of :py:meth:`xbob.io.HDF5File.set`
+to write data to a file. That is normally the case when you write lists of
+variables to a dataset.
+
+.. doctest::
+
+ >>> f = xbob.io.HDF5File('testfile2.hdf5', 'w')
+ >>> f.append('arrayset', numpy.array(range(10), 'float64'))
+ >>> f.append('arrayset', 2*numpy.array(range(10), 'float64'))
+ >>> f.append('arrayset', 3*numpy.array(range(10), 'float64'))
+ >>> print(f.lread('arrayset', 0))
+ [ 0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]
+ >>> print(f.lread('arrayset', 2))
+ [ 0. 3. 6. 9. 12. 15. 18. 21. 24. 27.]
+ >>> del f
+
+This is what the ``h5dump`` of the file would look like:
+
+.. code-block:: none
+
+ HDF5 "testfile4.hdf5" {
+ GROUP "/" {
+ DATASET "arrayset" {
+ DATATYPE H5T_IEEE_F64LE
+ DATASPACE SIMPLE { ( 3, 10 ) / ( H5S_UNLIMITED, 10 ) }
+ DATA {
+ (0,0): 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
+ (1,0): 0, 2, 4, 6, 8, 10, 12, 14, 16, 18,
+ (2,0): 0, 3, 6, 9, 12, 15, 18, 21, 24, 27
+ }
+ }
+ }
+ }
+
+Notice that the expansion limits for the first dimension have been correctly
+set by |project| so you can insert an *unlimited* number of 1D float vectors.
+Of course, you can also read the whole contents of the arrayset in a single
+shot:
+
+.. doctest::
+
+ >>> f = xbob.io.HDF5File('testfile2.hdf5')
+ >>> print(f.read('arrayset'))
+ [[ 0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]
+ [ 0. 2. 4. 6. 8. 10. 12. 14. 16. 18.]
+ [ 0. 3. 6. 9. 12. 15. 18. 21. 24. 27.]]
+
+As you can see, the only difference between :py:meth:`xbob.io.HDF5File.read`
+and :py:meth:`xbob.io.HDF5File.lread` is on how |project| considers the
+available data (as a single array with N dimensions or as a set of arrays with
+N-1 dimensions). In the first example, you would have also been able to read
+the variable `my_array` as an arrayset using :py:meth:`xbob.io.HDF5File.lread`
+instead of :py:meth:`xbob.io.HDF5File.read`. In this case, each position
+readout would return a 1D uint8 array instead of a 2D array.
+
+Array interfaces
+----------------
+
+What we have shown so far is the generic API to read and write data using HDF5.
+You will use it when you want to import or export data from |project| into
+other software frameworks, debug your data or just implement your own classes
+that can serialize and de-serialize from HDF5 file containers. In |project|,
+most of the time you will be working with :py:class:`numpy.ndarrays`\s. In
+special situations though, you may be asked to handle
+:py:class:`xbob.io.File`\s. :py:class:`xbob.io.File` objects create a
+transparent connection between C++ (`Blitz++`_) / Python (`NumPy`_) arrays and
+file access. You specify the filename from which you want to input data and
+the :py:class:`xbob.io.File` object decides what is the best codec to be used
+(from the extension) and how to read the data back into your array.
+
+To create an :py:class:`xbob.io.File` from a file path, just do the following:
+
+.. doctest::
+
+ >>> a = xbob.io.File('testfile2.hdf5', 'r')
+ >>> a.filename
+ 'testfile2.hdf5'
+
+:py:class:`xbob.io.File`\s simulate containers for :py:class:`numpy.ndarray`\s,
+transparently accessing the file data when requested. Note, however, that when
+you instantiate an :py:class:`xbob.io.File` it does **not** load the file
+contents into memory. It waits until you emit another explicit instruction to
+do so. We do this with the :py:meth:`xbob.io.File.read` method:
+
+.. doctest::
+
+ >>> array = a.read()
+ >>> array
+ array([[ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.],
+ [ 0., 2., 4., 6., 8., 10., 12., 14., 16., 18.],
+ [ 0., 3., 6., 9., 12., 15., 18., 21., 24., 27.]])
+
+Every time you say :py:meth:`xbob.io.File.read`, the file contents will be read
+from the file and into a new array.
+
+Saving arrays to the :py:class:`xbob.io.File` is as easy, just call the
+:py:meth:`xbob.io.File.write` method:
+
+.. doctest::
+
+ >>> f = xbob.io.File('copy1.hdf5', 'w')
+ >>> f.write(a)
+
+Numpy ndarray shortcuts
+-----------------------
+
+To just load an :py:class:`numpy.ndarray` in memory, you can use a short cut
+that lives at :py:func:`xbob.io.load`. With it, you don't have to go through
+the :py:class:`xbob.io.File` container:
+
+.. doctest::
+
+ >>> t = xbob.io.load('testfile2.hdf5')
+ >>> t
+ array([[ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.],
+ [ 0., 2., 4., 6., 8., 10., 12., 14., 16., 18.],
+ [ 0., 3., 6., 9., 12., 15., 18., 21., 24., 27.]])
+
+You can also directly save :py:class:`numpy.ndarray`\s without going
+through the :py:class:`xbob.io.Array` container:
+
+.. doctest::
+
+ >>> xbob.io.save(t, 'copy2.hdf5')
+
+.. note::
+
+ Under the hood, we still use the :py:class:`xbob.io.File` API to execute
+ the read and write operations. Have a look at the manual section for
+ :py:mod:`xbob.io` for more details and other shortcuts available.
+
+Reading and writing images
+--------------------------
+
+|project| provides support to load and save data from many different file types
+including Matlab ``.mat`` files, various image file types and video data. File
+types and specific serialization and de-serialization is switched automatically
+using filename extensions. Knowing this, saving an array in a different format
+is just a matter of choosing the right extension. This is illustrated in the
+following example, where an image generated randomly using the method `NumPy`
+:py:meth:`numpy.random.random_integers`, is saved in JPEG format. The image
+must be of type uint8 or uint16.
+
+.. doctest::
+
+ >>> my_image = numpy.random.random_integers(0,255,(3,256,256))
+ >>> xbob.io.save(my_image.astype('uint8'), 'testimage.jpg') # saving the image in jpeg format
+ >>> my_image_copy = xbob.io.load('testimage.jpg')
+
+.. tip::
+
+ To find out about which formats and extensions are supported in a given
+ installation of |project|, just call ``bob_config.py`` on your prompt. It
+ will print a list of compiled-in software and supported extensions.
+
+The loaded image files can be 3D arrays (for RGB format) or 2D arrays (for
+greyscale) of type ``uint8`` or ``uint16``.
+
+Dealing with videos
+-------------------
+
+|project| has support for dealing with videos in an equivalent way to dealing
+with images:
+
+.. doctest::
+
+ >>> my_video = numpy.random.random_integers(0,255,(30,3,256,256))
+ >>> xbob.io.save(my_video.astype('uint8'), 'testvideo.avi') # saving the video avi format with a default codec
+ >>> my_video_copy = xbob.io.load('testvideo.avi')
+
+Video reading and writing is performed using an `FFmpeg`_ (or `libav`_ if
+`FFmpeg`_ is not available) bridge. |project|'s :py:meth:`xbob.io.save` method
+will allow you to choose the output format with the same extension mechanism as
+mentioned earlier. `FFmpeg`_ will then choose a default codec for the format
+and perform encoding. The output file can be as easily loaded using
+:py:meth:`xbob.io.load`.
+
+For finer control over the loading, saving, format and codecs used for a
+specific encoding or decoding operation, you must directly use either
+:py:class:`xbob.io.VideoReader` or :py:class:`xbob.io.VideoWriter` classes. For
+example, it is possible to use :py:class:`xbob.io.VideoReader` to read videos
+frame by frame and avoid overloading your machine's memory. In the following
+example you can see how to create a video, save it using the class
+:py:class:`xbob.io.VideoWriter` and load it again using the class
+:py:class:`xbob.io.VideoReader`. The created video will have 30 frames
+generated randomly.
+
+.. note::
+
+ Due to `FFmpeg`_ constrains, the width and height of the video need to be
+ multiples of two.
+
+.. doctest::
+
+ >>> width = 50; height = 50;
+ >>> framerate = 24
+ >>> outv = xbob.io.VideoWriter('testvideo.avi', height, width, framerate, codec='mpeg1video') # output video
+ >>> for i in range(0, 30):
+ ... newframe = (numpy.random.random_integers(0,255,(3,height,width)))
+ ... outv.append(newframe.astype('uint8'))
+ >>> outv.close()
+ >>> input = xbob.io.VideoReader('testvideo.avi')
+ >>> input.number_of_frames
+ 30
+ >>> inv = input.load()
+ >>> inv.shape
+ (30, 3, 50, 50)
+ >>> type(inv)
+ <... 'numpy.ndarray'>
+
+Videos in |project| are represented as sequences of colored images, i.e. 4D
+arrays of type ``uint8``. All the extensions and formats for videos supported
+in version of |project| installed on your machine can be listed using the
+|project|'s utility ``bob_config.py``.
+
+.. testcleanup:: *
+
+ import shutil
+ os.chdir(current_directory)
+ shutil.rmtree(temp_dir)
+
+.. warning::
+
+ Please read :doc:`video` for details on choosing codecs and formats that are
+ adequate to your application, as well as drawbacks and pitfalls with video
+ encoding and decoding.
+
+Loading and saving Matlab data
+------------------------------
+
+An alternative for saving data in ``.mat`` files using :py:meth:`xbob.io.save`,
+would be to save them as a `HDF5`_ file which then can be easily read in
+Matlab. Similarly, instead of having to read ``.mat`` files using
+:py:meth:`xbob.io.load`, you can save your Matlab data in `HDF5`_ format, which
+then can be easily read from |project|. Detailed instructions about how to save
+and load data from Matlab to and from `HDF5`_ files can be found `here`__.
+
+.. _audiosignal:
+
+Loading and saving audio files
+------------------------------
+
+|project| does not yet support audio files (no wav codec). However, it is
+possible to use the `SciPy`_ module :py:mod:`scipy.io.wavfile` to do the job.
+For instance, to read a wave file, just use the
+:py:func:`scipy.io.wavfile.read` function.
+
+.. code-block:: python
+
+ >>> import scipy.io.wavfile
+ >>> filename = '/home/user/sample.wav'
+ >>> samplerate, data = scipy.io.wavfile.read(filename)
+ >>> print(type(data))
+ <... 'numpy.ndarray'>
+ >>> print(data.shape)
+ (132474, 2)
+
+In the above example, the stereo audio signal is represented as a 2D `NumPy`
+:py:class:`numpy.ndarray`. The first dimension corresponds to the time index
+(132474 frames) and the second dimesnion correpsonds to one of the audio
+channel (2 channels, stereo). The values in the array correpsond to the wave
+magnitudes.
+
+To save a `NumPy` :py:class:`numpy.ndarray` into a wave file, the
+:py:func:`scipy.io.wavfile.write` could be used, which also requires the
+framerate to be specified.
Reference
---------
This section includes information for using the pure Python API of ``xbob.io``.
+.. autoclass:: xbob.io.File
+
+.. autoclass:: xbob.io.HDF5File
+
+.. autoclass:: xbob.io.VideoReader
+
+.. autoclass:: xbob.io.VideoWriter
+
+.. autofunction:: xbob.io.load
+
+.. autofunction:: xbob.io.merge
+
+.. autofunction:: xbob.io.save
+
+.. autofunction:: xbob.io.append
+
+.. autofunction:: xbob.io.peek
+
+.. autofunction:: xbob.io.peek_all
+
+.. autofunction:: xbob.io.create_directories_save
+
.. autofunction:: xbob.io.get_include
-.. autoclass:: xbob.io.file
+.. include:: links.rst
+
+.. Place here your external references
+
+.. _ddl: http://www.hdfgroup.org/HDF5/doc/ddl.html
+.. _matlab-hdf5: http://www.mathworks.ch/help/techdoc/ref/hdf5write.html
+__ matlab-hdf5_
+
diff --git a/doc/video.rst b/doc/video.rst
new file mode 100644
index 0000000000000000000000000000000000000000..ab72d859bed48b9d04d390edb9cf26ea6edade57
--- /dev/null
+++ b/doc/video.rst
@@ -0,0 +1,568 @@
+.. vim: set fileencoding=utf-8 :
+.. Andre Anjos <andre.anjos@idiap.ch>
+.. Wed 20 Mar 2013 11:30:02 CET
+..
+.. Copyright (C) 2011-2013 Idiap Research Institute, Martigny, Switzerland
+..
+.. This program is free software: you can redistribute it and/or modify
+.. it under the terms of the GNU General Public License as published by
+.. the Free Software Foundation, version 3 of the License.
+..
+.. This program is distributed in the hope that it will be useful,
+.. but WITHOUT ANY WARRANTY; without even the implied warranty of
+.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.. GNU General Public License for more details.
+..
+.. You should have received a copy of the GNU General Public License
+.. along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+=============================
+ Using Videos with |project|
+=============================
+
+Video read and write support in |project| uses FFmpeg_ as implementation
+backend. In Ubuntu-based distributions, FFmpeg_ was replaced by libav_, which
+is a fork based on FFmpeg_ version 0.8. |project| can detect and use libav_
+when FFmpeg_ is not available on the machine. We currently support a variety of
+FFmpeg_ (and libav_) releases, ranging from FFmpeg_ 0.5 until the most recent
+branches.
+
+FFmpeg_ (and libav_) provide a (reasonably) uniform API for reading and writing
+data into a variety of video container formats, using different video and audio
+codecs. |project| leverages on this API to propose a sub-range of formats and
+codecs that work well together, with low distortion patterns and accross
+platforms.
+
+.. note::
+
+ As much as we strive to make video formats and codecs available to all
+ platforms in which |project| is available, codecs, in particular may be
+ disabled by compilation options on FFmpeg_ or libav_, in which case |project|
+ builds will not be able to use them.
+
+.. note::
+
+ Currently, |project| does not support reading or writing of audio streams on
+ video data - only images.
+
+This section provides guidance in choosing a set of formats and codecs for your
+project, so you will be able to leverage the maximum from |project|.
+
+Codec and Format Availability
+-----------------------------
+
+To get a list of all FFmpeg_ (or libav_) supported formats for a given build of
+|project|, use the ``bob_video_test.py`` application:
+
+.. code-block:: sh
+
+ $ bob_video_test.py --list-all-codecs # lists all codecs available
+
+ $ bob_video_test.py --list-all-formats # lists all formats available
+
+These listings represent all that is compiled with your current installation of
+FFmpeg_ or libav_. To list supported formats and codecs by |project| use
+another set of command-line options:
+
+.. code-block:: sh
+
+ $ bob_video_test.py --list-codecs # lists all codecs currently supported
+
+ $ bob_video_test.py --list-formats # lists all formats currently supported
+
+The program ``bob_video_test.py`` can be used to run a sequence of tests using
+all combinations of *supported* formats and tests:
+
+.. code-block:: sh
+
+ $ bob_video_test.py # runs all tests
+
+This will run through all combinations of supported codecs and formats and will
+report average distortion figures for each of 4 different tests, which exercise
+different aspects of each combination of format and codec. Here is a an example
+output:
+
+.. code-block:: text
+
+ Video Encoding/Decoding Test Tool v1.2.0a0 (bob_video_test)
+ Settings:
+ Width : 128 pixels
+ Height : 128 pixels
+ Length : 30 frames
+ Framerate: 30.000000 Hz
+ Legend:
+ C: Color test
+ N: Noise test
+ U: User test
+ S: Frameskip test
+ Running 4 test(s)...CSNU
+
+ =========== ===== ======= =======================================
+ test fmt codec figure (lower means better quality)
+ =========== ===== ======= =======================================
+ color mov h264 4.603 min=0.890@22 max=8.387@9
+ frameskip mov h264 0.108 min=0.009@11 max=0.344@0
+ noise mov h264 44.900 min=43.916@4 max=46.103@29
+ user mov h264 1.983 min=1.525@0 max=2.286@7
+ =========== ===== ======= =======================================
+
+Each line in the output table represents the average distortion patterns for
+the particular test using the format and codec described. The lower the
+distortion, the better the combination of format and codecs is. Different tests
+have different levels of baseline performance. The figures above were obtained
+in a healthy (no know bugs) system, running libav_ 0.8.13 (Ubuntu 12.10). Each
+line indicates, besides the average distortion per frame, the minimum and the
+maximum obtained and in which frame (counting from 0 - zero), that figure was
+obtained.
+
+The video tests are made on temporary files that are discarded after the test
+is completed. You can use the option ``--output=<directory>`` to specify a
+directory in which the generated files will be saved. You can then go to these
+directories and explore potential problems you may find.
+
+Each test creates a video from an artificially generated test signal, encodes
+it using the defined format and codec and reads it back, comparing the output
+result with the original sequence. The sole exception is the ``user`` test. In
+this test, a user test sequence is (partially) loaded and tested. If you don't
+specify any sequence, a default sequence from |project| is used. If you want to
+test a specific sequence of your own, use ``--user-video`` to specify the path
+of the video sequence you want to test with. By default, only the first 10
+frames of the sequence are used for the test, to speed-up execution. You can
+change this behavior with the option ``--user-frames``. Here is an example:
+
+.. code-block:: sh
+
+ $ bob_video_test.py --user-video=test_sample.avi
+
+All tests are executed by default, on all combination of formats and codecs.
+That can be long. You can limit the test execution by properly choosing the
+format (``--format``), the codec (``--codec``) and the tests to execute. For
+example:
+
+.. code-block:: sh
+
+ # execute only the user video test with a user provided video and
+ # using the H.264 built-in codec and a MOV output file format.
+ $ xbob_video_test.py --format mov --codec h264 --user-video=test_sample.avi -- user
+
+.. note::
+
+ Not all codecs can be used by all formats available. For example, the ``mp4``
+ file format cannot use the ``vp8`` codec, even if both are supported by
+ |project|. To know which formats support each codec, you can execute the
+ following python code:
+
+ .. code-block:: python
+
+ import xbob.io
+ xbob.io.supported_videowriter_formats()['mp4']['supported_codecs'].keys()
+ ['h264', 'libx264', 'mjpeg', 'mpeg1video']
+
+ You can see from the output command that only 4 codecs are supported by the
+ file format ``mp4``.
+
+You can test new combinations of formats and codecs which are not currently
+supported by |project|, as long as they are supported by the underlying FFmpeg_
+or libav_ installations. In this case, just specify the format and/or codec
+names using ``--format`` and ``--codec`` options in the application
+``xbob_video_test.py``. The advantage of using *supported* formats and codecs is
+that we make sure a minimal distortion figure is respected in all platform
+nightly builds, with our unit and integration tests. We cannot, currently,
+test all possible combinations of codecs and formats.
+
+Know Your Platforms
+-------------------
+
+One important aspect when working with videos is to know there will be some
+lossy compression applied to the output. This means you will **loose**
+information when re-encoding. When working with videos, you will want to choose
+the combination of format and codec that will work well accross different
+platforms. We recommend to run ``xbob_video_test.py`` with a few of your video
+inputs to make sure they can be decoded with low distortion where you plan to
+work.
+
+.. note::
+
+ The only codec that supports lossless compression in |project| is ``zlib``.
+ Of course, the output files are considerably bigger, but they continue to be
+ readable using any FFmpeg_-based movie player or even QuickTime (on OSX), if
+ Perian is installed.
+
+Example Output in Different Platforms
+-------------------------------------
+
+In what follows, you will find some tabbed output for different combinations of
+operating systems and FFmpeg_/libav_ versions. To run these tests we only
+executed:
+
+.. code-block:: sh
+
+ $ xbob_video_test.py
+
+Idiap Linux (Xubuntu), version 12.10 + libav 0.8.3
+==================================================
+
+=========== ===== ============ ================================================
+ test fmt codec figure (lower means better quality)
+=========== ===== ============ ================================================
+ color avi ffv1 4.569 min=0.888\@22 max=8.377\@9
+ color avi h264 4.603 min=0.890\@22 max=8.388\@9
+ color avi libvpx 4.657 min=0.955\@26 max=8.528\@9
+ color avi libx264 4.603 min=0.890\@22 max=8.388\@9
+ color avi mjpeg 4.676 min=0.965\@22 max=8.469\@9
+ color avi mpeg1video 4.781 min=1.103\@28 max=8.483\@9
+ color avi mpeg2video 4.741 min=1.004\@16 max=8.466\@9
+ color avi mpeg4 4.892 min=1.087\@24 max=8.658\@9
+ color avi msmpeg4 4.921 min=1.073\@24 max=8.717\@9
+ color avi msmpeg4v2 4.921 min=1.073\@24 max=9.181\@17
+ color avi vp8 4.657 min=0.955\@26 max=8.528\@9
+ color avi wmv1 4.871 min=1.087\@24 max=8.729\@9
+ color avi wmv2 4.884 min=1.093\@24 max=8.823\@9
+ color avi zlib 0.000 min=0.000\@0 max=0.000\@0
+ color mov ffv1 4.569 min=0.888\@22 max=8.377\@9
+ color mov h264 4.603 min=0.890\@22 max=8.387\@9
+ color mov libvpx 4.657 min=0.955\@26 max=8.528\@9
+ color mov libx264 4.603 min=0.890\@22 max=8.387\@9
+ color mov mjpeg 4.676 min=0.965\@22 max=8.469\@9
+ color mov mpeg1video 4.781 min=1.103\@28 max=8.483\@9
+ color mov mpeg2video 4.741 min=1.004\@16 max=8.466\@9
+ color mov mpeg4 4.892 min=1.087\@24 max=8.658\@9
+ color mov msmpeg4 4.921 min=1.073\@24 max=8.717\@9
+ color mov msmpeg4v2 4.921 min=1.073\@24 max=9.181\@17
+ color mov vp8 4.657 min=0.955\@26 max=8.528\@9
+ color mov wmv1 4.871 min=1.087\@24 max=8.729\@9
+ color mov wmv2 4.884 min=1.093\@24 max=8.823\@9
+ color mov zlib 0.000 min=0.000\@0 max=0.000\@0
+ color mp4 ffv1 format+codec unsupported
+ color mp4 h264 4.603 min=0.890\@22 max=8.387\@9
+ color mp4 libvpx format+codec unsupported
+ color mp4 libx264 4.603 min=0.890\@22 max=8.387\@9
+ color mp4 mjpeg 4.676 min=0.965\@22 max=8.469\@9
+ color mp4 mpeg1video 4.781 min=1.103\@28 max=8.483\@9
+ color mp4 mpeg2video 4.741 min=1.004\@16 max=8.466\@9
+ color mp4 mpeg4 4.892 min=1.087\@24 max=8.658\@9
+ color mp4 msmpeg4 format+codec unsupported
+ color mp4 msmpeg4v2 format+codec unsupported
+ color mp4 vp8 format+codec unsupported
+ color mp4 wmv1 format+codec unsupported
+ color mp4 wmv2 format+codec unsupported
+ color mp4 zlib format+codec unsupported
+ frameskip avi ffv1 0.018 min=0.002\@11 max=0.029\@8
+ frameskip avi h264 0.108 min=0.009\@11 max=0.344\@0
+ frameskip avi libvpx 0.129 min=0.042\@11 max=0.198\@8
+ frameskip avi libx264 0.108 min=0.009\@11 max=0.344\@0
+ frameskip avi mjpeg 0.380 min=0.141\@11 max=1.108\@0
+ frameskip avi mpeg1video 0.426 min=0.237\@17 max=1.338\@0
+ frameskip avi mpeg2video 0.411 min=0.223\@15 max=1.284\@0
+ frameskip avi mpeg4 0.454 min=0.263\@17 max=0.858\@0
+ frameskip avi msmpeg4 1.684 min=0.257\@12 max=3.766\@15
+ frameskip avi msmpeg4v2 1.683 min=0.257\@12 max=3.765\@15
+ frameskip avi vp8 0.129 min=0.042\@11 max=0.198\@8
+ frameskip avi wmv1 0.627 min=0.191\@11 max=1.568\@8
+ frameskip avi wmv2 0.626 min=0.191\@11 max=1.566\@8
+ frameskip avi zlib 0.000 min=0.000\@0 max=0.000\@0
+ frameskip mov ffv1 0.018 min=0.002\@11 max=0.029\@8
+ frameskip mov h264 0.108 min=0.009\@11 max=0.344\@0
+ frameskip mov libvpx 0.129 min=0.042\@11 max=0.198\@8
+ frameskip mov libx264 0.108 min=0.009\@11 max=0.344\@0
+ frameskip mov mjpeg 0.380 min=0.141\@11 max=1.108\@0
+ frameskip mov mpeg1video 0.426 min=0.237\@17 max=1.338\@0
+ frameskip mov mpeg2video 0.411 min=0.223\@15 max=1.284\@0
+ frameskip mov mpeg4 0.454 min=0.263\@17 max=0.858\@0
+ frameskip mov msmpeg4 1.684 min=0.257\@12 max=3.766\@15
+ frameskip mov msmpeg4v2 1.683 min=0.257\@12 max=3.765\@15
+ frameskip mov vp8 0.129 min=0.042\@11 max=0.198\@8
+ frameskip mov wmv1 0.627 min=0.191\@11 max=1.568\@8
+ frameskip mov wmv2 0.626 min=0.191\@11 max=1.566\@8
+ frameskip mov zlib 0.000 min=0.000\@0 max=0.000\@0
+ frameskip mp4 ffv1 format+codec unsupported
+ frameskip mp4 h264 0.108 min=0.009\@11 max=0.344\@0
+ frameskip mp4 libvpx format+codec unsupported
+ frameskip mp4 libx264 0.108 min=0.009\@11 max=0.344\@0
+ frameskip mp4 mjpeg 0.380 min=0.141\@11 max=1.108\@0
+ frameskip mp4 mpeg1video 0.426 min=0.237\@17 max=1.338\@0
+ frameskip mp4 mpeg2video 0.411 min=0.223\@15 max=1.284\@0
+ frameskip mp4 mpeg4 0.454 min=0.263\@17 max=0.858\@0
+ frameskip mp4 msmpeg4 format+codec unsupported
+ frameskip mp4 msmpeg4v2 format+codec unsupported
+ frameskip mp4 vp8 format+codec unsupported
+ frameskip mp4 wmv1 format+codec unsupported
+ frameskip mp4 wmv2 format+codec unsupported
+ frameskip mp4 zlib format+codec unsupported
+ noise avi ffv1 44.192 min=43.887\@0 max=44.568\@8
+ noise avi h264 44.882 min=43.738\@2 max=45.848\@27
+ noise avi libvpx 48.629 min=44.156\@12 max=54.365\@27
+ noise avi libx264 44.883 min=44.089\@2 max=45.857\@29
+ noise avi mjpeg 45.723 min=43.942\@3 max=48.283\@28
+ noise avi mpeg1video 46.270 min=44.412\@2 max=48.632\@29
+ noise avi mpeg2video 45.227 min=44.008\@5 max=48.528\@29
+ noise avi mpeg4 45.769 min=43.720\@4 max=48.472\@27
+ noise avi msmpeg4 45.757 min=44.034\@7 max=48.055\@24
+ noise avi msmpeg4v2 45.789 min=43.908\@6 max=48.423\@27
+ noise avi vp8 48.796 min=43.765\@0 max=50.864\@15
+ noise avi wmv1 45.729 min=43.878\@6 max=47.921\@29
+ noise avi wmv2 46.105 min=44.205\@3 max=48.261\@28
+ noise avi zlib 0.000 min=0.000\@0 max=0.000\@0
+ noise mov ffv1 44.200 min=43.869\@20 max=44.719\@22
+ noise mov h264 44.882 min=43.991\@6 max=46.183\@27
+ noise mov libvpx 48.692 min=43.934\@0 max=50.906\@15
+ noise mov libx264 44.909 min=43.773\@3 max=46.079\@29
+ noise mov mjpeg 45.754 min=43.823\@8 max=48.278\@28
+ noise mov mpeg1video 46.353 min=44.326\@1 max=48.712\@29
+ noise mov mpeg2video 45.970 min=43.952\@4 max=50.645\@29
+ noise mov mpeg4 45.772 min=43.961\@4 max=48.414\@28
+ noise mov msmpeg4 45.764 min=43.867\@5 max=48.156\@29
+ noise mov msmpeg4v2 45.844 min=44.009\@6 max=48.317\@27
+ noise mov vp8 48.323 min=43.985\@12 max=50.512\@19
+ noise mov wmv1 45.803 min=44.109\@3 max=48.334\@29
+ noise mov wmv2 46.081 min=43.950\@4 max=48.293\@26
+ noise mov zlib 0.000 min=0.000\@0 max=0.000\@0
+ noise mp4 ffv1 format+codec unsupported
+ noise mp4 h264 44.856 min=43.749\@1 max=46.045\@27
+ noise mp4 libvpx format+codec unsupported
+ noise mp4 libx264 44.785 min=43.820\@0 max=46.093\@28
+ noise mp4 mjpeg 45.725 min=43.979\@7 max=48.208\@28
+ noise mp4 mpeg1video 46.227 min=44.144\@2 max=48.241\@27
+ noise mp4 mpeg2video 46.060 min=43.991\@5 max=51.358\@29
+ noise mp4 mpeg4 45.690 min=44.072\@6 max=47.974\@28
+ noise mp4 msmpeg4 format+codec unsupported
+ noise mp4 msmpeg4v2 format+codec unsupported
+ noise mp4 vp8 format+codec unsupported
+ noise mp4 wmv1 format+codec unsupported
+ noise mp4 wmv2 format+codec unsupported
+ noise mp4 zlib format+codec unsupported
+ user avi ffv1 1.174 min=1.166\@2 max=1.187\@7
+ user avi h264 1.988 min=1.525\@0 max=2.290\@7
+ user avi libvpx 1.614 min=1.464\@0 max=1.711\@8
+ user avi libx264 1.988 min=1.525\@0 max=2.290\@7
+ user avi mjpeg 1.067 min=1.014\@2 max=1.444\@0
+ user avi mpeg1video 1.586 min=1.447\@1 max=1.895\@0
+ user avi mpeg2video 1.743 min=1.515\@3 max=1.891\@8
+ user avi mpeg4 1.794 min=1.606\@1 max=1.906\@9
+ user avi msmpeg4 1.802 min=1.599\@1 max=1.925\@8
+ user avi msmpeg4v2 1.775 min=1.599\@1 max=1.868\@9
+ user avi vp8 1.614 min=1.464\@0 max=1.711\@8
+ user avi wmv1 1.802 min=1.599\@1 max=1.925\@8
+ user avi wmv2 1.799 min=1.596\@1 max=1.921\@8
+ user avi zlib 0.000 min=0.000\@0 max=0.000\@0
+ user mov ffv1 1.174 min=1.166\@2 max=1.187\@7
+ user mov h264 1.983 min=1.525\@0 max=2.286\@7
+ user mov libvpx 1.614 min=1.464\@0 max=1.711\@8
+ user mov libx264 1.983 min=1.525\@0 max=2.286\@7
+ user mov mjpeg 1.067 min=1.014\@2 max=1.444\@0
+ user mov mpeg1video 1.586 min=1.447\@1 max=1.895\@0
+ user mov mpeg2video 1.743 min=1.515\@3 max=1.891\@8
+ user mov mpeg4 1.794 min=1.606\@1 max=1.906\@9
+ user mov msmpeg4 1.802 min=1.599\@1 max=1.925\@8
+ user mov msmpeg4v2 1.775 min=1.599\@1 max=1.868\@9
+ user mov vp8 1.614 min=1.464\@0 max=1.711\@8
+ user mov wmv1 1.802 min=1.599\@1 max=1.925\@8
+ user mov wmv2 1.799 min=1.596\@1 max=1.921\@8
+ user mov zlib 0.000 min=0.000\@0 max=0.000\@0
+ user mp4 ffv1 format+codec unsupported
+ user mp4 h264 1.983 min=1.525\@0 max=2.286\@7
+ user mp4 libvpx format+codec unsupported
+ user mp4 libx264 1.983 min=1.525\@0 max=2.286\@7
+ user mp4 mjpeg 1.067 min=1.014\@2 max=1.444\@0
+ user mp4 mpeg1video 1.586 min=1.447\@1 max=1.895\@0
+ user mp4 mpeg2video 1.743 min=1.515\@3 max=1.891\@8
+ user mp4 mpeg4 1.794 min=1.606\@1 max=1.906\@9
+ user mp4 msmpeg4 format+codec unsupported
+ user mp4 msmpeg4v2 format+codec unsupported
+ user mp4 vp8 format+codec unsupported
+ user mp4 wmv1 format+codec unsupported
+ user mp4 wmv2 format+codec unsupported
+ user mp4 zlib format+codec unsupported
+=========== ===== ============ ================================================
+
+MacOSX 10.8.3 + FFmpeg 1.1.2
+============================
+
+=========== ===== ================== ========================================
+ test fmt codec figure (lower is better quality)
+=========== ===== ================== ========================================
+ color avi ffv1 4.643 min=0.999\@24 max=8.420\@9
+ color avi h264 4.685 min=1.001\@24 max=8.473\@9
+ color avi libvpx 4.736 min=1.079\@26 max=8.503\@9
+ color avi libx264 4.685 min=1.001\@24 max=8.473\@9
+ color avi mjpeg 4.617 min=0.934\@24 max=8.440\@9
+ color avi mpeg1video 4.820 min=1.125\@16 max=8.548\@9
+ color avi mpeg2video 4.787 min=1.130\@16 max=8.465\@9
+ color avi mpeg4 4.956 min=1.129\@24 max=8.725\@9
+ color avi mpegvideo 4.787 min=1.130\@16 max=8.465\@9
+ color avi msmpeg4 4.987 min=1.114\@24 max=8.731\@9
+ color avi msmpeg4v2 4.949 min=1.114\@24 max=8.667\@9
+ color avi vp8 4.736 min=1.079\@26 max=8.503\@9
+ color avi wmv1 4.925 min=1.129\@24 max=8.728\@9
+ color avi wmv2 4.936 min=1.138\@24 max=8.796\@9
+ color avi zlib 0.000 min=0.000\@0 max=0.000\@0
+ color mov ffv1 4.643 min=0.999\@24 max=8.420\@9
+ color mov h264 4.645 min=1.001\@24 max=8.424\@9
+ color mov libvpx 4.736 min=1.079\@26 max=8.503\@9
+ color mov libx264 4.645 min=1.001\@24 max=8.424\@9
+ color mov mjpeg 4.617 min=0.934\@24 max=8.440\@9
+ color mov mpeg1video 4.820 min=1.125\@16 max=8.548\@9
+ color mov mpeg2video 4.787 min=1.130\@16 max=8.465\@9
+ color mov mpeg4 4.956 min=1.129\@24 max=8.725\@9
+ color mov mpegvideo 4.787 min=1.130\@16 max=8.465\@9
+ color mov msmpeg4 4.987 min=1.114\@24 max=8.731\@9
+ color mov msmpeg4v2 4.949 min=1.114\@24 max=8.667\@9
+ color mov vp8 4.736 min=1.079\@26 max=8.503\@9
+ color mov wmv1 4.925 min=1.129\@24 max=8.728\@9
+ color mov wmv2 4.936 min=1.138\@24 max=8.796\@9
+ color mov zlib 0.000 min=0.000\@0 max=0.000\@0
+ color mp4 ffv1 format+codec unsupported
+ color mp4 h264 4.645 min=1.001\@24 max=8.424\@9
+ color mp4 libvpx format+codec unsupported
+ color mp4 libx264 4.645 min=1.001\@24 max=8.424\@9
+ color mp4 mjpeg 4.617 min=0.934\@24 max=8.440\@9
+ color mp4 mpeg1video 4.820 min=1.125\@16 max=8.548\@9
+ color mp4 mpeg2video 4.787 min=1.130\@16 max=8.465\@9
+ color mp4 mpeg4 4.956 min=1.129\@24 max=8.725\@9
+ color mp4 mpegvideo 4.787 min=1.130\@16 max=8.465\@9
+ color mp4 msmpeg4 format+codec unsupported
+ color mp4 msmpeg4v2 format+codec unsupported
+ color mp4 vp8 format+codec unsupported
+ color mp4 wmv1 format+codec unsupported
+ color mp4 wmv2 format+codec unsupported
+ color mp4 zlib format+codec unsupported
+ frameskip avi ffv1 0.018 min=0.002\@11 max=0.029\@8
+ frameskip avi h264 0.120 min=0.017\@21 max=0.300\@0
+ frameskip avi libvpx 0.122 min=0.051\@11 max=0.181\@0
+ frameskip avi libx264 0.120 min=0.017\@21 max=0.300\@0
+ frameskip avi mjpeg 0.386 min=0.147\@11 max=1.085\@0
+ frameskip avi mpeg1video 0.427 min=0.243\@11 max=1.310\@0
+ frameskip avi mpeg2video 0.408 min=0.229\@17 max=1.258\@0
+ frameskip avi mpeg4 0.456 min=0.253\@12 max=0.849\@0
+ frameskip avi mpegvideo 0.408 min=0.229\@17 max=1.258\@0
+ frameskip avi msmpeg4 1.608 min=0.434\@24 max=3.409\@25
+ frameskip avi msmpeg4v2 1.600 min=0.434\@24 max=3.708\@5
+ frameskip avi vp8 0.122 min=0.051\@11 max=0.181\@0
+ frameskip avi wmv1 0.617 min=0.191\@11 max=1.981\@8
+ frameskip avi wmv2 0.614 min=0.191\@11 max=1.978\@8
+ frameskip avi zlib 0.000 min=0.000\@0 max=0.000\@0
+ frameskip mov ffv1 0.018 min=0.002\@11 max=0.029\@8
+ frameskip mov h264 0.042 min=0.011\@11 max=0.085\@9
+ frameskip mov libvpx 0.122 min=0.051\@11 max=0.181\@0
+ frameskip mov libx264 0.042 min=0.011\@11 max=0.085\@9
+ frameskip mov mjpeg 0.386 min=0.147\@11 max=1.085\@0
+ frameskip mov mpeg1video 0.427 min=0.243\@11 max=1.310\@0
+ frameskip mov mpeg2video 0.408 min=0.229\@17 max=1.258\@0
+ frameskip mov mpeg4 0.456 min=0.253\@12 max=0.849\@0
+ frameskip mov mpegvideo 0.408 min=0.229\@17 max=1.258\@0
+ frameskip mov msmpeg4 1.608 min=0.434\@24 max=3.409\@25
+ frameskip mov msmpeg4v2 1.600 min=0.434\@24 max=3.708\@5
+ frameskip mov vp8 0.122 min=0.051\@11 max=0.181\@0
+ frameskip mov wmv1 0.617 min=0.191\@11 max=1.981\@8
+ frameskip mov wmv2 0.614 min=0.191\@11 max=1.978\@8
+ frameskip mov zlib 0.000 min=0.000\@0 max=0.000\@0
+ frameskip mp4 ffv1 format+codec unsupported
+ frameskip mp4 h264 0.042 min=0.011\@11 max=0.085\@9
+ frameskip mp4 libvpx format+codec unsupported
+ frameskip mp4 libx264 0.042 min=0.011\@11 max=0.085\@9
+ frameskip mp4 mjpeg 0.386 min=0.147\@11 max=1.085\@0
+ frameskip mp4 mpeg1video 0.427 min=0.243\@11 max=1.310\@0
+ frameskip mp4 mpeg2video 0.408 min=0.229\@17 max=1.258\@0
+ frameskip mp4 mpeg4 0.456 min=0.253\@12 max=0.849\@0
+ frameskip mp4 mpegvideo 0.408 min=0.229\@17 max=1.258\@0
+ frameskip mp4 msmpeg4 format+codec unsupported
+ frameskip mp4 msmpeg4v2 format+codec unsupported
+ frameskip mp4 vp8 format+codec unsupported
+ frameskip mp4 wmv1 format+codec unsupported
+ frameskip mp4 wmv2 format+codec unsupported
+ frameskip mp4 zlib format+codec unsupported
+ noise avi ffv1 44.108 min=43.717\@16 max=44.565\@22
+ noise avi h264 44.509 min=43.859\@4 max=45.146\@27
+ noise avi libvpx 46.882 min=43.812\@1 max=49.422\@18
+ noise avi libx264 44.572 min=43.917\@5 max=45.236\@29
+ noise avi mjpeg 45.739 min=43.819\@4 max=48.211\@29
+ noise avi mpeg1video 46.320 min=44.273\@3 max=48.996\@29
+ noise avi mpeg2video 46.054 min=43.987\@7 max=51.580\@29
+ noise avi mpeg4 45.755 min=44.071\@2 max=48.502\@28
+ noise avi mpegvideo 44.951 min=43.775\@1 max=46.796\@24
+ noise avi msmpeg4 45.749 min=43.934\@5 max=48.267\@29
+ noise avi msmpeg4v2 45.846 min=43.987\@0 max=48.264\@27
+ noise avi vp8 46.457 min=43.931\@12 max=48.857\@27
+ noise avi wmv1 45.804 min=44.219\@10 max=48.252\@28
+ noise avi wmv2 46.091 min=44.113\@3 max=48.380\@25
+ noise avi zlib 0.000 min=0.000\@0 max=0.000\@0
+ noise mov ffv1 44.128 min=43.657\@15 max=44.513\@21
+ noise mov h264 44.168 min=43.794\@24 max=44.577\@7
+ noise mov libvpx 47.009 min=44.127\@4 max=49.547\@17
+ noise mov libx264 44.143 min=43.813\@23 max=44.529\@16
+ noise mov mjpeg 44.378 min=44.020\@18 max=44.670\@0
+ noise mov mpeg1video 44.564 min=43.903\@9 max=45.314\@0
+ noise mov mpeg2video 44.340 min=44.021\@26 max=44.733\@0
+ noise mov mpeg4 44.338 min=43.923\@3 max=44.677\@11
+ noise mov mpegvideo 44.343 min=43.978\@8 max=44.904\@29
+ noise mov msmpeg4 44.293 min=43.870\@9 max=44.669\@24
+ noise mov msmpeg4v2 44.256 min=43.859\@5 max=44.596\@21
+ noise mov vp8 47.558 min=43.955\@0 max=52.720\@25
+ noise mov wmv1 44.283 min=43.848\@24 max=44.643\@14
+ noise mov wmv2 44.323 min=43.957\@10 max=44.727\@0
+ noise mov zlib 0.000 min=0.000\@0 max=0.000\@0
+ noise mp4 ffv1 format+codec unsupported
+ noise mp4 h264 44.118 min=43.717\@18 max=44.439\@1
+ noise mp4 libvpx format+codec unsupported
+ noise mp4 libx264 44.218 min=43.870\@8 max=44.730\@19
+ noise mp4 mjpeg 44.374 min=44.061\@2 max=44.902\@0
+ noise mp4 mpeg1video 44.537 min=44.157\@18 max=45.222\@0
+ noise mp4 mpeg2video 44.397 min=43.834\@5 max=44.825\@0
+ noise mp4 mpeg4 44.276 min=43.875\@9 max=44.912\@17
+ noise mp4 mpegvideo 44.339 min=43.812\@2 max=45.328\@0
+ noise mp4 msmpeg4 format+codec unsupported
+ noise mp4 msmpeg4v2 format+codec unsupported
+ noise mp4 vp8 format+codec unsupported
+ noise mp4 wmv1 format+codec unsupported
+ noise mp4 wmv2 format+codec unsupported
+ noise mp4 zlib format+codec unsupported
+ user avi ffv1 1.463 min=1.457\@5 max=1.472\@7
+ user avi h264 2.028 min=1.666\@0 max=2.201\@9
+ user avi libvpx 1.999 min=1.646\@0 max=2.420\@2
+ user avi libx264 2.028 min=1.666\@0 max=2.201\@9
+ user avi mjpeg 1.197 min=1.149\@6 max=1.532\@0
+ user avi mpeg1video 1.760 min=1.641\@1 max=2.061\@0
+ user avi mpeg2video 1.882 min=1.694\@3 max=2.026\@0
+ user avi mpeg4 1.960 min=1.782\@1 max=2.076\@9
+ user avi mpegvideo 1.882 min=1.694\@3 max=2.026\@0
+ user avi msmpeg4 1.964 min=1.773\@1 max=2.088\@8
+ user avi msmpeg4v2 1.921 min=1.773\@1 max=2.008\@9
+ user avi vp8 1.999 min=1.646\@0 max=2.420\@2
+ user avi wmv1 1.964 min=1.773\@1 max=2.088\@8
+ user avi wmv2 1.958 min=1.768\@1 max=2.082\@8
+ user avi zlib 0.000 min=0.000\@0 max=0.000\@0
+ user mov ffv1 1.463 min=1.457\@5 max=1.472\@7
+ user mov h264 1.533 min=1.477\@0 max=1.566\@7
+ user mov libvpx 2.103 min=1.646\@0 max=2.547\@2
+ user mov libx264 1.533 min=1.477\@0 max=1.566\@7
+ user mov mjpeg 1.197 min=1.149\@6 max=1.532\@0
+ user mov mpeg1video 1.760 min=1.641\@1 max=2.061\@0
+ user mov mpeg2video 1.882 min=1.694\@3 max=2.026\@0
+ user mov mpeg4 1.960 min=1.782\@1 max=2.076\@9
+ user mov mpegvideo 1.882 min=1.694\@3 max=2.026\@0
+ user mov msmpeg4 1.964 min=1.773\@1 max=2.088\@8
+ user mov msmpeg4v2 1.921 min=1.773\@1 max=2.008\@9
+ user mov vp8 2.103 min=1.646\@0 max=2.547\@2
+ user mov wmv1 1.964 min=1.773\@1 max=2.088\@8
+ user mov wmv2 1.958 min=1.768\@1 max=2.082\@8
+ user mov zlib 0.000 min=0.000\@0 max=0.000\@0
+ user mp4 ffv1 format+codec unsupported
+ user mp4 h264 1.533 min=1.477\@0 max=1.566\@7
+ user mp4 libvpx format+codec unsupported
+ user mp4 libx264 1.533 min=1.477\@0 max=1.566\@7
+ user mp4 mjpeg 1.197 min=1.149\@6 max=1.532\@0
+ user mp4 mpeg1video 1.760 min=1.641\@1 max=2.061\@0
+ user mp4 mpeg2video 1.882 min=1.694\@3 max=2.026\@0
+ user mp4 mpeg4 1.960 min=1.782\@1 max=2.076\@9
+ user mp4 mpegvideo 1.882 min=1.694\@3 max=2.026\@0
+ user mp4 msmpeg4 format+codec unsupported
+ user mp4 msmpeg4v2 format+codec unsupported
+ user mp4 vp8 format+codec unsupported
+ user mp4 wmv1 format+codec unsupported
+ user mp4 wmv2 format+codec unsupported
+ user mp4 zlib format+codec unsupported
+=========== ===== ================== ========================================
+
+.. include:: links.rst
+
+.. Place here your external references
diff --git a/xbob/io/hdf5.cpp b/xbob/io/hdf5.cpp
index d4c8bd4f3da7b0c5973384ba104ed28a64606e8f..0deb128834c7c3657c9edc34fe38302182ccd94f 100644
--- a/xbob/io/hdf5.cpp
+++ b/xbob/io/hdf5.cpp
@@ -40,7 +40,7 @@ cross-architecture format.\n\
\n\
Objects of this class allows users to read and write data from\n\
and to files in HDF5 format. For an introduction to HDF5, visit\n\
-the `HDF5 Website<http://www.hdfgroup.org/HDF5>`_.\n\
+the `HDF5 Website <http://www.hdfgroup.org/HDF5>`_.\n\
\n\
");
diff --git a/xbob/io/videoreader.cpp b/xbob/io/videoreader.cpp
index 24216e2b2368f709fd85947e09ed7c241b362023..e86ede81b6a2a685244034f7d90d7d986baf6bdf 100644
--- a/xbob/io/videoreader.cpp
+++ b/xbob/io/videoreader.cpp
@@ -41,14 +41,15 @@ implementation uses `FFmpeg <http://ffmpeg.org>`_ (or\n\
a stable freely available video encoding and decoding library,\n\
designed specifically for these tasks. You can read an entire\n\
video in memory by using the 'load()' method or use iterators\n\
-to read it frame by frame and avoid overloading your machine's\n\
-memory. The maximum precision data `FFmpeg` will yield is a 24-bit\n\
+to read it frame by frame and avoid overloading your machine\'s\n\
+memory. The maximum precision data `FFmpeg`_ will yield is a 24-bit\n\
(8-bit per band) representation of each pixel (32-bit depths are\n\
-also supported by `FFmpeg`, but not by this extension presently).\n\
+also supported by `FFmpeg`_, but not by this extension presently).\n\
So, the output of data is done with ``uint8`` as data type.\n\
Output will be colored using the RGB standard, with each band\n\
varying between 0 and 255, with zero meaning pure black and 255,\n\
pure white (color).\n\
+\n\
");
/* How to create a new PyBobIoVideoReaderObject */