Massive update with changes from downstream

* Better documentation
 - More complete
 - Focused on the user experience
 - Include resources
* Re-organisation of components into directories corresponding to each bob.bio
  base type: databases, preprocessors, extractors and algorithms.
* Changed old-style resources in favor of configuration files which are also
  resource'd
* Clean-up of unused resources

bob/bio/vein/configurations/verafinger.py

+#!/usr/bin/env python
+#Mon 26 Sep 2016 17:21:42 CEST
+
+"""`VERA Fingervein`_ is a database for biometric fingervein recognition
+
+It consists of 440 images from 110 clients. It was produced at the Idiap
+Research Institute in Martigny and at Haute Ecole Spécialisée de Suisse
+Occidentale in Sion, in Switzerland. The reference citation is [TVM14]_.
+
+You can download the raw data of the `VERA Fingervein`_ database by following
+the link.
+
+.. include:: links.rst
+"""
+
+
+from bob.bio.vein.database import VerafingerBioDatabase
+
+verafinger_directory = "[YOUR_VERAFINGER_DIRECTORY]"
+"""Value of ``~/.bob_bio_databases.txt`` for this database"""
+
+database = VerafingerBioDatabase(original_directory = verafinger_directory)
+"""The :py:class:`bob.bio.base.database.BioDatabase` derivative with Verafinger
+database settings
+
+.. warning::
+
+   This class only provides a programmatic interface to load data in an orderly
+   manner, respecting usage protocols. It does **not** contain the raw
+   datafiles. You should procure those yourself.
+
+Notice that ``original_directory`` is set to ``[YOUR_VERAFINGER_DIRECTORY]``.
+You must make sure to create ``${HOME}/.bob_bio_databases.txt`` setting this
+value to the place where you actually installed the Verafinger Database, as
+explained in the section :ref:`bob.bio.vein.baselines`.
+"""
+
+protocol = 'Nom'
+"""The default protocol to use for tests
+
+You may modify this at runtime by specifying the option ``--protocol`` on the
+command-line of ``verify.py`` or using the keyword ``protocol`` on a
+configuration file that is loaded **after** this configuration resource.
+"""

bob/bio/vein/configurations/wide_line_detector.py

+#!/usr/bin/env python
+# vim: set fileencoding=utf-8 :
+
+'''Huang's Wide-Line Detector and Miura Matching baseline
+
+References:
+
+1. [HDLTL10]_
+2. [TV13]_
+3. [TVM14]_
+
+'''
+
+sub_directory = 'wld'
+"""Sub-directory where results will be placed.
+
+You may change this setting using the ``--sub-directory`` command-line option
+or the attribute ``sub_directory`` in a configuration file loaded **after**
+this resource.
+"""
+
+from ..preprocessor import FingerCrop
+preprocessor = FingerCrop()
+"""Preprocessing using gray-level based finger cropping and no post-processing
+"""
+
+from ..extractor import WideLineDetector
+
+# Radius of the circular neighbourhood region
+RADIUS_NEIGHBOURHOOD_REGION = 5
+NEIGHBOURHOOD_THRESHOLD = 1
+
+#Sum of neigbourhood threshold
+SUM_NEIGHBOURHOOD = 41
+RESCALE = True
+
+extractor = WideLineDetector(
+    radius=RADIUS_NEIGHBOURHOOD_REGION,
+    threshold=NEIGHBOURHOOD_THRESHOLD,
+    g=SUM_NEIGHBOURHOOD,
+    rescale=RESCALE
+    )
+"""Features are the output of the maximum curvature algorithm, as described on
+[HDLTL10]_.
+
+Defaults taken from [TV13]_.
+"""
+
+# Notice the values of ch and cw are different than those from the
+# repeated-line tracking **and** maximum curvature baselines.
+from ..algorithm import MiuraMatch
+algorithm = MiuraMatch(ch=18, cw=28)
+"""Miura-matching algorithm with specific settings for search displacement
+
+Defaults taken from [TV13]_.
+"""

