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/algorithms/MiuraMatch.py → 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
       ):

bob/bio/vein/configurations/algorithms.py

-#!/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)

bob/bio/vein/configurations/database/biowave_test.py → bob/bio/vein/configurations/biowave_test.py

 #!/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_IMAGE_DIRECTORY]"
+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',
-    protocol='all'
 )
+"""Not yet documented
+
+.. todo::
+
+  Document this attribute
+
+"""
+
+protocol = 'all'
+"""Not yet documented
+
+.. todo::
+
+  Document this attribute
+
+"""

bob/bio/vein/configurations/database/utfvp.py

-#!/usr/bin/env python
-
-from bob.bio.vein.database import UtfvpBioDatabase
-
-utfvp_directory = "[YOUR_UTFVP_DIRECTORY]"
-
-database = UtfvpBioDatabase(
-    original_directory = utfvp_directory,
-    extension = ".png",
-    )    
-

bob/bio/vein/configurations/database/verafinger.py

-#!/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',
-    )
-

bob/bio/vein/configurations/extractors/lbp.py

-#!/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
-)

bob/bio/vein/configurations/extractors/maximum_curvature.py

-#!/usr/bin/env python
-# vim: set fileencoding=utf-8 :
-
-from ...extractors import MaximumCurvature
-feature_extractor = MaximumCurvature(sigma = 5)

bob/bio/vein/configurations/extractors/normalised_crosscorr.py

-#!/usr/bin/env python
-# vim: set fileencoding=utf-8 :
-
-from ...extractors import NormalisedCrossCorrelation
-
-feature_extractor = NormalisedCrossCorrelation()

bob/bio/vein/configurations/extractors/repeated_line_tracking.py

-#!/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
-    )

bob/bio/vein/configurations/extractors/wide_line_detector.py

-#!/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
-    )

bob/bio/vein/configurations/grid.py

-#!/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',
-    )

bob/bio/vein/configurations/maximum_curvature.py

+#!/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]_.
+"""

bob/bio/vein/configurations/parallel.py

+#!/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.
+"""

bob/bio/vein/configurations/preprocessors.py

-#!/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')

bob/bio/vein/configurations/repeated_line_tracking.py

+#!/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]_.
+"""

bob/bio/vein/configurations/utfvp.py

+#!/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.
+"""