Skip to content
Snippets Groups Projects
Commit a0f2bcf2 authored by André Anjos's avatar André Anjos :speech_balloon:
Browse files

[doc] Huge simplification of documentation given bob.bio.base is now a base package

parent c73331a8
No related branches found
No related tags found
No related merge requests found
Expand all Hide whitespace changes
Inline Side-by-side
doc/api.rst 0 → 100644
+ 36
− 0
View file @ a0f2bcf2
.. 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
doc/contribute.rst deleted 100644 → 0
+ 0
− 257
View file @ c73331a8
.. 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
doc/evaluate.rst deleted 100644 → 0
+ 0
− 117
View file @ c73331a8
.. 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``.
doc/experiments.rst
+ 44
− 314
View file @ a0f2bcf2
This diff is collapsed.
doc/index.rst
+ 10
− 30
View file @ a0f2bcf2
.. 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
doc/installation.rst deleted 100644 → 0
+ 0
− 116
View file @ c73331a8
.. 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
doc/links.rst
+ 1
− 0
View file @ a0f2bcf2
......@@ -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
doc/satellite.rst deleted 100644 → 0
+ 0
− 38
View file @ c73331a8
.. 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
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment