baselines.rst 4.35 KB
Newer Older
André Anjos's avatar
André Anjos committed
1 2 3 4 5 6 7 8 9 10 11 12 13
.. vim: set fileencoding=utf-8 :
.. date: Thu Sep 20 11:58:57 CEST 2012

.. _bob.bio.vein.baselines:

===============================
 Executing Baseline Algorithms
===============================

The first thing you might want to do is to execute one of the vein
recognition algorithms that are implemented in ``bob.bio.vein``.


14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
Setting up Databases
--------------------

In order to run vein recognition algorithms using this package, you'll need to
make sure to download the raw files corresponding to the databases you'd like
to process. The raw files are not distributed with Bob_ software as biometric
data is, to most countries, considered sensible data that cannot be obtained
without explicit licensing from a data controller. You must visit the websites
below, sign the license agreements and then download the data before trying out
to run the baselines.

.. note::

   If you're at the Idiap Research Institute in Switzlerand, the datasets in
   the baselines mentioned in this guide are already downloaded and
   pre-installed on our shared file system. You don't need to re-download
   databases or create a ``~/.bob_bio_databases.txt`` file.


The current system readily supports the following freely available datasets:
André Anjos's avatar
André Anjos committed
34

35 36 37
* ``vera``: `Vera Fingervein`_
* ``utfvp``: `UTFVP`_
* ``put``: `PUT`_ Vein Dataset
André Anjos's avatar
André Anjos committed
38

39 40 41 42 43

After downloading the databases, annotate the base directories in which they
are installed. Then, follow the instructions in
:ref:`bob.bio.base.installation` to let this framework know where databases are
located on your system.
André Anjos's avatar
André Anjos committed
44 45 46 47 48 49 50 51 52 53 54 55 56 57


Running Baseline Experiments
----------------------------

To run the baseline experiments, you can use the ``./bin/verify.py`` script by
just going to the console and typing:

.. code-block:: sh

   $ ./bin/verify.py


This script is explained in more detail in :ref:`bob.bio.base.experiments`.
58 59
The ``./bin/verify.py --help`` option shows you, which other options you can
set.
André Anjos's avatar
André Anjos committed
60 61

Usually it is a good idea to have at least verbose level 2 (i.e., calling
62 63
``./bin/verify.py --verbose --verbose``, or the short version ``./bin/verify.py
-vv``).
André Anjos's avatar
André Anjos committed
64

65
.. note:: **Running in Parallel**
André Anjos's avatar
André Anjos committed
66

67 68 69
   To run the experiments in parallel, you can define an SGE grid or local host
   (multi-processing) configurations as explained in
   :ref:`running_in_parallel`.
André Anjos's avatar
André Anjos committed
70

71 72 73 74
   In short, to run in the Idiap SGE grid, you can simply add the ``--grid``
   command line option, without parameters. To run experiments in parallel on
   the local machine, simply add a ``--parallel <N>`` option, where ``<N>``
   specifies the number of parallel jobs you want to execute.
André Anjos's avatar
André Anjos committed
75 76


77 78
In the remainder of this section we introduce baseline experiments you can
readily run with this tool without further configuration.
André Anjos's avatar
André Anjos committed
79 80


81 82
Repeated Line-Tracking with Miura Matching
==========================================
André Anjos's avatar
André Anjos committed
83

84 85
You can find the description of this method on the paper from Miura *et al.*
[MNM04]_.
André Anjos's avatar
André Anjos committed
86

André Anjos's avatar
André Anjos committed
87
To run the baseline on the `VERA fingervein`_ database, using the ``1vsAll``
88
protocol (1-fold cross-validation), do the following:
André Anjos's avatar
André Anjos committed
89

90
.. code-block:: sh
André Anjos's avatar
André Anjos committed
91

92
   ./bin/verify.py --database=vera --protocol=1vsAll --preprocessor=none --extractor=repeatedlinetracking --algorithm=match-rlt --sub-directory="vera-1vsall-mnm04" --verbose --verbose
André Anjos's avatar
André Anjos committed
93

94
This command line selects the following implementations for the toolchain:
André Anjos's avatar
André Anjos committed
95

96 97 98 99 100 101
  * Database: Use the base Bob API for the VERA database implementation,
    protocol variant ``1vsAll`` which corresponds to the 1-fold
    cross-validation evaluation protocol described in [TVM14]_
  * Preprocessor: Simple finger cropping, with no extra pre-processing
  * Feature extractor: Repeated line tracking, as explained in [MNM04]_
  * Matching algorithm: "Miura" matching, as explained on the same paper
André Anjos's avatar
André Anjos committed
102

103 104
As the tool runs, you'll see printouts that show how it advances through
preprocessing, feature extraction and matching.
André Anjos's avatar
André Anjos committed
105 106


107 108
Available Resources
-------------------
André Anjos's avatar
André Anjos committed
109

110 111 112 113 114
This package provides various different ``bob.bio.base`` resource
configurations to handle a variety of techniques in vein recognition: database
adaptors, preprocessors (cropping and illumination
normalization), feature extractors and matching algorithms. In order to list
each contribution, use the script ``./bin/resources.py``.
André Anjos's avatar
André Anjos committed
115

116
For available resources:
André Anjos's avatar
André Anjos committed
117

118
  .. code-block:: sh
André Anjos's avatar
André Anjos committed
119

120
     $ ./bin/resources.py --packages=bob.bio.vein
André Anjos's avatar
André Anjos committed
121

122 123
For a detailed explanation and the configurability of each resource, consult
:ref:`bob.bio.vein.api`.
André Anjos's avatar
André Anjos committed
124 125 126


.. include:: links.rst