doc/api.rst

@@ -12,27 +12,26 @@ This section contains a listing of all functionality available on this library
 which can be used for vein experiments.
 
 
-Databases
----------
+Database Interfaces
+-------------------
 
-.. automodule:: bob.bio.vein.configurations.databases
+.. automodule:: bob.bio.vein.database
 
 
 Pre-processors
 --------------
 
-.. automodule:: bob.bio.vein.preprocessors
+.. automodule:: bob.bio.vein.preprocessor
 
 
 Feature Extractors
 ------------------
 
-.. automodule:: bob.bio.vein.extractors
+.. automodule:: bob.bio.vein.extractor
 
 
 Matching Algorithms
 -------------------
 
-.. automodule:: bob.bio.vein.algorithms
-
+.. automodule:: bob.bio.vein.algorithm
 

doc/baselines.rst

@@ -46,20 +46,58 @@ In the remainder of this section we introduce baseline experiments you can
 readily run with this tool without further configuration. Baselines examplified
 in this guide were published in [TVM14]_.
 
+Database setups and baselines are encoded using
+:ref:`bob.bio.base.configuration-files`, all stored inside the package root, in
+the directory ``bob/bio/vein/configurations``. Documentation for each resource
+is available on the section :ref:`bob.bio.vein.resources`.
+
+.. warning::
+
+   You **cannot** run experiments just by executing the command line
+   instructions described in this guide. You **need first** to procure yourself
+   the raw data files that correspond to *each* database used here in order to
+   correctly run experiments with those data. Biometric data is considered
+   private date and, under EU regulations, cannot be distributed without a
+   consent or license. You may consult our
+   :ref:`bob.bio.vein.resources.databases` resources section for checking
+   currently supported databases and accessing download links for the raw data
+   files.
+
+   Once the raw data files have been downloaded, particular attention should be
+   given to the directory locations of those. Unpack the databases carefully
+   and annotate the root directory where they have been unpacked.
+
+   Then, carefully read the *Databases* section of
+   :ref:`bob.bio.base.installation` on how to correctly setup the
+   ``~/.bob_bio_databases.txt`` file.
+
+   Use the following keywords on the left side of the assignment (see
+   :ref:`bob.bio.vein.resources.databases`):
+
+   .. code-block:: text
+
+      [YOUR_VERAFINGER_DIRECTORY] = /complete/path/to/verafinger
+      [YOUR_UTFVP_DIRECTORY] = /complete/path/to/utfvp
+      [YOUR_BIOWAVE_TEST_DIRECTORY] = /complete/path/to/biowave_test
+
+   Notice it is rather important to use the strings as described above,
+   otherwise ``bob.bio.base`` will not be able to correctly load your images.
+
+   Once this step is done, you can proceed with the instructions below.
+
 
 Repeated Line-Tracking with Miura Matching
 ==========================================
 
-You can find the description of this method on the paper from Miura *et al.*
-[MNM04]_.
+Detailed description at :ref:`bob.bio.vein.resources.recognition.rlt`.
 
-To run the baseline on the `VERA fingervein`_ database, using the ``NOM``
-protocol (called ``Full`` in [TVM14]_), do the following:
+To run the baseline on the `VERA fingervein`_ database, using the ``Nom``
+protocol, do the following:
 
 
 .. code-block:: sh
 
-   $ ./bin/verify.py --database=verafinger --protocol=NOM --preprocessor=nopp --extractor=repeatedlinetracking --algorithm=match-rlt --sub-directory="rlt" --verbose --verbose
+   $ ./bin/verify.py verafinger rlt -vv
 
 
 .. tip::
@@ -72,62 +110,54 @@ protocol (called ``Full`` in [TVM14]_), do the following:
 This command line selects and runs the following implementations for the
 toolchain:
 
