Skip to content
Snippets Groups Projects
Commit bcd6469a authored by Amir MOHAMMADI's avatar Amir MOHAMMADI
Browse files

Merge branch 'install' into 'master' 

Improve the installation instructions

Closes #72 and #69

See merge request !72
parents 6add1e4b 567cf5ff
Branches
Tags
1 merge request!72Improve the installation instructions
Pipeline #
Hide whitespace changes
Inline Side-by-side
bob/bio/base/script/preprocess.py
+ 4
− 1
View file @ bcd6469a
......@@ -12,7 +12,10 @@ import numpy
import bob.core
import bob.io.base
import bob.io.image
try:
import bob.io.image
except ImportError:
pass
def command_line_arguments(command_line_parameters):
......
doc/installation.rst
+ 85
− 61
View file @ bcd6469a
......@@ -8,126 +8,152 @@
Installation Instructions
=========================
As noted before, this package is part of the ``bob.bio`` packages, which in turn are part of the signal-processing and machine learning toolbox Bob_.
To install `Packages of Bob <https://www.idiap.ch/software/bob/packages>`_, please read the `Installation Instructions <https://www.idiap.ch/software/bob/install>`_.
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 <https://gitlab.idiap.ch/bob/bob/wikis/Dependencies>`_ for your operating system.
As noted before, this package is part of the ``bob.bio`` packages, which in
turn are part of the signal-processing and machine learning toolbox Bob_. To
install Bob_, please read the `Installation Instructions <bobinstall_>`_.
.. note::
Currently, running Bob_ under MS Windows in not yet supported.
However, we found that running Bob_ in a virtual Unix environment such as the one provided by VirtualBox_ is a good alternative.
Currently, running Bob_ under MS Windows in not yet supported. However, we
found that running Bob_ in a virtual Unix environment such as the one
provided by VirtualBox_ is a good alternative.
Installation via pip
----------------------
The most simple and most convenient way to use the ``bob.bio`` tools is to install it using `pip`.
After setting up your python environment (you can find the instructions `here <https://www.idiap.ch/software/bob/install>`_), use the sequence of commands to
first search the ``bob.bio`` packages and then install it.
Then, to install the ``bob.bio`` packages and in turn maybe the database
packages that you want to use, use conda_ to install them:
.. code-block:: sh
$ pip search bob.bio # searching
$ pip install bob.bio.base # Install the base package
Installation via zc.buildout
----------------------------
Another convenient way to use the ``bob.bio`` tools is to use a ``zc.buildout`` package, as explained in more detail `here <https://www.idiap.ch/software/bob/install#using-zcbuildout-for-production>`__.
There, in the ``eggs`` section of the ``buildout.cfg`` file, simply list the ``bob.bio`` packages that you want, like:
$ conda search bob.bio # searching
$ conda search bob.db # searching
$ conda install bob.bio.base bob.bio.<bioname> bob.db.<dbname>
.. code-block:: python
where you would replace ``<bioname>`` and ``<dbname>`` with the name of
packages that you want to use.
eggs = bob.bio.base
bob.bio.face
bob.bio.gmm
bob.bio.video
bob.db.youtube
gridtk
An example installation
-----------------------
in order to download and install all packages that are required for your experiments.
In the example above, you might want to run a video face recognition experiments using the :py:class:`bob.bio.face.preprocessor.FaceDetect` and the :py:class:`bob.bio.face.extractor.DCTBlocks` feature extractor defined in :ref:`bob.bio.face <bob.bio.face>`, the :py:class:`bob.bio.gmm.algorithm.IVector` algorithm defined in :ref:`bob.bio.gmm <bob.bio.gmm>` and the video extensions defined in :ref:`bob.bio.video <bob.bio.video>`, using the YouTube faces database interface defined in :ref:`bob.db.youtube <bob.db.youtube>`.
Running the simple command line:
For example, you might want to run a video face recognition experiments using
the :py:class:`bob.bio.face.preprocessor.FaceDetect` and the
:py:class:`bob.bio.face.extractor.DCTBlocks` feature extractor defined in
:ref:`bob.bio.face <bob.bio.face>`, the
:py:class:`bob.bio.gmm.algorithm.IVector` algorithm defined in
:ref:`bob.bio.gmm <bob.bio.gmm>` and the video extensions defined in
:ref:`bob.bio.video <bob.bio.video>`, using the YouTube faces database
interface defined in :ref:`bob.db.youtube <bob.db.youtube>`. Running the
command line below will install all the required packages:
.. code-block:: sh
$ buildout
will the download and install all dependent packages locally (relative to your current working directory), and add them to your environment.
$ source activate <bob_conda_environment>
$ conda install bob.bio.base \
bob.bio.face \
bob.bio.gmm \
bob.bio.video \
bob.db.youtube \
gridtk
Databases
---------
With ``bob.bio`` you will run biometric recognition experiments using some default biometric recognition databases.
Though the verification protocols are implemented in ``bob.bio``, the original data are **not included**.
To download the original data of the databases, please refer to the according Web-pages.
For a list of supported databases including their download URLs, please refer to the `verification_databases <https://www.idiap.ch/software/bob/packages>`_.
With ``bob.bio`` you will run biometric recognition experiments using some
default biometric recognition databases. Though the verification protocols are
implemented in ``bob.bio``, the original data are **not included**. To download
the original data of the databases, please refer to the according Web-pages.
For a list of supported databases including their download URLs, please refer
to the `verification_databases <packages_>`_.
After downloading the original data for the databases, you will need to tell ``bob.bio``, where these databases can be found.
For this purpose, we have decided to implement a special file, where you can set your directories.
By default, this file is located in ``~/.bob_bio_databases.txt``, and it contains several lines, each line looking somewhat like:
After downloading the original data for the databases, you will need to tell
``bob.bio``, where these databases can be found. For this purpose, we have
decided to implement a special file, where you can set your directories. By
default, this file is located in ``~/.bob_bio_databases.txt``, and it contains
several lines, each line looking somewhat like:
.. code-block:: text
[YOUR_ATNT_DIRECTORY] = /path/to/your/directory
.. note::
If this file does not exist, feel free to create and populate it yourself.
If this file does not exist, feel free to create and populate it yourself.
Please use ``databases.py`` for a list of known databases, where you can see the raw ``[YOUR_DATABASE_PATH]`` entries for all databases that you haven't updated, and the corrected paths for those you have.
Please use ``databases.py`` for a list of known databases, where you can see
the raw ``[YOUR_DATABASE_PATH]`` entries for all databases that you haven't
updated, and the corrected paths for those you have.
.. note::
If you have installed only ``bob.bio.base``, there is no database listed -- as all databases are included in other packages, such as :ref:`bob.bio.face <bob.bio.face>` or :ref:`bob.bio.spear <bob.bio.spear>`.
If you have installed only ``bob.bio.base``, there is no database listed --
as all databases are included in other packages, such as
:ref:`bob.bio.face <bob.bio.face>` or :ref:`bob.bio.spear <bob.bio.spear>`.
Test your Installation
----------------------
One of the scripts that were generated during the bootstrap/buildout step is a test script.
To verify your installation, you should run the script running the nose tests for each of the ``bob.bio`` packages:
You can also install the ``nose`` package to test your installation and use
that to verify your installation:
.. code-block:: sh
$ conda install nose # install nose
$ nosetests -vs bob.bio.base
$ nosetests -vs bob.bio.gmm
...
Some of the tests that are run require the images of the `AT&T database`_ database.
If the database is not found on your system, it will automatically download and extract the `AT&T database`_ a temporary directory, **which will not be erased**.
You should run the script running the nose tests for each of the ``bob.bio``
packages separately.
.. code-block:: sh
$ nosetests -vs bob.bio.base
$ nosetests -vs bob.bio.gmm
...
Some of the tests that are run require the images of the `AT&T database`_
database. If the database is not found on your system, it will automatically
download and extract the `AT&T database`_ a temporary directory, **which will
not be erased**.
To avoid the download to happen each time you call the nose tests, please:
1. Download the `AT&T database`_ database and extract it to the directory of your choice.
2. Set an environment variable ``ATNT_DATABASE_DIRECTORY`` to the directory, where you extracted the database to.
For example, in a ``bash`` you can call:
1. Download the `AT&T database`_ database and extract it to the directory of
your choice.
2. Set an environment variable ``ATNT_DATABASE_DIRECTORY`` to the directory,
where you extracted the database to. For example, in a ``bash`` you can
call:
.. code-block:: sh
$ export ATNT_DATABASE_DIRECTORY=/path/to/your/copy/of/atnt
.. note::
To set the directory permanently, you can also change the ``atnt_default_directory`` in the file `bob/bio/base/test/utils.py <file:../bob/bio/base/test/utils.py>`_.
In this case, there is no need to set the environment variable any more.
In case any of the tests fail for unexplainable reasons, please send a report through our `mailing list`_.
To set the directory permanently, you can also change the
``atnt_default_directory`` in the file `bob/bio/base/test/utils.py
<file:../bob/bio/base/test/utils.py>`_. In this case, there is no need to set
the environment variable any more.
.. note::
Usually, all tests should pass with the latest stable versions of the Bob_ packages.
In other versions, some of the tests may fail.
In case any of the tests fail for unexplainable reasons, please send a report
through our `mailing list`_.
.. note::
Usually, all tests should pass with the latest stable versions of Bob_
packages. In other versions, some of the tests may fail.
Generate this documentation
---------------------------
Generally, the documentation of this package is `available online <http://pythonhosted.org/bob.bio.base>`__, and this should be your preferred resource.
However, to generate this documentation locally, you call:
Generally, the documentation of this package is
`available online <http://pythonhosted.org/bob.bio.base>`__, and this should be
your preferred resource. However, to generate this documentation locally, you
call:
.. code-block:: sh
$ conda install sphinx # install sphinx
$ sphinx-build doc sphinx
Afterward, the documentation is available and you can read it, e.g., by using:
......@@ -137,6 +163,4 @@ Afterward, the documentation is available and you can read it, e.g., by using:
$ firefox sphinx/index.html
.. _buildout.cfg: file:../buildout.cfg
.. include:: links.rst
doc/links.rst
+ 6
− 3
View file @ bcd6469a
......@@ -4,9 +4,9 @@
.. This file contains all links we use for documentation in a centralized place
.. _idiap: http://www.idiap.ch
.. _bob: http://www.idiap.ch/software/bob
.. _idiap at gitlab: http://gitlab.idiap.ch/bob
.. _idiap: https://www.idiap.ch
.. _bob: https://www.idiap.ch/software/bob
.. _idiap at gitlab: https://gitlab.idiap.ch/bob
.. _at&t database: http://www.cl.cam.ac.uk/research/dtg/attarchive/facedatabase.html
.. _gridtk: https://pypi.python.org/pypi/gridtk
.. _buildout: http://www.buildout.org
......@@ -19,3 +19,6 @@
.. _virtualbox: https://www.virtualbox.org
.. _hdf5: http://www.hdfgroup.org/HDF5
.. _mailing list: https://www.idiap.ch/software/bob/discuss
.. _packages: https://www.idiap.ch/software/bob/packages
.. _bobinstall: https://www.idiap.ch/software/bob/install
.. _conda: https://conda.io
test-requirements.txt
+ 1
− 0
View file @ bcd6469a
......@@ -2,3 +2,4 @@ bob.db.atnt
bob.io.image
matplotlib
gridtk
nose
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment