README.rst 5.79 KB
Newer Older
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
1 2 3 4
.. vim: set fileencoding=utf-8 :
.. Tiago de Freitas Pereira <tiago.pereira@idiap.ch>
.. Mon 20 Jul 2015 16:57:00 CEST

5 6 7 8 9

.. image:: http://img.shields.io/badge/docs-stable-yellow.png
   :target: http://pythonhosted.org/bob/index.html
.. image:: http://img.shields.io/badge/docs-latest-orange.png
   :target: https://www.idiap.ch/software/bob/docs/latest/idiap/bob/master/index.html
10 11
.. image:: https://travis-ci.org/bioidiap/bob.learn.em.svg?branch=v2.3.2
   :target: https://travis-ci.org/idiap/bob?branch=v2.3.2
12 13 14 15 16 17 18
.. image:: https://img.shields.io/badge/github-master-0000c0.png
   :target: https://github.com/idiap/bob/tree/master
.. image:: http://img.shields.io/pypi/v/bob.png
   :target: https://pypi.python.org/pypi/bob
.. image:: http://img.shields.io/pypi/dm/bob.png
   :target: https://pypi.python.org/pypi/bob

Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
19
====================
20
 Bob
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
====================

Bob is a free signal-processing and machine learning toolbox originally
developed by the Biometrics group at `Idiap`_ Research Institute, Switzerland.

The toolbox is written in a mix of `Python`_ and `C++`_ and is designed to be
both efficient and reduce development time. It is composed of a reasonably
large number of `packages`_ that implement tools for image, audio & video
processing, machine learning and pattern recognition.

If just want to use Bob's functionalities on your experiments, you are **not**
supposed to install this package on your machine, but rather `create your own
personalised work environment
<https://github.com/idiap/bob/wiki/Installation>`_ depending on your needs, by
collecting individual sub-packages based on your requirements.

If you are developing Bob packages which are supposed to built along side our
`nightly build system <https://www.idiap.ch/software/bob/buildbot/waterfall>`_,
please read on.

41

Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
42 43 44
Installation
------------

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 71 72 73 74
.. note::
  If you are reading this page through our GitHub portal and not through PyPI,
  note **the development tip of the package may not be stable** or become
  unstable in a matter of moments.

  Go to `http://pypi.python.org/pypi/bob
  <http://pypi.python.org/pypi/bob>`_ to download the latest
  stable version of this package.

There are 2 options you can follow to get this package installed and
operational on your computer: you can use automatic installers like `pip
<http://pypi.python.org/pypi/pip/>`_ (or `easy_install
<http://pypi.python.org/pypi/setuptools>`_) or manually download, unpack and
use `zc.buildout <http://pypi.python.org/pypi/zc.buildout>`_ to create a
virtual work environment just for this package.

Using an automatic installer
============================

Using ``pip`` is the easiest (shell commands are marked with a ``$`` signal)::

  $ pip install bob

You can also do the same with ``easy_install``::

  $ easy_install bob

This will download and install this package plus any other required
dependencies. It will also verify if the version of Bob you have installed
is compatible.
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
75

76 77 78 79 80 81 82 83 84 85 86 87 88 89
This scheme works well with virtual environments by `virtualenv
<http://pypi.python.org/pypi/virtualenv>`_ or if you have root access to your
machine. Otherwise, we recommend you use the next option.

Using ``zc.buildout``
=====================

Download the latest version of this package from `PyPI
<http://pypi.python.org/pypi/bob>`_ and unpack it in your
working area. The installation of the toolkit itself uses `buildout
<http://www.buildout.org/>`_. You don't need to understand its inner workings
to use this package. Here is a recipe to get you started::
  
  $ python bootstrap-buildout.py
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
90 91
  $ ./bin/buildout

92 93 94 95 96 97
These 2 commands should download and install all non-installed dependencies and
get you a fully operational test and development environment.

.. note::
  As per-usual, make sure all external `dependencies`_ are installed on your host
  before trying to compile the whole of Bob.
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
98 99 100 101 102 103 104 105 106 107 108 109 110 111


Documentation
-------------

You can generate the documentation for all packages in this container, after
installation, using Sphinx::

  $ ./bin/sphinx-build . sphinx

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


112 113
For the maintainers
-------------------
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
114

115
In the next subsections we have instructions for the maintainers of the package.
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
116

117 118
Adding a dependency package
===========================
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
119

120 121
   
   To add a package on bob, just append the package name in the file ('requirements.txt').
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142

.. warning::
   Before adding a package to this prototype, please ensure that the package:

   * contains a README clearly indicating how to install the package (including
     external dependencies required). Also, please add package badges for the
     build status and coverage as shown in other packages (even if your package
     is not yet integrated to Travis or Coveralls).

   * Has unit tests.

   * Is integrated with Travis-CI, and correctly tests on that platform (i.e.
     it builds, it tests fine and a documentation can be constructed and tested
     w/o errors)

   * Is integrated with Coveralls for reporting test coverage

   If you don't know how to do this, ask for information on the bob-devel
   mailing list.


143 144
Updating the dependencies
=========================
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
145

146
 If you want to update the version of the dependency packages, run the following commands::
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
147
 
148 149
 $ ./bin/get_versions.py > requirements.txt
 $ git commit requirements.txt -m "Update requeriments" && git push
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
150 151
 

152 153
Removing a dependency package
=============================
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
154

155
   To remove a package on bob, just append the package name in the file ('requirements.txt').
Tiago de Freitas Pereira's avatar
Tiago de Freitas Pereira committed
156 157 158 159 160 161 162 163 164 165 166 167


.. External References

.. _c++: http://www2.research.att.com/~bs/C++.html
.. _python: http://www.python.org
.. _idiap: http://www.idiap.ch
.. _packages: https://github.com/idiap/bob/wiki/Packages
.. _wiki: https://github.com/idiap/bob/wiki
.. _bug tracker: https://github.com/idiap/bob/issues
.. _dependencies: https://github.com/idiap/bob/wiki/Dependencies