-* Database: Use the base Bob API for the VERA database implementation,
-  protocol variant ``NOM`` which corresponds to the ``Full`` evaluation
-  protocol described in [TVM14]_
-* Preprocessor: Simple finger cropping, with no extra post-processing, as
-  defined in [LLP09]_
-* Feature extractor: Repeated line tracking, as explained in [MNM04]_
-* Matching algorithm: "Miura" matching, as explained on the same paper
-* Subdirectory: This is the subdirectory in which the scores and intermediate
-  results of this baseline will be stored.
-
+* :ref:`bob.bio.vein.resources.database.verafinger`
+* :ref:`bob.bio.vein.resources.recognition.rlt`
 
 As the tool runs, you'll see printouts that show how it advances through
 preprocessing, feature extraction and matching. In a 4-core machine and using
-4 parallel tasks, it takes around 2 hours to process this baseline with the
+4 parallel tasks, it takes around 4 hours to process this baseline with the
 current code implementation.
 
-To complete the evaluation, run the commands bellow, that will output the equal
+To complete the evaluation, run the command bellow, that will output the equal
 error rate (EER) and plot the detector error trade-off (DET) curve with the
 performance:
 
 .. code-block:: sh
 
-   $ ./bin/bob_eval_threshold.py  --scores <path-to>/verafinger/rlt/NOM/nonorm/scores-dev --criterium=eer
-   ('Threshold:', 0.320748535)
-   FAR : 26.478% (12757/48180)
+   $ ./bin/bob_eval_threshold.py  --scores <path-to>/verafinger/rlt/Nom/nonorm/scores-dev --criterium=eer
+   ('Threshold:', 0.32045327)
+   FAR : 26.362% (12701/48180)
    FRR : 26.364% (58/220)
-   HTER: 26.421%
+   HTER: 26.363%
 
 
 Maximum Curvature with Miura Matching
 =====================================
 
-You can find the description of this method on the paper from Miura *et al.*
-[MNM05]_.
+Detailed description at :ref:`bob.bio.vein.resources.recognition.mc`.
 
-To run the baseline on the `VERA fingervein`_ database, using the ``NOM``
+To run the baseline on the `VERA fingervein`_ database, using the ``Nom``
 protocol like above, do the following:
 
 
 .. code-block:: sh
 
-   $ ./bin/verify.py --database=verafinger --protocol=NOM --preprocessor=nopp --extractor=maximumcurvature --algorithm=match-mc --sub-directory="mc" --verbose --verbose
+   $ ./bin/verify.py verafinger mc -vv
 
 
 This command line selects and runs the following implementations for the
-toolchain, with comparison to the previous baseline:
+toolchain:
 
-* Feature extractor: Maximum Curvature, as explained in [MNM05]_
+* :ref:`bob.bio.vein.resources.database.verafinger`
+* :ref:`bob.bio.vein.resources.recognition.mc`
 
 In a 4-core machine and using 4 parallel tasks, it takes around 1 hour and 40
-minutes to process this baseline with the current code implementation.  Results
+minutes to process this baseline with the current code implementation. Results
 we obtained:
 
 .. code-block:: sh
 
-   $ ./bin/bob_eval_threshold.py  --scores <path-to>/verafinger/mc/NOM/nonorm/scores-dev --criterium=eer
+   $ ./bin/bob_eval_threshold.py  --scores <path-to>/verafinger/mc/Nom/nonorm/scores-dev --criterium=eer
    ('Threshold:', 0.078274325)
    FAR : 3.182% (1533/48180)
    FRR : 3.182% (7/220)
@@ -146,17 +176,18 @@ protocol like above, do the following:
 
 .. code-block:: sh
 
-   $ ./bin/verify.py --database=verafinger --protocol=NOM --preprocessor=nopp --extractor=widelinedetector --algorithm=match-wld --sub-directory="wld" --verbose --verbose
+   $ ./bin/verify.py verafinger wld -vv
 
 
 This command line selects and runs the following implementations for the
