Commit 38ac1db8 authored by André Anjos's avatar André Anjos 💬

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
parent f8ac0cd4
......@@ -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
):
......
#!/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)
#!/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
"""
#!/usr/bin/env python
from bob.bio.vein.database import UtfvpBioDatabase
utfvp_directory = "[YOUR_UTFVP_DIRECTORY]"
database = UtfvpBioDatabase(
original_directory = utfvp_directory,
extension = ".png",
)
#!/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',
)
#!/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
)
#!/usr/bin/env python
# vim: set fileencoding=utf-8 :
from ...extractors import MaximumCurvature
feature_extractor = MaximumCurvature(sigma = 5)
#!/usr/bin/env python
# vim: set fileencoding=utf-8 :
from ...extractors import NormalisedCrossCorrelation
feature_extractor = NormalisedCrossCorrelation()
#!/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
)
#!/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
)
#!/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',
)
#!/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]_.
"""
#!/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.
"""
#!/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')
#!/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]_.
"""
#!/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.
"""
#!/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.
"""
#!/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]_.
"""
......@@ -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
......@@ -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,54 +110,46 @@ 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
......@@ -127,7 +157,7 @@ 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