From a0f2bcf2a64ce247487d862c4076280e929c59dc Mon Sep 17 00:00:00 2001
From: Andre Anjos <andre.anjos@idiap.ch>
Date: Mon, 11 Jul 2016 16:58:45 +0200
Subject: [PATCH] [doc] Huge simplification of documentation given bob.bio.base
is now a base package
---
doc/api.rst | 36 +++++
doc/contribute.rst | 257 -------------------------------
doc/evaluate.rst | 117 --------------
doc/experiments.rst | 358 ++++++-------------------------------------
doc/index.rst | 40 ++---
doc/installation.rst | 116 --------------
doc/links.rst | 1 +
doc/satellite.rst | 38 -----
8 files changed, 91 insertions(+), 872 deletions(-)
create mode 100644 doc/api.rst
delete mode 100644 doc/contribute.rst
delete mode 100644 doc/evaluate.rst
delete mode 100644 doc/installation.rst
delete mode 100644 doc/satellite.rst
diff --git a/doc/api.rst b/doc/api.rst
new file mode 100644
index 0000000..1516ea2
--- /dev/null
+++ b/doc/api.rst
@@ -0,0 +1,36 @@
+.. vim: set fileencoding=utf-8 :
+.. Mon 11 Jul 2016 16:39:15 CEST
+
+
+============
+ Python API
+============
+
+This section contains a listing of all functionality available on this library
+which can be used for vein experiments.
+
+
+Pre-configured Databases
+------------------------
+
+.. automodule:: bob.bio.vein.configurations.databases
+
+
+Preprocessors
+-------------
+
+.. automodule:: bob.bio.vein.preprocessors
+
+
+Feature Extractors
+------------------
+
+.. automodule:: bob.bio.vein.extractors
+
+
+Matching Algorithms
+-------------------
+
+.. automodule:: bob.bio.vein.algorithms
+
+
diff --git a/doc/contribute.rst b/doc/contribute.rst
deleted file mode 100644
index b9b2850..0000000
--- a/doc/contribute.rst
+++ /dev/null
@@ -1,257 +0,0 @@
-.. vim: set fileencoding=utf-8 :
-.. date: Wed Jan 14 11:58:57 CEST 2015
-
-===========================================================================================
- Implementing your own Database, Preprocessor, Feature Extractor, or Recognition Algorithm
-===========================================================================================
-
-The FingerveinRecLib module is specifically designed to be as flexible as
-possible while trying to keep things simple. Therefore, it uses python to
-implement algorithms. It is file based so any algorithm can implement its own
-way of reading and writing data, features or models. Algorithm configurations
-are stored in configuration files, so it should be easy to test different
-parameters of your algorithms without modifying the code.
-
-To implement your own database, preprocessor, feature, or algorithm, simply
-follow the examples that are already in the FingerveinRecLib. In the following
-sections there will be an overview of the functions that need to be
-implemented.
-
-The FingerveinRecLib is designed in a way that useful default functionalities
-are executed. If you want/need to have a different behavior, you can simply
-add functions to your classes and register these functions, for details please
-see below.
-
-
-Implementing your own Functions
--------------------------------
-
-There are two options to add functionality to the FingerveinRecLib. The
-preferred option should be to write a satellite package of the
-FingerveinRecLib, implement everything you want to do, test it and document it.
-Please read the :ref:`satellite-packages` section for more details on this.
-
-Here, we describe the second way, which is to add functionality to
-FingerveinRecLib directly.
-
-
-Base Classes
-~~~~~~~~~~~~
-
-In general, any database, preprocessor, feature extractor or recognition
-algorithm should be derived from a base class that is detailed below. This
-base class provides default implementations of functionality that can be used
-directly or overwritten in your class. One of these functions, which is
-identical to all base classes, is the ``__str__(self)`` function, a special
-Python construct to convert an object of a class into a string that contains
-information about the object. In the FingerveinRecLib, this function is used
-to write the experimental configuration into a specific text file (by default:
-**Experiment.info** in the ``--result-directory``). This information is useful
-to see the exact configuration of the experiment with which the results was
-generated.
-
-There are two ways of providing these information for your class:
-
-1. Call the base class constructor and specify all parameters that should be
- added to the information file.
-2. Overwrite the ``__str__(self)`` function in your class, following the
- example of the base class.
-
-
-.. _filelist:
-
-Image Databases
-~~~~~~~~~~~~~~~
-
-If you have your own database that you want to execute the recognition
-experiments on, you should first check if you could use the :ref:`Verifcation
-FileList Database <bob.db.verification.filelist>` interface by defining
-appropriate file lists for the training set, the model set, and the probes.
-
-For more details, please check the documentation of `FaceRecLib
-<http://pythonhosted.org/facereclib/contribute.html>`_.
-
-
-Data Preprocessors
-~~~~~~~~~~~~~~~~~~
-
-All preprocessing classes should be derived from the
-:py:class:`FingerveinRecLib.preprocessing.Preprocessor` class.
-
-If your class returns data that is **not** of type :py:class:`numpy.ndarray`,
-you might need to overwrite further functions from
-:py:class:`FingerveinRecLib.preprocessing.Preprocessor` that define the IO of
-your class:
-
-* ``save_data(data, filename)``: Writes the given data (that has been generated
- using the ``__call__`` function of this class) to file.
-* ``read_data(filename)``: Reads the preprocessed data from file.
-
-By default, the original data is read by :py:func:`bob.io.base.load`. Hence,
-data is given as :py:class:`numpy.ndarray`\s. If you want to use a different
-IO for the original data (rarely useful...), you might want to overload:
-
-* ``read_original_data(filename)``: Reads the original data from file.
-
-If you plan to use a simple finger cropping for fingervein image processing,
-you might want to derive your class from the
-:py:class:`FingerveinRecLib.preprocessing.FingerCrop` class (you don't need to
-derive from :py:class:`FingerveinRecLib.preprocessing.Preprocessor ` in this
-case). In this case, just add a ``**kwargs`` parameter to your constructor,
-call the fingervein crop constructor with these parameters:
-``FingerveinRecLib.preprocessing.FingerCrop.__init__(self, **kwargs)``, and
-call the ``self.finger_crop(image)`` in your ``__call__`` function. For an
-example of this behavior, you might have a look into the
-`FingerveinRecLib.preprocessing.finger_crop_None_HE
-<file:../FingerveinRecLib/preprocessing/finger_crop_None_HE.py>`_ class.
-
-
-Feature Extractors
-~~~~~~~~~~~~~~~~~~
-
-Feature extractors should be derived from the
-:py:class:`FingerveinRecLib.features.Extractor` class. Your extractor class
-has to provide at least the functions:
-
-* ``__init__(self, <parameters>)``: Initializes the feature extraction
- algorithm with the parameters it needs. Please call the base class
- constructor in this constructor, e.g. as
- ``FingerveinRecLib.features.Extractor.__init__(self, ...)`` (there are more
- parameters to this constructor, see below).
-* ``__call__(self, data) -> feature``: Extracts the feature from the given
- preprocessed data. By default, the returned feature should be a
- :py:class:`numpy.ndarray`.
-
-If your features are not of type :py:class:`numpy.ndarray`, please overwrite
-the ``save_feature`` function to write features of other types. Please also
-overwrite the function to read your kind of features:
-
-* ``save_feature(self, feature, feature_file)``: Saves the feature (as returned by the ``__call__`` function) to the given file name.
-* ``read_feature(self, feature_file) -> feature``: Reads the feature (as written by the ``save_feature`` function) from the given file name.
-
-.. note::
-
- If your feature is of a class that contains and is written via a
- ``save(bob.io.base.HDF5File)`` method, you do not need to define a
- ``save_feature`` function. However, the ``read_feature`` function is
- required in this case.
-
-If the feature extraction process requires to read a trained extractor model
-from file, simply overload the function:
-
-* ``load(self, extractor_file)``: Loads the extractor from file. This function
- is called at least once before the ``__call__`` function is executed.
-
-
-Recognition Algorithms
-~~~~~~~~~~~~~~~~~~~~~~
-
-Implementing your recognition algorithm should be as straightforward. Simply
-derive your class from the :py:class:`FingerveinRecLib.tools.Tool` class.
-
-.. note::
-
- When you use a distance measure in your scoring function, and lower
- distances represents higher probabilities of having the same identity,
- please return the negative distance.
-
-And once more, if the projected feature is not of type ``numpy.ndarray``,
-overwrite the methods:
-
-* ``save_feature(feature, feature_file)``: Writes the feature (as returned by
- the ``project`` function) to file.
-* ``read_feature(feature_file) -> feature``: Reads and returns the feature (as
- written by the ``write_feature`` function).
-
-By default, it is assumed that both the models and the probe features are of
-type :py:class:`numpy.ndarray`. If your ``score`` function expects models and
-probe features to be of a different type, you should overwrite the functions:
-
-* ``save_model(self, model, model_file)``: writes the model (as returned by the
- ``enroll`` function)
-* ``read_model(self, model_file) -> model``: reads the model (as written by the
- ``write_model`` function) from file.
-* ``read_probe(self, probe_file) -> feature``: reads the probe feature from
- file.
-
-.. note::
-
- In many cases, the ``read_feature`` and ``read_probe`` functions are
- identical (if both are present).
-
-
-Finally, the :py:class:`FingerveinRecLib.tools.Tool` class provides default
-implementations for the case that models store several features, or that
-several probe features should be combined into one score.
-
-
-Executing experiments with your classes
----------------------------------------
-
-Finally, executing experiments using your database, preprocessor, feature
-extraction, and/or recognition tool should be as easy as using the tools that
-are already available. Nonetheless, it might be a good idea to first run the
-experiments locally (i.e., calling the ``bin/fingerveinverify.py -vvv`` without
-the ``--grid`` option) to see if your functions do work and do provide expected
-results.
-
-
-Adding Unit Tests
------------------
-
-To make sure that your piece of code it working properly, you should add a test
-case for your class. The FingerveinRecLib, as well as Bob_, rely on `nose
-tests <http://pypi.python.org/pypi/nose>`_ to run the unit tests. To implement
-a unit test for your contribution, you simply can create a python file with a
-name containing 'test' in your package. In the FingerveinRecLib, these files
-are located in `FingerveinRecLib/tests <file:../FingerveinRecLib/tests>`_.
-
-In the test file, please write a test class that derives from
-``unittest.TestCase``. Any function name containing the string ``test`` will
-be automatically found and executed when running ``bin/nosetests``. In your
-test function, please assure that all aspects of your contribution are
-thoroughly tested and that all test cases pass. Also remember that your tests
-need to run on different machines with various operating systems, so don't test
-floating point values for equality.
-
-
-.. _configuration-files:
-
-Adding Configuration Files
---------------------------
-
-After your code is tested, you should provide a configuration file for your
-algorithm. A configuration file basically consists of a constructor call to
-your new class with a useful (yet not necessarily optimized) set of parameters.
-Depending on your type of contribution, you should write a line like:
-
-* ``database = FingerveinRecLib.databases.<YourDatabase>(<YourParameters>)``
-* ``preprocessor = FingerveinRecLib.preprocessing.<YourPreprocessor>(<YourParameters>)``
-* ``feature_extractor = FingerveinRecLib.features.<YourExtractor>(<YourParameters>)``
-* ``tool = FingerveinRecLib.tools.<YourAlgorithm>(<YourParameters>)``
-
-and save the configuration file into the according sub-directory of
-`FingerveinRecLib/configurations <file:../FingerveinRecLib/configurations>`_.
-
-
-.. _register-resources:
-
-Registering your Code as a Resource
------------------------------------
-
-Now, you should be able to register this configuration file as a resource, so
-that you can use the configuration from above by a simple ``<shortcut>`` of
-your choice. Please open the `setup.py <file:../setup.py>`_ file in the base
-directory of your satellite package and edit the ``entry_points`` section.
-Depending on your type of algorithm, you have to add:
-
-* ``'FingerveinRecLib.database': [ '<your-database-shortcut> = <your-database-configuration>.database' ]``
-* ``'FingerveinRecLib.preprocessor': [ '<your-preprocessor-shortcut> = <your-preprocessor-configuration>.preprocessor' ]``
-* ``'FingerveinRecLib.feature_extractor': [ '<your-extractor-shortcut> = <your-extractor-configuration>.feature_extractor' ]``
-* ``'FingerveinRecLib.tool': [ '<your-recognition-algorithm-shortcut> = <your-algorithm-configuration>.tool' ]``
-
-After re-running ``bin/buildout``, your new resource should be listed in the
-output of ``bin/resources.py``.
-
-
-.. include:: links.rst
diff --git a/doc/evaluate.rst b/doc/evaluate.rst
deleted file mode 100644
index 82fd9b5..0000000
--- a/doc/evaluate.rst
+++ /dev/null
@@ -1,117 +0,0 @@
-.. vim: set fileencoding=utf-8 :
-.. date: Thu Jan 15 15:58:57 CEST 2015
-
-.. _evaluate:
-
-========================
- Evaluating Score Files
-========================
-
-Now, you have successfully run fingervein recognition experiments, and the
-result is one or more score files. Usually, these score files are located in
-sub-directories of your ``--result-directory`` and are called ``scores-dev``
-and ``scores-eval``. This section describes how to interpret these score
-files. So far, so good. In this section we show, what to do with these files.
-
-
-Interpreting Score Files
-------------------------
-
-The scores in the score files are arranged in rows. Usually, each score was
-generated by comparing one probe image to one client model. Information about
-this pair is contained in each row of the score file, which contains the four
-elements:
-
-1. The client id of the model. This is the identity of the enrolled client
- model of this model/probe pair.
-2. The client id of the probe. This is the identity shown in the probe image of
- this model/probe pair.
-3. The path of the probe image file, which is relative to the image database
- directory and without file extension.
-4. The score that was produced by comparing model and probe.
-
-Hence, if the first two elements are identical, the score is a client (a.k.a.
-genuine, positive, true access, target) score, if they differ it is an impostor
-(a.k.a. negative, non-target) score.
-
-
-Evaluation
-----------
-
-Since all required information is available in the score file, you can use any
-tool (like MatLab) to evaluate the score file and compute error measures or
-generate plots. The FingerveinRecLib defines one generic script that is able
-to evaluate the score files, compute some error measures and generate various
-types of plots. This script is called ``bin/evaluate.py`` and has the
-following command line options (see ``bin/evaluate.py --help`` for the
-shortcuts):
-
-* ``--dev-files``: A list of files of the development set that will be evaluated.
-* ``--eval-files`` (optional): A list of files of the evaluation set. If given,
- please assure that there exist exactly one evaluation file for each
- development score file and that they are given in the same order.
-
-* ``--directory`` (optional): If given, the ``--dev-files`` and
- ``--eval-files`` have either absolute paths or are relative to the given
- directory.
-
-* ``--roc`` (optional): If given, the score files will be evaluated to compute
- an ROC curve (one for dev and one for eval) and the result is plotted to the
- given pdf file.
-
-* ``--det`` (optional): If given, the score files will be evaluated to compute
- a DET curve (one for dev and one for eval) and the result is plotted to the
- given pdf file.
-
-* ``--cmc`` (optional): If given, the score files will be evaluated to compute
- a CMC curve (one for dev and one for eval) and the result is plotted to the
- given pdf file. Please note that CMC plots are not valid for all databases.
-
-* ``--legends`` (optional): If given, these legends will be placed into ROC,
- DET and CMC plots. Otherwise the file names will be used. Please assure that
- there exist exactly one legend for each development score file and that they
- are given in the correct order.
-
-* ``--criterion`` (optional): If given, a threshold will be computed based on
- the EER or minimum HTER of each development set file, and applied to the
- development and evaluation files. Both results will be written to console.
-
-* ``--cllr`` (optional): If given, a the Cllr and the minCllr will be computed
- on both the development and the evaluation set. All results will be written
- to console.
-
-As usual, the ``--verbose`` (i.e., ``-v``) option exists, and it is wise to use
-``-vv``.
-
-
-Deep Evaluation
----------------
-
-For deep evaluation you can use to plot the fauna models, EER per model for the
-all database in a detailed way. The script called ``bin/scoresanalysis.py``
-and has the following command line options (see ``bin/scoresanalysis.py
---help`` for the shortcuts):
-
-* ``--dev-files``: A list of files of the development set that will be
- evaluated.
-
-* ``--eval-files`` (optional): A list of files of the evaluation set. If given,
- please assure that there exist exactly one evaluation file for each
- development score file and that they are given in the same order.
-
-* ``--norm`` (optional): The scores are normalized in the rank [0,1]. (default:
- norm).
-
-* ``--directory`` (optional): If given, the ``--dev-files`` and
- ``--eval-files`` have either absolute paths or are relative to the given
- directory.
-
-* ``--criterion`` (optional): If given, a threshold will be computed based on
- the EER or minimum HTER of each development set file, and applied to the
- development and evaluation files. Both results will be written to console.
-
-* ``--pdf`` (optional): If given, Fauna graph will be plotted into the given
- pdf file. (default: None)
-
-As usual, the ``--verbose`` (i.e., ``-v``) option exists, and it is wise to use
-``-vv``.
diff --git a/doc/experiments.rst b/doc/experiments.rst
index 8f6aeb6..8cfc345 100644
--- a/doc/experiments.rst
+++ b/doc/experiments.rst
@@ -1,5 +1,5 @@
.. vim: set fileencoding=utf-8 :
-.. date: Thu Jan 15 15:58:57 CEST 2015
+.. Mon 11 Jul 2016 16:35:18 CEST
.. _experiments:
@@ -7,355 +7,85 @@
Running Experiments
=====================
-For running experiments with a defined setup, you should use the
-``bin/fingerveinverify.py`` script directly.
-
-In the following sections the available command line arguments are listed.
-Sometimes, arguments have a long version starting with ``--`` and a short one
-starting with a single ``-``. In this section, only the long names of the
-arguments are listed, please refer to ``bin/fingerveinverify.py --help`` (or
-short: ``bin/fingerveinverify.py -h``) for the abbreviations.
-
-
-.. _required:
-
-Required Command Line Arguments
--------------------------------
-
-To run a fingervein recognition experiment using the FingerveinRecLib, you have
-to tell the ``bin/fingerveinverify.py`` script, which database, preprocessing,
-features, and algorithm should be used. To use this script, you have to
-specify at least these command line arguments (see also the ``--help`` option):
-
-* ``--database``: The database to run the experiments on, and which protocol to
- use.
-* ``--preprocessing``: The data preprocessing and its parameters.
-* ``--features``: The features to extract and their options.
-* ``--tool``: The recognition algorithm and all its required parameters.
-
-There is another command line argument that is used to separate the resulting
-files from different experiments. Please specify a descriptive name for your
-experiment to be able to remember, how the experiment was run:
-
-* ``--sub-directory``: A descriptive name for your experiment.
-
-
-.. _managing-resources:
-
-Managing Resources
-~~~~~~~~~~~~~~~~~~
-
-The FingerveinRecLib is designed in a way that makes it very easy to select the
-setup of your experiments. Basically, you can specify your algorithm and its
-configuration in three different ways:
-
-1. You choose one of the registered resources. Just call ``bin/resources.py``
- or ``bin/fingerveinverify.py --help`` to see, which kind of resources are
- currently registered. Of course, you can also register a new resource.
- How this is done is detailed in section :ref:`register-resources`.
-
- Example:
-
- .. code-block:: sh
-
- $ bin/fingerveinverify.py --database vera
-
-
-2. You define a configuration file or choose one of the already existing
- configuration files that are located in `FingerveinRecLib/configurations`_
- and its sub-directories. How to define a new configuration file, please read
- section :ref:`configuration-files`.
-
- Example:
-
- .. code-block:: sh
-
- $ bin/fingerveinverify.py --preprocessing histeq
-
-
-3. You directly put the constructor call of the class into the command line.
- Since the parentheses are special characters in the shell, usually you have
- to enclose the constructor call into quotes. If you, e.g., want to extract
- MC-MaximumCurvature features, just add a to your command line.
-
- Example:
-
- .. code-block:: sh
-
- $ bin/fingerveinverify.py --features mc-maximumcurvature
-
-
-Of course, you can mix the ways, how you define command line options.
-
-For several databases, preprocessors, feature types, and recognition algorithms the FingerveinRecLib provides configuration files.
-They are located in the `FingerveinRecLib/configurations`_ directories.
-Each configuration file contains the required information for the part of the experiment, and all required parameters are preset with a suitable default value.
-Many of these configuration files with their default parameters are registered as resources, so that you don't need to specify the path.
-
-Since the default values might not be optimized or adapted to your problem, you can modify the parameters according to your needs.
-The most simple way is to pass the constructor call directly to the command line (i.e., use option 3).
-If you want to remember the parameters, you probably would write another configuration file.
-In this case, just copy one of the existing configuration files to a directory of your choice, adapt it, and pass the file location to the ``bin/fingerveinverify.py`` script.
-
-In the following, we will provide a detailed explanation of the parameters of the existing :ref:`databases`, :ref:`preprocessors`, :ref:`extractors`, and :ref:`algorithms`.
+For running experiments with a defined setup, you should use ``bin/verify.py``
+directly. Follow the instructions on bob.bio.base_ for listing and using all
+resources available in this package. In this section, we discuss specificities
+for added plugins.
.. _databases:
Databases
---------
-Currently, all implemented databases are taken from Bob_.
-To define a common API for all of the databases, the FingerveinRecLib defines the wrapper classes :py:class:`FingerveinRecLib.databases.DatabaseBob` and :py:class:`FingerveinRecLib.databases.DatabaseBobZT` and :py:class:`FingerveinRecLib.databases.DatabaseFileList` for these databases.
-The parameters of this wrapper class are:
-Required Parameters
-~~~~~~~~~~~~~~~~~~~
-* ``name``: The name of the database, in lowercase letters without special characters.
- This name will be used as a default sub-directory to separate resulting files of different experiments.
-* ``database = bob.db.<DATABASE>(original_directory=...)``: One of the image databases available at `Idiap at GitHub`_.
- Please set the ``original_directory`` and, if required, the ``original_extension`` parameter in the constructor of that database.
-* ``protocol``: The name of the protocol that should be used.
- If omitted, the protocol *Default* will be used (which might not be available in all databases, so please specify).
-
-Optional Parameters
+Required Parameters
~~~~~~~~~~~~~~~~~~~
-These parameters can be used to reduce the number of training images.
-Usually, there is no need to specify them, but in case your algorithm requires to much memory:
-
-* ``all_files_option``: The options to the database query that will extract all files.
-* ``extractor_training_options``: Special options that are passed to the query, e.g., to reduce the number of images in the extractor training.
-* ``projector_training_options``: Special options that are passed to the query, e.g., to reduce the number of images in the projector training.
-* ``enroller_training_options``: Special options that are passed to the query, e.g., to reduce the number of images in the enroller training.
-
-Implemented Database Interfaces
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Here we list the database interfaces that are currently available in the FingerveinRecLib.
-By clicking on the database name, you open one configuration file of the database, the link in ``<>`` parentheses will link to the ``bob.db`` database package documentation.
-If you have an ``image_directory`` different to the one specified in the file, please change the directory accordingly to be able to use the database.
-
-For more information, please also read the `FaceRecLib <http://pythonhosted.org/facereclib/experiments.html#databases>`_ documentation.
+* ``name``: The name of the database, in lowercase letters without special
+ characters. This name will be used as a default sub-directory to separate
+ resulting files of different experiments.
+* ``protocol``: The name of the protocol that should be used. If omitted, the
+ protocol ``Default`` will be used (which might not be available in all
+ databases, so please specify).
.. _preprocessors:
Preprocessors
-------------
-Currently, all preprocessors that are defined in FingerveinRecLib perform work on fingervein images and are, hence, used for fingervein recognition.
-Fingervein Cropping Parameters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Vein Cropping Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~
* ``mask_h``: Height of the cropping finger mask.
* ``mask_w``: Width of the cropping finger mask.
-
-* ``padding_offset``: An offset to the paddy array to be applied arround the fingervein image.
-* ``padding_threshold``: The pixel value of this paddy array.
- Defined to 0.2 to uncontrolled (low quality) fingervein databases and to 0 for controlled (high quality) fingervein databases. (By default 0.2).
-
-* ``preprocessing``: The pre-processing applied to the fingervein image before finger contour extraction.
- By default equal to 'None'.
-
+* ``padding_offset``: An offset to the paddy array to be applied arround the
+ fingervein image.
+* ``padding_threshold``: The pixel value of this paddy array. Defined to 0.2 to
+ uncontrolled (low quality) fingervein databases and to 0 for controlled (high
+ quality) fingervein databases. (By default 0.2).
+* ``preprocessing``: The pre-processing applied to the fingervein image before
+ finger contour extraction. By default equal to ``None``.
* ``fingercontour``: The algorithm used to localize the finger contour.
- Options: 'leemaskMatlab' - Implementation based on [LLP09]_, 'leemaskMod' - Modification based on [LLP09]_ for uncontrolled images introduced by author, and 'konomask' - Implementation based on [KUU02]_.
-
-* ``postprocessing``: The post-processing applied to the fingervein image after the finger contour extraction.
- Options: 'None', 'HE' - Histogram Equalization, 'HFE' - High Frequency Enphasis Filtering [ZTXL09]_, 'CircGabor' - Circular Gabor Filters [ZY09]_.
-
-
-Preprocessor Classes
-~~~~~~~~~~~~~~~~~~~~
+ Options: 'leemaskMatlab' - Implementation based on [LLP09]_, 'leemaskMod' -
+ Modification based on [LLP09]_ for uncontrolled images introduced by author,
+ and 'konomask' - Implementation based on [KUU02]_.
+* ``postprocessing``: The post-processing applied to the fingervein image after
+ the finger contour extraction. Options: 'None', 'HE' - Histogram
+ Equalization, 'HFE' - High Frequency Enphasis Filtering [ZTXL09]_,
+ 'CircGabor' - Circular Gabor Filters [ZY09]_.
-* :py:class:`FingerveinRecLib.preprocessing.FingerCrop`: Crops the fingervein image to the desired resolution, localize the finger contour and generate the finger mask region to extract features.
-* :py:class:`FingerveinRecLib.preprocessing.finger_crop_None_None`: None pre-processing applied and None post-processing applied after localize the finger contours.
-* :py:class:`FingerveinRecLib.preprocessing.finger_crop_None_HE`: None pre-processing applied and Histogram Equalization post-processing applied after localize the finger contours.
-* :py:class:`FingerveinRecLib.preprocessing.finger_crop_None_HEF`: None pre-processing applied and High Frequency Enphasis Filtering post-processing applied after localize the finger contours.
-* :py:class:`FingerveinRecLib.preprocessing.finger_crop_None_CircGabor`: None pre-processing applied and Circular Gabor Filters post-processing applied after localize the finger contours.
.. note::
- Currently, the pre-processing is fixed to 'None' by default.
-
-
-.. _extractors:
-
-Feature Extractors
-------------------
-Several different kinds of features can be extracted from the preprocessed data.
-Here is the list of classes to perform feature extraction and its parameters.
-
-* :py:class:`FingerveinRecLib.features.normalised_crosscorr`: Just use the full image as a feature.
-* :py:class:`FingerveinRecLib.features.maximum_curvature`: Extracts Maximum Curvature features [MNM05]_ from the preprocessed data.
-* :py:class:`FingerveinRecLib.features.repeated_line_tracking`: Extracts Repeated Line Tracking features [MNM04]_ from the preprocessed data.
-* :py:class:`FingerveinRecLib.features.wide_line_detector`: Extracts Wide Line Detector features [HDLTL10]_ from the preprocessed data.
-* :py:class:`FingerveinRecLib.features.lbp`: Extracts Local Binary Patterns features [MD13]_ from the preprocessed data.
+ Currently, the pre-processing is fixed to ``None`` by default.
.. _algorithms:
Recognition Algorithms
----------------------
-There are also a variety of recognition algorithms implemented in the FingerveinRecLib.
-All finger recognition algorithms are based on the :py:class:`FingerveinRecLib.tools.Tool` base class.
-This base class has parameters that some of the algorithms listed below share.
-These parameters mainly deal with how to compute a single score when more than one feature is provided for the model or for the probe:
-
-Here is a list of the most important algorithms and their parameters:
+There are also a variety of recognition algorithms implemented in the
+FingerveinRecLib. All finger recognition algorithms are based on the
+:py:class:`FingerveinRecLib.tools.Tool` base class. This base class has
+parameters that some of the algorithms listed below share. These parameters
+mainly deal with how to compute a single score when more than one feature is
+provided for the model or for the probe:
-* :py:class:`FingerveinRecLib.tools.MiuraMatch`: Computes the match ratio based on [MNM04]_ convolving the two template image.
- Return score - Value between 0 and 0.5, larger value is better match.
+Here is a list of the most important algorithms and their parameters:
- - ``ch``: Maximum search displacement in y-direction. Different defult values based on the different features.
- - ``cw``: Maximum search displacement in x-direction. Different defult values based on the different features.
+* :py:class:`FingerveinRecLib.tools.MiuraMatch`: Computes the match ratio based
+ on [MNM04]_ convolving the two template image. Return score - Value between
+ 0 and 0.5, larger value is better match.
+ - ``ch``: Maximum search displacement in y-direction. Different defult values
+ based on the different features.
+ - ``cw``: Maximum search displacement in x-direction. Different defult values
+ based on the different features.
* :py:class:`FingerveinRecLib.tools.HammingDistance`: Computes the Hamming Distance between two fingervein templates.
-Parallel Execution of Experiments
----------------------------------
-
-By default, all jobs of the fingervein recognition tool chain run sequentially on the local machine.
-To speed up the processing, some jobs can be parallelized using the SGE_ grid or using multi-processing on the local machine, using the :ref:`GridTK <gridtk>`.
-For this purpose, there is another option:
-
-* ``--grid``: The configuration file for the grid execution of the tool chain.
-
-.. note::
- The current SGE setup is specialized for the SGE_ grid at Idiap_.
- If you have an SGE grid outside Idiap_, please contact your administrator to check if the options are valid.
-
-The SGE_ setup is defined in a way that easily allows to parallelize data preprocessing, feature extraction, feature projection, model enrollment, and scoring jobs.
-Additionally, if the training of the extractor, projector, or enroller needs special requirements (like more memory), this can be specified as well.
-
-Several configuration files can be found in the `FingerveinRecLib/configurations/grid <file:../FingerveinRecLib/configurations/grid>`_ directory.
-All of them are based on the :py:class:`FingerveinRecLib.utils.GridParameters` class.
-Here are the parameters that you can set:
-
-* ``grid``: The type of the grid configuration; currently "sge" and "local" are supported.
-* ``number_of_preprocessing_jobs``: Number of parallel preprocessing jobs.
-* ``number_of_extraction_jobs``: Number of parallel feature extraction jobs.
-* ``number_of_projection_jobs``: Number of parallel feature projection jobs.
-* ``number_of_enrollment_jobs``: Number of parallel enrollment jobs (when development and evaluation sets are enabled, both sets will be split separately).
-* ``number_of_scoring_jobs``: Number of parallel scoring jobs (when development and evaluation sets are enabled, or ZT-norm is computed, more scoring jobs will be generated).
-
-If the ``grid`` parameter is set to ``'sge'`` (the default), jobs will be submitted to the SGE_ grid.
-In this case, the SGE_ queue parameters might be specified, either using one of the pre-defined queues (see `FingerveinRecLib/configurations/grid <file:../FingerveinRecLib/configurations/grid>`_) or using a dictionary of key/value pairs that are sent to the grid during submission of the jobs:
-
-* ``training_queue``: The queue that is used in any of the training (extractor, projector, enroller) steps.
-* ``..._queue``: The queue for the ... step.
-
-If the ``grid`` parameter is set to ``local``, all jobs will be run locally.
-In this case, the following parameters for the local submission can be modified:
-
-* ``number_of_parallel_processes``: The number of parallel processes that will be run on the local machine.
-* ``scheduler_sleep_time``: The interval in which the local scheduler should check for finished jobs and execute new jobs; the sleep time is given in seconds.
-
-and the ``number_of_..._jobs`` are ignored, and ``number_of_parallel_processes`` is used for all of them.
-
-.. note::
- The parallel execution of jobs on the local machine is currently in BETA status and might be unstable.
- If any problems occur, please file a new bug at http://github.com/idiap/gridtk/issues.
-
-When calling the ``bin/fingerveinverify.py`` script with the ``--grid ...`` argument, the script will submit all the jobs by taking care of the dependencies between the jobs.
-If the jobs are sent to the SGE_ grid (``grid = "sge"``), the script will exit immediately after the job submission.
-Otherwise, the jobs will be run locally in parallel and the script will exit after all jobs are finished.
-
-In any of the two cases, the script writes a database file that you can monitor using the ``bin/jman`` command.
-Please refer to ``bin/jman --help`` or the :ref:`GridTK documentation <gridtk>` to see the command line arguments of this tool.
-The name of the database file by default is **submitted.sql3**, but you can change the name (and its path) using the argument:
-
-* ``--submit-db-file``
-
-
-Command Line Arguments to change Default Behavior
--------------------------------------------------
-Additionally to the required command line arguments discussed above, there are several options to modify the behavior of the FingerveinRecLib experiments.
-One set of command line arguments change the directory structure of the output.
-By default, the results of the recognition experiment will be written to directory **/idiap/user/<USER>/<DATABASE>/<EXPERIMENT>/<SCOREDIR>/<PROTOCOL>**, while the intermediate (temporary) files are by default written to **/idiap/temp/<USER>/<DATABASE>/<EXPERIMENT>** or **/scratch/<USER>/<DATABASE>/<EXPERIMENT>**, depending on whether the ``--grid`` argument is used or not, respectively:
-
-* <USER>: The Unix username of the person executing the experiments.
-* <DATABASE>: The name of the database. It is read from the database configuration.
-* <EXPERIMENT>: A user-specified experiment name (see the ``--sub-directory`` argument above).
-* <SCOREDIR>: Another user-specified name (``--score-sub-directory`` argument below), e.g., to specify different options of the experiment.
-* <PROTOCOL>: The protocol which is read from the database configuration.
-
-These default directories can be overwritten using the following command line arguments, which expects relative or absolute paths:
-
-* ``--temp-directory``
-* ``--result-directory`` (for compatibility reasons also ``--user-directory`` can be used)
-
-Re-using Parts of Experiments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you want to re-use parts previous experiments, you can specify the directories (which are relative to the ``--temp-directory``, but you can also specify absolute paths):
-
-* ``--preprocessed-data-directory``
-* ``--features-directory``
-* ``--models-directories``
-
-or even trained extractor, projector, or enroller (i.e., the results of the extractor, projector, or enroller training):
-
-* ``--extractor-file``
-* ``--enroller-file``
-
-For that purpose, it is also useful to skip parts of the tool chain.
-To do that you can use:
-
-* ``--skip-preprocessing``
-* ``--skip-extractor-training``
-* ``--skip-extraction``
-* ``--skip-enroller-training``
-* ``--skip-enrollment``
-* ``--skip-score-computation``
-* ``--skip-concatenation``
-
-although by default files that already exist are not re-created.
-To enforce the re-creation of the files, you can use the:
-
-* ``--force``
-
-argument, which of course can be combined with the ``--skip...`` arguments (in which case the skip is preferred).
-To run just a sub-selection of the tool chain, you can also use the:
-
-* ``--execute-only``
-
-argument, which takes a list of options out of: ``preprocessing``, ``extractor-training``, ``extraction``, ``projector-training``, ``projection``, ``enroller-training``, ``enrollment``, ``score-computation``, or ``concatenation``.
-
-Sometimes you just want to try different scoring functions.
-In this case, you could simply specify a:
-
-* ``--score-sub-directory``
-
-In this case, no feature or model is recomputed (unless you use the ``--force`` option), but only new scores are computed.
-
-
-Other Arguments
----------------
-
-By default, the algorithms are set up to execute quietly, and only errors are reported.
-To change this behavior, you can -- again -- use the
-
-* ``--verbose``
-
-argument several times to increase the verbosity level to show:
-
-1) Warning messages
-2) Informative messages
-3) Debug messages
-
-When running experiments locally, my personal preference is verbose level 2, which can be enabled by ``--verbose --verbose``, or using the short version of the argument: ``-vv``.
-
-Finally, there is the:
-
-* ``--dry-run``
-
-argument that can be used for debugging purposes or to check that your command line is proper.
-When this argument is used, the experiment is not actually executed, but only the steps that would have been executed are printed to console.
-
-.. note::
- Usually it is a good choice to use the ``--dry-run`` option before submitting jobs to the SGE_, just to make sure that all jobs would be submitted correctly and with the correct dependencies.
-
-.. _FingerveinRecLib/configurations: file:../FingerveinRecLib/configurations
-
.. include:: links.rst
diff --git a/doc/index.rst b/doc/index.rst
index bc320c6..3979b22 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,30 +1,17 @@
.. vim: set fileencoding=utf-8 :
.. date: Wed Jan 14 11:58:57 CEST 2015
-.. _fingerveinreclib:
-=============================================
- Welcome to FingerveinRecLib's documentation!
-=============================================
+====================================
+ Biometric Vein Recognition Library
+====================================
-The FingerveinRecLib is an open source tool (based on FaceRecLib_) that is designed to run comparable and reproducible fingervein recognition experiments.
- Most of this documentation is based on the documentation of FaceRecLib_.
-
-
-To design a fingervein recognition experiment, one has to choose:
-
-* an image databases and its according protocol,
-* finger contours detection and image preprocessing algorithms,
-* the type of features to extract from the fingervein image,
-* the fingervein recognition algorithm to employ, and
-* the way to evaluate the results
-
-For any of these parts, several different types are implemented in the FingerveinRecLib, and basically any combination of the five parts can be executed.
-For each type, several meta-parameters can be tested.
-This results in a nearly infinite amount of possible fingervein recognition experiments that can be run using the current setup.
-But it is also possible to use your own database, preprocessing, feature type, or fingervein recognition algorithm and test this against the baseline algorithms implemented in the FingerveinRecLib.
-
-If you are interested, please continue reading:
+The Biometric Vein Recognition Library is an open source tool consisting of a
+series of plugins for bob.bio.base_, our open-source biometric recognition
+platform. As a result, it is fully extensible using bob.bio.base_ documented
+types and techniques. Please refer to the manual of that package for a thorough
+introduction. In this guide, we focus on details concerning vein recognition
+experiments with our plugins.
===========
@@ -34,16 +21,9 @@ Users Guide
.. toctree::
:maxdepth: 2
- installation
experiments
- evaluate
- contribute
- satellite
references
-
-
-This documentation is still under development.
+ api
.. include:: links.rst
-.. _facereclib: http://pythonhosted.org/facereclib/index.html
diff --git a/doc/installation.rst b/doc/installation.rst
deleted file mode 100644
index c1b0510..0000000
--- a/doc/installation.rst
+++ /dev/null
@@ -1,116 +0,0 @@
-.. vim: set fileencoding=utf-8 :
-.. date: Thu Jan 15 15:58:57 CEST 2015
-
-.. _installation:
-
-=========================
-Installation Instructions
-=========================
-
-.. note::
- This documentation includes several ``file://`` links that usually point to files or directories in your source directory.
- When you are reading this documentation online, these links won't work.
- Please read `Generate this documentation`_ on how to create this documentation including working ``file://`` links.
-
-Download
---------
-
-FingerveinRecLib
-~~~~~~~~~~~~~~~~
-To have a stable version of the FingerveinRecLib, the safest option is to go to the `FingerveinRecLib <http://pypi.python.org/pypi/fingerveinreclib>`_ web page on PyPI_ and download the latest version.
-
-Nevertheless, the library is also available as a project of `Idiap at GitHub`_.
-To check out the current version of the FingerveinRecLib, go to the console, move to any place you like and call:
-
-.. code-block:: sh
-
- $ git clone git@github.com:bioidiap/fingerveinreclib.git
-
-Be aware that you will get the latest changes and that it might not work as expected.
-
-
-Bob
-~~~
-
-The FingerveinRecLib is a satellite package of Bob_, where most of the image processing, feature extraction, and fingervein recognition algorithms, as well as the evaluation techniques are implemented. This package uses FaceRecLib_ as a parent package.
-In its current version, the FingerveinRecLib requires Bob_ version 2 or greater.
-Since version 2.0 there is no need for a global installation of Bob any more, all required packages will be automatically downloaded from PyPi_.
-
-To install `Packages of Bob <https://github.com/idiap/bob/wiki/Packages>`_, please read the `Installation Instructions <https://github.com/idiap/bob/wiki/Installation>`_.
-For Bob_ to be able to work properly, some dependent packages are required to be installed.
-Please make sure that you have read the `Dependencies <https://github.com/idiap/bob/wiki/Dependencies>`_ for your operating system.
-
-.. note::
- Currently, running Bob_ under MS Windows in not yet supported.
- However, we found that running Bob_ in a virtual Unix environment such as the one provided by VirtualBox_ is a good alternative.
-
-Usually, all possible database satellite packages (called ``bob.db.[...]``) are automatically downloaded from PyPI_.
-If you don't want to download the databases, please edit the ``eggs`` section of the buildout.cfg_ configuration file by removing the databases that you don't want.
-
-The ``gridtk`` tool kit is mainly used for submitting submitting jobs to Idiap_'s SGE_ grid.
-The latest version also supports to run jobs in parallel on the local machine.
-You can safely remove this line from the buildout.cfg_ if you are not at Idiap and if you don't want to launch your experiments in parallel.
-
-
-Image Databases
-~~~~~~~~~~~~~~~
-
-With the FingerveinRecLib you will run fingervein recognition experiments using some default finger vein image databases.
-Though the verification protocols are implemented in the FingerveinRecLib, the images are **not included**.
-To download the image databases, please refer to the according Web-pages, database URL's will be given in the :ref:`databases` section.
-
-
-Set-up your FingerveinRecLib
-----------------------------
-
-Now, you have everything ready so that you can continue to set up the FingerveinRecLib.
-To do this, we use the BuildOut_ system.
-To proceed, open a terminal in your FaceRecLib main directory and call:
-
-.. code-block:: sh
-
- $ python bootstrap-buildout.py
- $ bin/buildout
-
-The first step will generate a `bin <file:../bin>`_ directory in the main directory of the FingerveinRecLib.
-The second step automatically downloads all dependencies of the FingerveinRecLib and creates all required scripts that we will need soon.
-
-
-Test your Installation
-~~~~~~~~~~~~~~~~~~~~~~
-
-One of the scripts that were generated during the bootstrap/buildout step is a test script.
-To verify your installation, you should run the script by calling:
-
-.. code-block:: sh
-
- $ bin/nosetests
-
-In case any of the tests fail for unexplainable reasons, please file a bug report through the `GitHub bug reporting system`_.
-
-.. note::
- Usually, all tests should pass with the latest stable versions of the Bob_ packages.
- In other versions, some of the tests may fail.
-
-
-Generate this documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To generate this documentation, you call:
-
-.. code-block:: sh
-
- $ bin/sphinx-build docs sphinx
-
-Afterwards, the documentation is available and you can read it, e.g., by using:
-
-.. code-block:: sh
-
- $ firefox sphinx/index.html
-
-
-.. _buildout.cfg: file:../buildout.cfg
-
-.. include:: links.rst
-
-.. _facereclib: http://pythonhosted.org/facereclib/index.html
diff --git a/doc/links.rst b/doc/links.rst
index b8e1f29..ae58bb5 100644
--- a/doc/links.rst
+++ b/doc/links.rst
@@ -17,3 +17,4 @@
.. _sge: http://wiki.idiap.ch/linux/SunGridEngine
.. _virtualbox: https://www.virtualbox.org
.. _hdf5: http://www.hdfgroup.org/HDF5
+.. _bob.bio.base: https://pypi.python.org/pypi/bob.bio.base
diff --git a/doc/satellite.rst b/doc/satellite.rst
deleted file mode 100644
index 5d00f22..0000000
--- a/doc/satellite.rst
+++ /dev/null
@@ -1,38 +0,0 @@
-.. vim: set fileencoding=utf-8 :
-.. date: Wed Jan 14 11:58:57 CEST 2015
-
-.. _satellite-packages:
-
-=================================
-Create your own Satellite Package
-=================================
-
-The simplest and most clean way to test your own code in the FingerveinRecLib is to add it in a satellite package.
-In principle, you can choose a name that fits you, but it is preferable to have a package name that starts with ``xFingerveinRecLib.`` to show that it is a satellite package to the FingerveinRecLib.
-Please refer to the :ref:`satellite package explanation of Bob <bob.extension>`, which explains in detail how to start.
-
-Depending on of what nature is your contribution, you have to register it in the `setup.py` file of your satellite package.
-In case, your contribution is a fingervein recognition algorithm, you might want to :ref:`register it <register-resources>`.
-After doing that, you can simply use the ``bin/fingerveinverify.py`` (or any other script of the FingerveinRecLib) with your registered tool, as if it would be part of the FingerveinRecLib.
-
-Another contribution of code is to provide the source code to rerun the experiments as published in a paper.
-In this case, the contribution is more about scripts that can be used to run experiments.
-To cause the buildout_ system to create a python script in the `bin <file:../bin>`_ directory, you have to register the script in your `setup.py` file under the ``console_scripts`` section.
-
-
-Contribute your Code
---------------------
-When you invented a completely new type of preprocessing, features, or recognition algorithm and you want to share them with the world, or you want other researchers to be able to rerun your experiments, you are highly welcome **and encouraged** to do so.
-Please make sure that every part of your code is documented and tested.
-
-To upload your satellite package to the world (more specifically to PyPI_) you have to create an account and register an ssh key.
-Add the required packages in the `setup.py` file and under the ``install_requires`` section, provide the other information and upload the package to PyPI via:
-
-.. code-block:: sh
-
- $ python setup.py register
- $ python setup.py sdist --formats zip upload
-
-Now, all other researchers can make use of your invention, with the effect that your paper will be cited more often, simply by adding your project to the **setup.py** in their satellite package.
-
-.. include:: links.rst
--
GitLab