-toolchain, with comparison to the previous baseline:
+toolchain:
 
-* Feature extractor: Wide Line Detector, as explained in [HDLTL10]_
+* :ref:`bob.bio.vein.resources.database.verafinger`
+* :ref:`bob.bio.vein.resources.recognition.wld`
 
 In a 4-core machine and using 4 parallel tasks, it takes only around 5 minutes
-minutes to process this baseline with the current code implementation.
-Results we obtained:
+minutes to process this baseline with the current code implementation.Results
+we obtained:
 
 .. code-block:: sh
 
@@ -190,23 +221,4 @@ Wide Line Detector           None                                10.4
 WLD + HEQ (preproc) @ Vera/Full = 10.9%
 
 
-Available Resources
--------------------
-
-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``.
-
-For available resources:
-
-  .. code-block:: sh
-
-     $ ./bin/resources.py --packages=bob.bio.vein
-
-For a detailed explanation and the configurability of each resource, consult
-:ref:`bob.bio.vein.api`.
-
-
 .. include:: links.rst

doc/index.rst

@@ -24,7 +24,9 @@ Users Guide
    installation
    baselines
    references
+   resources
    api
 
+.. todolist::
 
 .. include:: links.rst

doc/links.rst

@@ -18,7 +18,6 @@
 .. _virtualbox: https://www.virtualbox.org
 .. _hdf5: http://www.hdfgroup.org/HDF5
 .. _vera fingervein: https://www.idiap.ch/dataset/vera-fingervein
-.. _vera palmvein: https://www.idiap.ch/dataset/vera-palmvein
 .. _utfvp: http://scs.ewi.utwente.nl/downloads/show,Finger%20Vein/
 .. _put: http://biometrics.put.poznan.pl/vein-dataset/
 .. _installation: https://gitlab.idiap.ch/bob/bob/wikis/Installation

doc/references.rst

@@ -22,3 +22,5 @@
 .. [MD13] *L. Mirmohamadsadeghi and A. Drygajlo*, **Palm vein recognition using local texture patterns**, IET Biometrics, pp. 1-9, 2013.
 
 .. [TVM14] *Pedro Tome, Matthias Vanoni and Sébastien Marcel*, **On the Vulnerability of Finger Vein Recognition to Spoofing**, in: IEEE International Conference of the Biometrics Special Interest Group (BIOSIG), Darmstadt, Germay, pages 1 - 10, IEEE, 2014
+
+.. [TV13] *B. Ton and R. Veldhuis*, **A high quality finger vascular pattern dataset collected using a custom designed capturing device**, in: IAPR International Conference on Biometrics (ICB), 2013.

doc/resources.rst

