README.rst 4.34 KB
Newer Older
André Anjos's avatar
André Anjos committed
1
2
3
4
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.anjos@idiap.ch>
.. Thu 29 Aug 2013 16:07:57 CEST

André Anjos's avatar
André Anjos committed
5
6
.. image:: https://travis-ci.org/bioidiap/bob.io.video.svg?branch=master
   :target: https://travis-ci.org/bioidiap/bob.io.video
7
8
.. image:: http://img.shields.io/badge/docs-latest-orange.png
   :target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.io.video/master/index.html
André Anjos's avatar
André Anjos committed
9
10
11
12
13
14
15
16
.. image:: https://coveralls.io/repos/bioidiap/bob.io.video/badge.png
   :target: https://coveralls.io/r/bioidiap/bob.io.video
.. image:: http://img.shields.io/github/tag/bioidiap/bob.io.video.png
   :target: https://github.com/bioidiap/bob.io.video
.. image:: http://img.shields.io/pypi/v/bob.io.video.png
   :target: https://pypi.python.org/pypi/bob.io.video
.. image:: http://img.shields.io/pypi/dm/bob.io.video.png
   :target: https://pypi.python.org/pypi/bob.io.video
André Anjos's avatar
André Anjos committed
17
18
19
20
21
22
23
24
25
26
27
28
29
30

==================================
 Support for Video I/O in bob::io
==================================

This package contains support for Video I/O in Bob. Video reading and writing
is implemented using either FFmpeg or LibAV, whichever is installed.

Installation
------------

Install it through normal means, via PyPI or use ``zc.buildout`` to bootstrap
the package and run test units.

31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
External Library Requirements
=============================

To properly install this package, you will need the following C/C++ components
pre-installed:

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
   two.

   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
  55.33.100
  $ pkg-config --modversion bob-io
  2.0.0a3

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.

André Anjos's avatar
André Anjos committed
71
72
73
Documentation
-------------

74
75
76
The latest version of the documentation can be found `here <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.io.video/master/index.html>`_.

Otherwise, you can generate the documentation for this package yourself, after installation, using Sphinx::
André Anjos's avatar
André Anjos committed
77
78
79
80
81
82
83
84
85
86
87

  $ sphinx-build -b html doc sphinx

This shall place in the directory ``sphinx``, the current version for the
documentation of the package.

Usage
-----

In order to enable support for video file reading and writing in your
application, make sure to import this module, before calling
André Anjos's avatar
André Anjos committed
88
:py:func:`bob.io.base.open` or similar::
André Anjos's avatar
André Anjos committed
89

André Anjos's avatar
André Anjos committed
90
91
92
    >>> import bob.io.base
    >>> import bob.io.video
    >>> bob.io.base.open('myfile.avi', 'r')
André Anjos's avatar
André Anjos committed
93
94
95
96
97
98

Testing
-------

You can run a set of tests using the nose test runner::

99
  $ nosetests -sv
André Anjos's avatar
André Anjos committed
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

.. 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::

André Anjos's avatar
André Anjos committed
116
  $ nosetests --with-coverage --cover-package=bob.io.video
André Anjos's avatar
André Anjos committed
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

The ``coverage`` egg must be installed for this to work properly.

Development
-----------

To develop this package, install using ``zc.buildout``, using the buildout
configuration found on the root of the package::

  $ python bootstrap.py
  ...
  $ ./bin/buildout

Tweak the options in ``buildout.cfg`` to disable/enable verbosity and debug
builds.
132
133
134
135

.. Place here references to all citations in lower case
.. _ffmpeg: http://ffmpeg.org
.. _libav: http://libav.org