From 38ac1db81e3f79606ca2562cb9d9f62c86d97cbd Mon Sep 17 00:00:00 2001
From: Andre Anjos <andre.anjos@idiap.ch>
Date: Tue, 27 Sep 2016 16:31:43 +0200
Subject: [PATCH] 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
---
.../HammingDistance.py | 0
.../{algorithms => algorithm}/MiuraMatch.py | 1 -
.../{algorithms => algorithm}/__init__.py | 0
bob/bio/vein/configurations/algorithms.py | 8 --
bob/bio/vein/configurations/biowave_test.py | 41 ++++++
.../vein/configurations/database/__init__.py | 0
.../configurations/database/biowave_test.py | 11 --
bob/bio/vein/configurations/database/utfvp.py | 11 --
.../configurations/database/verafinger.py | 11 --
.../configurations/extractors/__init__.py | 0
bob/bio/vein/configurations/extractors/lbp.py | 40 ------
.../extractors/maximum_curvature.py | 5 -
.../extractors/normalised_crosscorr.py | 6 -
.../extractors/repeated_line_tracking.py | 20 ---
.../extractors/wide_line_detector.py | 20 ---
bob/bio/vein/configurations/grid.py | 24 ----
.../vein/configurations/maximum_curvature.py | 42 +++++++
bob/bio/vein/configurations/parallel.py | 29 +++++
bob/bio/vein/configurations/preprocessors.py | 8 --
.../configurations/repeated_line_tracking.py | 54 ++++++++
bob/bio/vein/configurations/utfvp.py | 44 +++++++
bob/bio/vein/configurations/verafinger.py | 44 +++++++
.../vein/configurations/wide_line_detector.py | 56 +++++++++
.../LocalBinaryPatterns.py | 0
.../MaximumCurvature.py | 0
.../NormalisedCrossCorrelation.py | 0
.../PrincipalCurvature.py | 0
.../RepeatedLineTracking.py | 0
.../WideLineDetector.py | 0
.../{extractors => extractor}/__init__.py | 0
.../FingerCrop.py | 0
.../__init__.py | 0
doc/api.rst | 13 +-
doc/baselines.rst | 118 ++++++++++--------
doc/index.rst | 2 +
doc/links.rst | 1 -
doc/references.rst | 2 +
doc/resources.rst | 112 +++++++++++++++++
setup.py | 42 ++-----
39 files changed, 510 insertions(+), 255 deletions(-)
rename bob/bio/vein/{algorithms => algorithm}/HammingDistance.py (100%)
rename bob/bio/vein/{algorithms => algorithm}/MiuraMatch.py (95%)
rename bob/bio/vein/{algorithms => algorithm}/__init__.py (100%)
delete mode 100644 bob/bio/vein/configurations/algorithms.py
create mode 100644 bob/bio/vein/configurations/biowave_test.py
delete mode 100644 bob/bio/vein/configurations/database/__init__.py
delete mode 100644 bob/bio/vein/configurations/database/biowave_test.py
delete mode 100644 bob/bio/vein/configurations/database/utfvp.py
delete mode 100644 bob/bio/vein/configurations/database/verafinger.py
delete mode 100644 bob/bio/vein/configurations/extractors/__init__.py
delete mode 100644 bob/bio/vein/configurations/extractors/lbp.py
delete mode 100644 bob/bio/vein/configurations/extractors/maximum_curvature.py
delete mode 100644 bob/bio/vein/configurations/extractors/normalised_crosscorr.py
delete mode 100644 bob/bio/vein/configurations/extractors/repeated_line_tracking.py
delete mode 100644 bob/bio/vein/configurations/extractors/wide_line_detector.py
delete mode 100644 bob/bio/vein/configurations/grid.py
create mode 100644 bob/bio/vein/configurations/maximum_curvature.py
create mode 100644 bob/bio/vein/configurations/parallel.py
delete mode 100644 bob/bio/vein/configurations/preprocessors.py
create mode 100644 bob/bio/vein/configurations/repeated_line_tracking.py
create mode 100644 bob/bio/vein/configurations/utfvp.py
create mode 100644 bob/bio/vein/configurations/verafinger.py
create mode 100644 bob/bio/vein/configurations/wide_line_detector.py
rename bob/bio/vein/{extractors => extractor}/LocalBinaryPatterns.py (100%)
rename bob/bio/vein/{extractors => extractor}/MaximumCurvature.py (100%)
rename bob/bio/vein/{extractors => extractor}/NormalisedCrossCorrelation.py (100%)
rename bob/bio/vein/{extractors => extractor}/PrincipalCurvature.py (100%)
rename bob/bio/vein/{extractors => extractor}/RepeatedLineTracking.py (100%)
rename bob/bio/vein/{extractors => extractor}/WideLineDetector.py (100%)
rename bob/bio/vein/{extractors => extractor}/__init__.py (100%)
rename bob/bio/vein/{preprocessors => preprocessor}/FingerCrop.py (100%)
rename bob/bio/vein/{preprocessors => preprocessor}/__init__.py (100%)
create mode 100644 doc/resources.rst
diff --git a/bob/bio/vein/algorithms/HammingDistance.py b/bob/bio/vein/algorithm/HammingDistance.py
similarity index 100%
rename from bob/bio/vein/algorithms/HammingDistance.py
rename to bob/bio/vein/algorithm/HammingDistance.py
diff --git a/bob/bio/vein/algorithms/MiuraMatch.py b/bob/bio/vein/algorithm/MiuraMatch.py
similarity index 95%
rename from bob/bio/vein/algorithms/MiuraMatch.py
rename to bob/bio/vein/algorithm/MiuraMatch.py
index 3f22338..d848e29 100644
--- a/bob/bio/vein/algorithms/MiuraMatch.py
+++ b/bob/bio/vein/algorithm/MiuraMatch.py
@@ -21,7 +21,6 @@ class MiuraMatch (Algorithm):
"""
def __init__(self,
- # some similarity functions might need a GaborWaveletTransform class, so we have to provide the parameters here as well...
ch = 8, # Maximum search displacement in y-direction
cw = 5, # Maximum search displacement in x-direction
):
diff --git a/bob/bio/vein/algorithms/__init__.py b/bob/bio/vein/algorithm/__init__.py
similarity index 100%
rename from bob/bio/vein/algorithms/__init__.py
rename to bob/bio/vein/algorithm/__init__.py
diff --git a/bob/bio/vein/configurations/algorithms.py b/bob/bio/vein/configurations/algorithms.py
deleted file mode 100644
index 21d8f6e..0000000
--- a/bob/bio/vein/configurations/algorithms.py
+++ /dev/null
@@ -1,8 +0,0 @@
-#!/usr/bin/env python
-# vim: set fileencoding=utf-8 :
-
-from ..algorithms import MiuraMatch
-
-huangwl = MiuraMatch(ch=18, cw=28)
-miuramax = MiuraMatch(ch=80, cw=90)
-miurarlt = MiuraMatch(ch=65, cw=55)
diff --git a/bob/bio/vein/configurations/biowave_test.py b/bob/bio/vein/configurations/biowave_test.py
new file mode 100644
index 0000000..afb5257
--- /dev/null
+++ b/bob/bio/vein/configurations/biowave_test.py
@@ -0,0 +1,41 @@
+#!/usr/bin/env python
+
+"""Not yet documented
+
+.. todo::
+
+ Document this module
+
+"""
+
+from bob.bio.vein.database import BiowaveTestBioDatabase
+
+biowave_test_image_directory = "[YOUR_BIOWAVE_TEST_DIRECTORY]"
+"""Not yet documented
+
+.. todo::
+
+ Document this attribute
+
+"""
+
+database = BiowaveTestBioDatabase(
+ original_directory=biowave_test_image_directory,
+ original_extension='.png',
+)
+"""Not yet documented
+
+.. todo::
+
+ Document this attribute
+
+"""
+
+protocol = 'all'
+"""Not yet documented
+
+.. todo::
+
+ Document this attribute
+
+"""
diff --git a/bob/bio/vein/configurations/database/__init__.py b/bob/bio/vein/configurations/database/__init__.py
deleted file mode 100644
index e69de29..0000000
diff --git a/bob/bio/vein/configurations/database/biowave_test.py b/bob/bio/vein/configurations/database/biowave_test.py
deleted file mode 100644
index 0fd6d9b..0000000
--- a/bob/bio/vein/configurations/database/biowave_test.py
+++ /dev/null
@@ -1,11 +0,0 @@
-#!/usr/bin/env python
-
-from bob.bio.vein.database import BiowaveTestBioDatabase
-
-biowave_test_image_directory = "[YOUR_BIOWAVE_TEST_IMAGE_DIRECTORY]"
-
-database = BiowaveTestBioDatabase(
- original_directory=biowave_test_image_directory,
- original_extension='.png',
- protocol='all'
-)
diff --git a/bob/bio/vein/configurations/database/utfvp.py b/bob/bio/vein/configurations/database/utfvp.py
deleted file mode 100644
index 87e5b24..0000000
--- a/bob/bio/vein/configurations/database/utfvp.py
+++ /dev/null
@@ -1,11 +0,0 @@
-#!/usr/bin/env python
-
-from bob.bio.vein.database import UtfvpBioDatabase
-
-utfvp_directory = "[YOUR_UTFVP_DIRECTORY]"
-
-database = UtfvpBioDatabase(
- original_directory = utfvp_directory,
- extension = ".png",
- )
-
diff --git a/bob/bio/vein/configurations/database/verafinger.py b/bob/bio/vein/configurations/database/verafinger.py
deleted file mode 100644
index 4c5228b..0000000
--- a/bob/bio/vein/configurations/database/verafinger.py
+++ /dev/null
@@ -1,11 +0,0 @@
-#!/usr/bin/env python
-
-from bob.bio.vein.database import VerafingerBioDatabase
-
-vera_finger_directory = "[YOUR_VERAFINGER_DIRECTORY]"
-
-database = VerafingerBioDatabase(
- original_directory = vera_finger_directory,
- original_extension = '.png',
- )
-
diff --git a/bob/bio/vein/configurations/extractors/__init__.py b/bob/bio/vein/configurations/extractors/__init__.py
deleted file mode 100644
index e69de29..0000000
diff --git a/bob/bio/vein/configurations/extractors/lbp.py b/bob/bio/vein/configurations/extractors/lbp.py
deleted file mode 100644
index 7d39059..0000000
--- a/bob/bio/vein/configurations/extractors/lbp.py
+++ /dev/null
@@ -1,40 +0,0 @@
-#!/usr/bin/env python
-# vim: set fileencoding=utf-8 :
-
-from ...extractors import LocalBinaryPatterns
-
-# Parameters
-
-BLOCK_SIZE = 59 # one or two parameters for block size
-BLOCK_OVERLAP = 15 # one or two parameters for block overlap
-
-
-# LBP parameters
-LBP_RADIUS = 16
-LBP_NEIGHBOR_COUNT = 16
-LBP_UNIFORM = True
-LBP_CIRCULAR = True
-LBP_ROTATION_INVARIANT = False
-LBP_COMPARE_TO_AVERAGE = False
-LBP_ADD_AVERAGE = False
-
-# histogram options
-SPARSE_HISTOGRAM = False
-SPLIT_HISTOGRAM = None
-
-
-#Define feature extractor
-feature_extractor = LocalBinaryPatterns(
- block_size=BLOCK_SIZE, # one or two parameters for block size
- block_overlap=BLOCK_OVERLAP, # one or two parameters for block overlap
- lbp_radius=LBP_RADIUS,
- lbp_neighbor_count=LBP_NEIGHBOR_COUNT,
- lbp_uniform=LBP_UNIFORM,
- lbp_circular=LBP_CIRCULAR,
- lbp_rotation_invariant=LBP_ROTATION_INVARIANT,
- lbp_compare_to_average=LBP_COMPARE_TO_AVERAGE,
- lbp_add_average=LBP_ADD_AVERAGE,
- # histogram options
- sparse_histogram=SPARSE_HISTOGRAM,
- split_histogram=SPLIT_HISTOGRAM
-)
diff --git a/bob/bio/vein/configurations/extractors/maximum_curvature.py b/bob/bio/vein/configurations/extractors/maximum_curvature.py
deleted file mode 100644
index 96203b3..0000000
--- a/bob/bio/vein/configurations/extractors/maximum_curvature.py
+++ /dev/null
@@ -1,5 +0,0 @@
-#!/usr/bin/env python
-# vim: set fileencoding=utf-8 :
-
-from ...extractors import MaximumCurvature
-feature_extractor = MaximumCurvature(sigma = 5)
diff --git a/bob/bio/vein/configurations/extractors/normalised_crosscorr.py b/bob/bio/vein/configurations/extractors/normalised_crosscorr.py
deleted file mode 100644
index 8d3166e..0000000
--- a/bob/bio/vein/configurations/extractors/normalised_crosscorr.py
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/usr/bin/env python
-# vim: set fileencoding=utf-8 :
-
-from ...extractors import NormalisedCrossCorrelation
-
-feature_extractor = NormalisedCrossCorrelation()
diff --git a/bob/bio/vein/configurations/extractors/repeated_line_tracking.py b/bob/bio/vein/configurations/extractors/repeated_line_tracking.py
deleted file mode 100644
index 0d22b40..0000000
--- a/bob/bio/vein/configurations/extractors/repeated_line_tracking.py
+++ /dev/null
@@ -1,20 +0,0 @@
-#!/usr/bin/env python
-# vim: set fileencoding=utf-8 :
-
-from ...extractors import RepeatedLineTracking
-
-# Maximum number of iterations
-NUMBER_ITERATIONS = 3000
-
-# Distance between tracking point and cross section of profile
-DISTANCE_R = 1
-
-# Width of profile
-PROFILE_WIDTH = 21
-
-
-feature_extractor = RepeatedLineTracking(
- iterations=NUMBER_ITERATIONS,
- r=DISTANCE_R,
- profile_w=PROFILE_WIDTH
- )
diff --git a/bob/bio/vein/configurations/extractors/wide_line_detector.py b/bob/bio/vein/configurations/extractors/wide_line_detector.py
deleted file mode 100644
index d838c9f..0000000
--- a/bob/bio/vein/configurations/extractors/wide_line_detector.py
+++ /dev/null
@@ -1,20 +0,0 @@
-#!/usr/bin/env python
-# vim: set fileencoding=utf-8 :
-
-from ...extractors import WideLineDetector
-
-# Radius of the circular neighbourhood region
-RADIUS_NEIGHBOURHOOD_REGION = 5
-NEIGHBOURHOOD_THRESHOLD = 1
-
-#Sum of neigbourhood threshold
-SUM_NEIGHBOURHOOD = 41
-RESCALE = True
-
-
-feature_extractor = WideLineDetector(
- radius=RADIUS_NEIGHBOURHOOD_REGION,
- threshold=NEIGHBOURHOOD_THRESHOLD,
- g=SUM_NEIGHBOURHOOD,
- rescale=RESCALE
- )
diff --git a/bob/bio/vein/configurations/grid.py b/bob/bio/vein/configurations/grid.py
deleted file mode 100644
index 7939d23..0000000
--- a/bob/bio/vein/configurations/grid.py
+++ /dev/null
@@ -1,24 +0,0 @@
-#!/usr/bin/env python
-# vim: set fileencoding=utf-8 :
-
-from bob.bio.base.grid import Grid
-
-# our preferred grid setup for Idiap
-default = Grid(
- training_queue='32G',
-
- number_of_preprocessing_jobs=200,
- preprocessing_queue='4G',
-
- number_of_extraction_jobs=200,
- extraction_queue='8G',
-
- number_of_projection_jobs=200,
- projection_queue='8G',
-
- number_of_enrollment_jobs=10,
- enrollment_queue='8G',
-
- number_of_scoring_jobs=10,
- scoring_queue='8G',
- )
diff --git a/bob/bio/vein/configurations/maximum_curvature.py b/bob/bio/vein/configurations/maximum_curvature.py
new file mode 100644
index 0000000..41afc72
--- /dev/null
+++ b/bob/bio/vein/configurations/maximum_curvature.py
@@ -0,0 +1,42 @@
+#!/usr/bin/env python
+# vim: set fileencoding=utf-8 :
+
+'''Maximum Curvature and Miura Matching baseline
+
+References:
+
+1. [MNM05]_
+2. [TV13]_
+3. [TVM14]_
+
+'''
+
+sub_directory = 'mc'
+"""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 MaximumCurvature
+extractor = MaximumCurvature(sigma = 5)
+"""Features are the output of the maximum curvature algorithm, as described on
+[MNM05]_.
+
+Defaults taken from [TV13]_.
+"""
+
+# Notice the values of ch and cw are different than those from the
+# repeated-line tracking baseline.
+from ..algorithm import MiuraMatch
+algorithm = MiuraMatch(ch=80, cw=90)
+"""Miura-matching algorithm with specific settings for search displacement
+
+Defaults taken from [TV13]_.
+"""
diff --git a/bob/bio/vein/configurations/parallel.py b/bob/bio/vein/configurations/parallel.py
new file mode 100644
index 0000000..c0ab155
--- /dev/null
+++ b/bob/bio/vein/configurations/parallel.py
@@ -0,0 +1,29 @@
+#!/usr/bin/env python
+# vim: set fileencoding=utf-8 :
+
+"""Sets-up parallel processing using all available processors"""
+
+import multiprocessing
+parallel = multiprocessing.cpu_count()
+"""The number of processes to spawn for a given run
+
+The default is the value returned by :py:func:`multiprocessing.cpu_count` on
+**your** machine (disregard the value above). If you want to tune it, using the
+``--parallel`` command-line option or the attribute ``parallel`` on a
+configuration file read **after** this one.
+"""
+
+nice = 10
+"""Operating system priority (the higher the smaller)
+
+This value controls the execution priority for jobs launched by a run of
+the verification scripts. By default, jobs would be launched with priority of
+zero if this setting is not in place. By increasing the value (i.e., reducing
+the priority of spawn processes), existing programs already running on your
+desktop (such as your web browser) will have more priority and won't become
+irresponsive.
+
+Setting this value is optional, but you cannot set it to value smaller than
+zero (the default). The maximum is 19. You may read the manual for `renice` for
+more information about this setting.
+"""
diff --git a/bob/bio/vein/configurations/preprocessors.py b/bob/bio/vein/configurations/preprocessors.py
deleted file mode 100644
index f285002..0000000
--- a/bob/bio/vein/configurations/preprocessors.py
+++ /dev/null
@@ -1,8 +0,0 @@
-#!/usr/bin/env python
-# vim: set fileencoding=utf-8 :
-
-from ..preprocessors import FingerCrop
-none = FingerCrop()
-he = FingerCrop(postprocessing='HE')
-hfe = FingerCrop(postprocessing='HFE')
-circgabor = FingerCrop(postprocessing='CircGabor')
diff --git a/bob/bio/vein/configurations/repeated_line_tracking.py b/bob/bio/vein/configurations/repeated_line_tracking.py
new file mode 100644
index 0000000..df4b124
--- /dev/null
+++ b/bob/bio/vein/configurations/repeated_line_tracking.py
@@ -0,0 +1,54 @@
+#!/usr/bin/env python
+# vim: set fileencoding=utf-8 :
+
+'''Repeated-Line Tracking and Miura Matching baseline
+
+References:
+
+1. [MNM04]_
+2. [TV13]_
+3. [TVM14]_
+
+'''
+
+sub_directory = 'rlt'
+"""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 RepeatedLineTracking
+
+# Maximum number of iterations
+NUMBER_ITERATIONS = 3000
+
+# Distance between tracking point and cross section of profile
+DISTANCE_R = 1
+
+# Width of profile
+PROFILE_WIDTH = 21
+
+extractor = RepeatedLineTracking(
+ iterations=NUMBER_ITERATIONS,
+ r=DISTANCE_R,
+ profile_w=PROFILE_WIDTH,
+ seed=0, #Sets numpy.random.seed() to this value
+ )
+"""Features are the output of repeated-line tracking, as described on [MNM04]_.
+
+Defaults taken from [TV13]_.
+"""
+
+from ..algorithm import MiuraMatch
+algorithm = MiuraMatch(ch=65, cw=55)
+"""Miura-matching algorithm with specific settings for search displacement
+
+Defaults taken from [TV13]_.
+"""
diff --git a/bob/bio/vein/configurations/utfvp.py b/bob/bio/vein/configurations/utfvp.py
new file mode 100644
index 0000000..358bf55
--- /dev/null
+++ b/bob/bio/vein/configurations/utfvp.py
@@ -0,0 +1,44 @@
+#!/usr/bin/env python
+
+"""`UTFVP`_ is a database for biometric fingervein recognition
+
+The University of Twente Finger Vascular Pattern (UTFVP) Database is made
+publically available in order to support and stimulate research efforts in the
+area of developing, testing and evaluating algorithms for vascular patter
+recognition. The University of Twente, Enschede, The Netherlands (henceforth,
+UT) owns copyright of and serves as the source for the UTFVP database, which is
+now distributed to any research group approved by the UTFVP principal
+investigator. The reference citation is [TV13]_.
+
+You can download the raw data of the `UTFVP`_ database by following the link.
+
+.. include:: links.rst
+"""
+
+from bob.bio.vein.database import UtfvpBioDatabase
+
+utfvp_directory = "[YOUR_UTFVP_DIRECTORY]"
+"""Value of ``~/.bob_bio_databases.txt`` for this database"""
+
+database = UtfvpBioDatabase(original_directory = utfvp_directory)
+"""The :py:class:`bob.bio.base.database.BioDatabase` derivative with UTFVP 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_UTFVP_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.
+"""
diff --git a/bob/bio/vein/configurations/verafinger.py b/bob/bio/vein/configurations/verafinger.py
new file mode 100644
index 0000000..511aab3
--- /dev/null
+++ b/bob/bio/vein/configurations/verafinger.py
@@ -0,0 +1,44 @@
+#!/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.
+"""
diff --git a/bob/bio/vein/configurations/wide_line_detector.py b/bob/bio/vein/configurations/wide_line_detector.py
new file mode 100644
index 0000000..ba0835c
--- /dev/null
+++ b/bob/bio/vein/configurations/wide_line_detector.py
@@ -0,0 +1,56 @@
+#!/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]_.
+"""
diff --git a/bob/bio/vein/extractors/LocalBinaryPatterns.py b/bob/bio/vein/extractor/LocalBinaryPatterns.py
similarity index 100%
rename from bob/bio/vein/extractors/LocalBinaryPatterns.py
rename to bob/bio/vein/extractor/LocalBinaryPatterns.py
diff --git a/bob/bio/vein/extractors/MaximumCurvature.py b/bob/bio/vein/extractor/MaximumCurvature.py
similarity index 100%
rename from bob/bio/vein/extractors/MaximumCurvature.py
rename to bob/bio/vein/extractor/MaximumCurvature.py
diff --git a/bob/bio/vein/extractors/NormalisedCrossCorrelation.py b/bob/bio/vein/extractor/NormalisedCrossCorrelation.py
similarity index 100%
rename from bob/bio/vein/extractors/NormalisedCrossCorrelation.py
rename to bob/bio/vein/extractor/NormalisedCrossCorrelation.py
diff --git a/bob/bio/vein/extractors/PrincipalCurvature.py b/bob/bio/vein/extractor/PrincipalCurvature.py
similarity index 100%
rename from bob/bio/vein/extractors/PrincipalCurvature.py
rename to bob/bio/vein/extractor/PrincipalCurvature.py
diff --git a/bob/bio/vein/extractors/RepeatedLineTracking.py b/bob/bio/vein/extractor/RepeatedLineTracking.py
similarity index 100%
rename from bob/bio/vein/extractors/RepeatedLineTracking.py
rename to bob/bio/vein/extractor/RepeatedLineTracking.py
diff --git a/bob/bio/vein/extractors/WideLineDetector.py b/bob/bio/vein/extractor/WideLineDetector.py
similarity index 100%
rename from bob/bio/vein/extractors/WideLineDetector.py
rename to bob/bio/vein/extractor/WideLineDetector.py
diff --git a/bob/bio/vein/extractors/__init__.py b/bob/bio/vein/extractor/__init__.py
similarity index 100%
rename from bob/bio/vein/extractors/__init__.py
rename to bob/bio/vein/extractor/__init__.py
diff --git a/bob/bio/vein/preprocessors/FingerCrop.py b/bob/bio/vein/preprocessor/FingerCrop.py
similarity index 100%
rename from bob/bio/vein/preprocessors/FingerCrop.py
rename to bob/bio/vein/preprocessor/FingerCrop.py
diff --git a/bob/bio/vein/preprocessors/__init__.py b/bob/bio/vein/preprocessor/__init__.py
similarity index 100%
rename from bob/bio/vein/preprocessors/__init__.py
rename to bob/bio/vein/preprocessor/__init__.py
diff --git a/doc/api.rst b/doc/api.rst
index 06a6f35..0e9cab1 100644
--- a/doc/api.rst
+++ b/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
diff --git a/doc/baselines.rst b/doc/baselines.rst
index a25203c..e4a9903 100644
--- a/doc/baselines.rst
+++ b/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
diff --git a/doc/index.rst b/doc/index.rst
index 9c355cb..9eb9be6 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -24,7 +24,9 @@ Users Guide
installation
baselines
references
+ resources
api
+.. todolist::
.. include:: links.rst
diff --git a/doc/links.rst b/doc/links.rst
index 2437c81..3f5677d 100644
--- a/doc/links.rst
+++ b/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
diff --git a/doc/references.rst b/doc/references.rst
index 1a86352..f9ac086 100644
--- a/doc/references.rst
+++ b/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.
diff --git a/doc/resources.rst b/doc/resources.rst
new file mode 100644
index 0000000..bbb7724
--- /dev/null
+++ b/doc/resources.rst
@@ -0,0 +1,112 @@
+.. 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:
+
diff --git a/setup.py b/setup.py
index dad90b0..f9bcbea 100644
--- a/setup.py
+++ b/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',
],
},
--
GitLab