+.. vim: set fileencoding=utf-8 :
+.. Mon 11 Jul 2016 16:39:15 CEST
+
+
+.. _bob.bio.vein.resources:
+
+===========
+ Resources
+===========
+
+This section contains a listing of all ready-to-use resources you can find in
+this package. Each module may contain references different resource types,
+including ``database``, ``preprocessor``, ``extractor`` and ``algorithm``. By
+combining *complementary* resources, you can run baseline experiments as
+explained on :ref:`bob.bio.vein.baselines`.
+
+
+.. _bob.bio.vein.resources.databases:
+
+Databases
+---------
+
+These resources represent configuration files containing at least settings for
+the following runtime attributes of ``./bin/verify.py``:
+
+  * ``database``
+  * ``protocol``
+
+
+.. _bob.bio.vein.resources.database.verafinger:
+
+Verafinger Database
+===================
+
+.. automodule:: bob.bio.vein.configurations.verafinger
+   :members:
+
+
+.. _bob.bio.vein.resources.database.utfvp:
+
+UTFVP Database
+==============
+
+.. automodule:: bob.bio.vein.configurations.utfvp
+   :members:
+
+
+.. _bob.bio.vein.resources.database.biowave_test:
+
+Biowave Test Database
+=====================
+
+.. automodule:: bob.bio.vein.configurations.biowave_test
+   :members:
+
+
+.. _bob.bio.vein.resources.recognition:
+
+Recognition Systems
+-------------------
+
+These resources represent configuration files containing at least settings for
+the following runtime attributes of ``./bin/verify.py``:
+
+  * ``sub_directory``
+  * ``preprocessor``
+  * ``extractor``
+  * ``algorithm``
+
+
+.. _bob.bio.vein.resources.recognition.rlt:
+
+Repeated Line Tracking and Miura Matching
+=========================================
+
+.. automodule:: bob.bio.vein.configurations.repeated_line_tracking
+   :members:
+
+
+.. _bob.bio.vein.resources.recognition.mc:
+
+Maximum Curvature and Miura Matching
+====================================
+
+.. automodule:: bob.bio.vein.configurations.maximum_curvature
+   :members:
+
+
+.. _bob.bio.vein.resources.recognition.wld:
+
+Wide-Line Detector and Miura Matching
+=====================================
+
+.. automodule:: bob.bio.vein.configurations.wide_line_detector
+   :members:
+
+
+Other Resources
+---------------
+
+Other resources which include configuration parameters for circumstantial
+usage.
+
+.. _bob.bio.vein.resources.parallel:
+
+
+Parallel Running
+================
+
+.. automodule:: bob.bio.vein.configurations.parallel
+   :members:
+

setup.py

@@ -31,35 +31,19 @@ setup(
 
     entry_points={
 
-      'bob.bio.database': [
-        'verafinger = bob.bio.vein.configurations.database.verafinger:database',
-        'utfvp = bob.bio.vein.configurations.database.utfvp:database',
-        ],
-
-      'bob.bio.preprocessor': [
-        'nopp = bob.bio.vein.configurations.preprocessors:none',
-        'histeq = bob.bio.vein.configurations.preprocessors:he',
-        'highfreq = bob.bio.vein.configurations.preprocessors:hfe',
-        'circgabor = bob.bio.vein.configurations.preprocessors:circgabor',
-        ],
-
-      'bob.bio.extractor': [
-        'normalisedcrosscorr = bob.bio.vein.configurations.extractors.normalised_crosscorr:feature_extractor',
-        'maximumcurvature = bob.bio.vein.configurations.extractors.maximum_curvature:feature_extractor',
-        'repeatedlinetracking = bob.bio.vein.configurations.extractors.repeated_line_tracking:feature_extractor',
-        'widelinedetector = bob.bio.vein.configurations.extractors.wide_line_detector:feature_extractor',
-        'localbinarypatterns = bob.bio.vein.configurations.extractors.lbp:feature_extractor',
-        ],
-
-      'bob.bio.algorithm': [
-        'match-wld = bob.bio.vein.configurations.algorithms:huangwl',
-        'match-mc = bob.bio.vein.configurations.algorithms:miuramax',
-        'match-rlt = bob.bio.vein.configurations.algorithms:miurarlt',
-        #'match-lbp = bob.bio.face.configurations.algorithms.lgbphs:tool',
-        ],
-
-      'bob.bio.grid': [
-        'idiap = bob.bio.vein.configurations.grid:default',
+      'bob.bio.config': [
+        # databases
+        'verafinger = bob.bio.vein.configurations.verafinger',
+        'utfvp = bob.bio.vein.configurations.utfvp',
+        'biowave_test = bob.bio.vein.configurations.biowave_test',
+
+        # baselines
+        'mc = bob.bio.vein.configurations.maximum_curvature',
+        'rlt = bob.bio.vein.configurations.repeated_line_tracking',
+        'wld = bob.bio.vein.configurations.wide_line_detector',
+
+        # other
+        'parallel = bob.bio.vein.configurations.parallel',
         ],
 
       },