Commit 625f0868 authored by Manuel Günther's avatar Manuel Günther
Browse files

New README and documentation strategy.

parent 952e88fa
......@@ -2,7 +2,7 @@
......@@ -17,5 +17,3 @@ dist
......@@ -8,6 +8,7 @@ matrix:
- secure: TquyIDtjrxz3d9SkrNTP59OuG1/JIEozqUI/tQLHS/3SyYe5ZLjCBhzr0Ay0UmqLQpcoCTp+RSfNzIfHxCqwGqu9+GndXiuHZQAG9FB1gyjBovsHyUki1PAbNSBl/glenNShIFtgpOxKUaYqQ0JjDBdxywOjoqKVJgV27Vk0K0Y=
- secure: IVEbgKYaWUwNapbnioa3rrkLbNLe8pZqJIo9YWmO4EHI58qHyVahb1K9KSM0aNIN2gMZY2i5h00w64w9VxFsTJEwse/Cup3UBMVSufT5r+zVpRwXlEmc62BiRgD4PRXkDN74PsZvPYFs0GGFtpZWsg8oqxwZXBBYygHYxcmKN5A=
- python: 3.2
......@@ -20,7 +21,7 @@ matrix:
- sudo add-apt-repository -y ppa:biometrics/bob
- sudo apt-get update -qq
- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libavcodec-dev libavformat-dev libswscale-dev libhdf5-serial-dev
- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libavcodec-dev libavformat-dev libswscale-dev libhdf5-serial-dev texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
- if [ -n "${NUMPYSPEC}" ]; then sudo apt-get install -qq libatlas-dev libatlas-base-dev liblapack-dev gfortran; fi
- if [ -n "${NUMPYSPEC}" ]; then pip install --upgrade pip setuptools; fi
- if [ -n "${NUMPYSPEC}" ]; then pip install --find-links --find-links --use-wheel numpy$NUMPYSPEC; fi
......@@ -2,134 +2,38 @@
.. Andre Anjos <>
.. Thu 29 Aug 2013 16:07:57 CEST
.. image::
.. image::
.. image::
.. image::
.. image::
.. image::
.. image::
.. image::
.. image::
Support for Video I/O in bob::io
Video I/O Support for Bob
This package contains support for Video I/O in Bob. Video reading and writing
is implemented using either FFmpeg or LibAV, whichever is installed.
This package contains support for Video I/O in Bob.
Video reading and writing is implemented using either FFmpeg or LibAV, whichever is installed.
By importing this package, you activate a transparent plugin that makes possible reading and writing video files using :py:mod:`` functionalities.
Install it through normal means, via PyPI or use ``zc.buildout`` to bootstrap
the package and run test units.
External Library Requirements
To properly install this package, you will need the following C/C++ components
1. ``bob-io >= 2.0.0a2``
2. ``libavformat >= 52.31.0``
3. ``libavcodec >= 52.20.0``
4. ``libavutil >= 49.15.0``
5. ``libswscale >= 0.7.1``
.. note::
``libavformat``, ``libavcodec``, ``libavutil`` and ``libswscale`` are
components which are part of `FFmpeg`_ or `libav`_. We support any of these
The minimum version for `FFmpeg`_ is ``0.5``, while the minimum version for
`libav`_ should be ``0.8``.
To test for the availability of the libraries listed above, use the command
``pkg-config``. For example::
$ pkg-config --modversion libavformat
$ pkg-config --modversion bob-io
If any of the components is not installed on paths accessible by
``pkg-config``, you have two options:
1. Set the environment variable ``PKG_CONFIG_PATH`` so that ``.pc`` files for
each of those distributions can be properly located (see ``man pkg-config``
for details);
2. If you are using ``zc.buildout`` to setup your working environment, you can
use the buildout variable ``prefixes`` to define the path to the
installation area for your external packages.
To install this package -- alone or together with other `Packages of Bob <>`_ -- please read the `Installation Instructions <>`_.
For Bob_ to be able to work properly, some dependent packages are required to be installed.
Please make sure that you have read the `Dependencies <>`_ for your operating system.
For further documentation on this package, please read the `Stable Version <>`_ or the `Latest Version <>`_ of the documentation.
For a list of tutorials on this or the other packages ob Bob_, or information on submitting issues, asking questions and starting discussions, please visit its website.
The latest version of the documentation can be found `here <>`_.
Otherwise, you can generate the documentation for this package yourself, after installation, using Sphinx::
$ sphinx-build -b html doc sphinx
This shall place in the directory ``sphinx``, the current version for the
documentation of the package.
In order to enable support for video file reading and writing in your
application, make sure to import this module, before calling
:py:func:`` or similar::
>>> import
>>> import
>>>'myfile.avi', 'r')
You can run a set of tests using the nose test runner::
$ nosetests -sv
.. warning::
If Bob <= 1.2.1 is installed on your python path, nose will automatically
load the old version of the insulate plugin available in Bob, which will
trigger the loading of incompatible shared libraries (from Bob itself), in
to your working binary. This will cause a stack corruption. Either remove
the centrally installed version of Bob, or build your own version of Python
in which Bob <= 1.2.1 is not installed.
You can run our documentation tests using sphinx itself::
$ sphinx-build -b doctest doc sphinx
You can test overall test coverage with::
$ nosetests --with-coverage
The ``coverage`` egg must be installed for this to work properly.
To develop this package, install using ``zc.buildout``, using the buildout
configuration found on the root of the package::
$ python
$ ./bin/buildout
Tweak the options in ``buildout.cfg`` to disable/enable verbosity and debug
.. Place here references to all citations in lower case
.. _ffmpeg:
.. _libav:
.. _bob:
......@@ -15,9 +15,9 @@ develop = src/bob.extension
; options for bob.buildout extension
newest = false
debug = true
verbose = true
newest = false
bob.extension = git
......@@ -250,36 +250,10 @@ autoclass_content = 'both'
autodoc_member_order = 'bysource'
autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-inheritance']
def smaller_than(v1, v2):
"""Compares scipy/numpy version numbers"""
c1 = v1.split('.')
c2 = v2.split('.')[:len(c1)] #clip to the compared version
for i, k in enumerate(c2):
n1 = c1[i]
n2 = c2[i]
n1 = int(n1)
n2 = int(n2)
except ValueError:
n1 = str(n1)
n2 = str(n2)
if n1 > n2: return False
return True
# Some name mangling to find the correct sphinx manuals for some packages
numpy_version = __import__('numpy').version.version
if smaller_than(numpy_version, '1.5.z'):
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.x'
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.0'
numpy_manual = '' % numpy_version
# For inter-documentation mapping:
intersphinx_mapping = {
'' % sys.version_info[:2]: None,
numpy_manual: None,
from bob.extension.utils import link_documentation
intersphinx_mapping = link_documentation()
def setup(app):
......@@ -18,8 +18,7 @@
User Guide
This package provides support for dealing with videos in an equivalent way to
dealing with other data files in |project|:
This package provides support for dealing with videos in an equivalent way to dealing with other data files in |project|, i.e., by using :py:func:`` and :py:func:``.
.. doctest::
......@@ -28,11 +27,11 @@ dealing with other data files in |project|:
>>> my_video_copy ='testvideo.avi')
Video reading and writing is performed using an `FFmpeg`_ (or `libav`_ if
`FFmpeg`_ is not available) bridge. |project|'s :py:meth:``
`FFmpeg`_ is not available) bridge. |project|'s :py:func:``
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
For finer control over the loading, saving, format and codecs used for a
specific encoding or decoding operation, you must directly use either
......@@ -40,13 +40,13 @@ Codec and Format Availability
To get a list of all FFmpeg_ (or libav_) supported formats for a given build of
|project|, use the ```` application:
|project|, use the ```` application provided by this module:
.. code-block:: sh
$ --list-all-codecs # lists all codecs available
$ ./bin/ --list-all-codecs # lists all codecs available
$ --list-all-formats # lists all formats available
$ ./bin/ --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
......@@ -54,16 +54,16 @@ another set of command-line options:
.. code-block:: sh
$ --list-codecs # lists all codecs currently supported
$ ./bin/ --list-codecs # lists all codecs currently supported
$ --list-formats # lists all formats currently supported
$ ./bin/ --list-formats # lists all formats currently supported
The program ```` can be used to run a sequence of tests using
all combinations of *supported* formats and tests:
.. code-block:: sh
$ # runs all tests
$ ./bin/ # 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
......@@ -120,7 +120,7 @@ change this behavior with the option ``--user-frames``. Here is an example:
.. code-block:: sh
$ --user-video=test_sample.avi
$ ./bin/ --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
......@@ -131,7 +131,7 @@ example:
# 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.
$ --format mov --codec h264 --user-video=test_sample.avi -- user
$ ./bin/ --format mov --codec h264 --user-video=test_sample.avi -- user
.. note::
......@@ -140,10 +140,12 @@ example:
|project|. To know which formats support each codec, you can execute the
following python code:
.. code-block:: python
.. doctest::
>>> import
>>> codecs =['mp4']['supported_codecs'].keys()
>>> print(codecs) # doctest: +SKIP
['h264', 'libx264', 'mjpeg', 'mpeg1video']
You can see from the output command that only 4 codecs are supported by the
......@@ -185,7 +187,7 @@ executed:
.. code-block:: sh
$ ./bin/
Idiap Linux (Xubuntu), version 12.10 + libav 0.8.3
......@@ -124,7 +124,8 @@ setup(
classifiers = [
'Development Status :: 3 - Alpha',
'Framework :: Bob',
'Development Status :: 4 - Beta',
'Intended Audience :: Developers',
'License :: OSI Approved :: BSD License',
'Natural Language :: English',
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment