Commit 175c2749 authored by Tiago de Freitas Pereira's avatar Tiago de Freitas Pereira
Browse files

Some directions to the new documentation

parent dcd6864b
Pipeline #42106 failed with stage
in 5 minutes and 35 seconds
......@@ -8,23 +8,24 @@ This section will introduce biometrics and how to differentiate people given
samples of traits that define them.
Biometry is the science that studies the measurment of physical and behavioral
traits of human beings. Those traits can be:
Biometrics is the science that studies the measurement of physical and behavioral traits of human beings. Those traits can be:
- The face shape and dimensions
- Face
- Fingerprints
- The voice
- Voice
- Vein patterns
- The gait (way of walking)
- ...
Measurments of such traits can be used to identify a person. They can also be
Measurements of such traits can be used to identify a person. They can also be
fused together (multimodal biometrics).
The goal of a biometric system is to associate a subject sample (image, sound,
video) with an identity (name, number).
For example, a photograph of a face of a person can be associated with the name
of that person.
The goal of a biometric system is to associate a subject signal (image, sound, video) with an identity (name, number).
For example, a photograph of a face of a person can be associated with the name of that person.
.. todo::
The text above needs to be rephrased by something more solid.
For instance, take a look in the handbook of biometrics.
Feature vectors
......@@ -35,6 +36,14 @@ feature vector. This vector dimension depends on the system used. In a good
system, vectors for different people would point to different space position,
and vectors representing the same person would point to the same position.
.. todo::
Elaborate this better.
For instance, biometrics is basically a classification problem.
The goal of these "feature vectors" extractors is to make the classification easier.
I suggest you to call this section as "Transformer".
The method used for getting this vector is called *extraction*.
.. figure:: img/feature_vector_extraction.png
......@@ -94,7 +103,7 @@ Then when using the system, a sample is presented along with a claimed
identity. The system then verifies that the sample belong to that identity by
comparing the features extracted from the proposed sample to the enrolled
features corresponding to that claimed identity. The system can outputs a
similarity score (:numref:`comparison-figure`) or directly a decision wether
similarity score (:numref:`comparison-figure`) or directly a decision whether
the subject corresponds to the claimed identity.
.. _comparison-figure:
......@@ -112,6 +121,16 @@ authorized people are enrolled, and when trying to access the resource, they
would be compared against their reference and authorized given a high enough
score.
.. todo::
Thinks missing:
- Mention that it's a 1:1 operation (yes/no).
- Explain that there are 2 types of errors
- Explain ROC and DET that are suitable to evaluate verification systems and that shows this trade-off.
Closed set identification
*************************
......@@ -123,6 +142,14 @@ most probable identity is returned.
This is used for example for searching to whom belongs a sample. (fingerprint
taken from a crime scene, compared against a list of suspects' fingerprints)
.. todo::
Thinks missing:
- Mention that it's a 1:N operation with a closed set of known identities.
- Explain CMC curve that it's suitable for this operation.
Open set identification
***********************
......@@ -135,5 +162,12 @@ This is used for searching a person in a database where its presence is not
guaranteed. Searching for a fingerprint taken on a crime scene in a list of
criminals, for example.
.. todo::
Thinks missing:
- Mention that it's a 1:N operation with a open set of known/unknown identities.
- Explain Detection and Identification Curve that it's suitable for this kind of problem
.. include:: links.rst
.. _bob.bio.base.hands_on_database:
=====================================================================
Hands on: Creating your own database
=====================================================================
.. todo::
Teach how to create your own database interface
\ No newline at end of file
......@@ -6,51 +6,44 @@
.. _bob.bio.base:
===========================================
Running Biometric Recognition Experiments
Scikit-biometrics
===========================================
The ``bob.bio`` packages provide open source tools to run comparable and reproducible biometric recognition experiments.
To design a biometric recognition experiment, you must choose:
* A database to use for the raw biometric data and a protocol that defines how to use that data,
* A data preprocessing algorithm to clean up the raw biometric data,
* A feature extractor to extract the desired type of features from the preprocessed data,
* A biometric matching algorithm,
* An evaluation method to make sense of the matching scores.
``scikit-biometrics`` provides open source tools to run comparable and reproducible biometric recognition experiments.
It covers the following biometrics traits:
The ``bob.bio`` packages contain several implementations of each of the above steps, so you can either choose from the existing methods or use your own.
* Face Biometrics: `scikit-face-biometrics <http://gitlab.idiap.ch/bob/bob.bio.face>`_
* Vein Biometrics: `scikit-vein-biometrics <http://gitlab.idiap.ch/bob/bob.bio.vein>`_
* Speaker Biometrics: `scikit-speaker-biometrics <http://gitlab.idiap.ch/bob/bob.bio.spear>`_
.. note::
The ``bob.bio`` packages are derived from the former `FaceRecLib <http://pypi.python.org/pypi/facereclib>`__, which is herewith outdated.
.. todo::
We might need a new logo
bob.bio.base in one shot
========================
Get Started
============
If you are too lazy to go through the documentation, and just want to see what this is about, just run the command below:
Compare two samples using a face recognition algorithm from `scikit-face-biometrics <http://gitlab.idiap.ch/bob/bob.bio.face>`_
.. code-block:: sh
bob bio pipelines vanilla-biometrics --help
bob bio compare-samples -p facenet me.png not_me.png
List all algorithms available
.. code-block:: sh
resources.py --type p
Structure of the Biometric Recognition Framework
================================================
The :py:mod:`bob.bio.base` package includes the basic definition of a biometric recognition experiment, as well as a generic script, which can execute the full biometric experiment in a single command line.
Changing the employed tools, such as the database, protocol, preprocessor, feature extractor or matching algorithm is as simple as changing a parameter in a configuration file or on the command line.
.. todo::
This command should change name.
The implementation of (most of) the tools is separated into other packages in the ``bob.bio`` namespace.
All of these packages can be easily combined.
Here is a growing list of derived packages:
* :ref:`bob.bio.spear <bob.bio.spear>` Tools to run speaker recognition experiments, including voice activity detection, Cepstral feature extraction, and speaker databases
* :ref:`bob.bio.vein <bob.bio.vein>` Tools to run vein recognition experiments, such as finger RoI detection, image binarization and template matching, and access to multiple vein image databases
* :ref:`bob.bio.face <bob.bio.face>` Tools to run face recognition experiments, such as face detection, facial feature extraction and comparison, and face image databases
* :ref:`bob.bio.video <bob.bio.video>` An extension of face recognition algorithms to run on video data, and the according video databases
* :ref:`bob.bio.gmm <bob.bio.gmm>` Algorithms based on Gaussian Mixture Modeling (GMM) such as Inter-Session Variability modeling (ISV) or Total Variability modeling (TV, aka. I-Vector) [Pri07]_ and [ESM+13]_.
Citing our Publications
......@@ -93,12 +86,11 @@ Users Guide
installation
biometrics_intro
biometrics_eval
struct_bio_rec_sys
experiments
implementation
filelist-guide
annotations
vanilla_biometrics_intro
vanilla_biometrics_experiment
legacy
hands_on_database
Reference Manual
......@@ -112,27 +104,6 @@ Reference Manual
References
==========
.. [TP91] *M. Turk and A. Pentland*. **Eigenfaces for recognition**. Journal of Cognitive Neuroscience, 3(1):71-86, 1991.
.. [ZKC+98] *W. Zhao, A. Krishnaswamy, R. Chellappa, D. Swets and J. Weng*. **Discriminant analysis of principal components for face recognition**, pages 73-85. Springer Verlag Berlin, 1998.
.. [Pri07] *S. J. D. Prince*. **Probabilistic linear discriminant analysis for inferences about identity**. Proceedings of the International Conference on Computer Vision. 2007.
.. [ESM+13] *L. El Shafey, Chris McCool, Roy Wallace and Sébastien Marcel*. **A scalable formulation of probabilistic linear discriminant analysis: applied to face recognition**. IEEE Transactions on Pattern Analysis and Machine Intelligence, 35(7):1788-1794, 7/2013.
.. [MWP98] *B. Moghaddam, W. Wahid and A. Pentland*. **Beyond eigenfaces: probabilistic matching for face recognition**. IEEE International Conference on Automatic Face and Gesture Recognition, pages 30-35. 1998.
.. [GW09] *M. Günther and R.P. Würtz*. **Face detection and recognition using maximum likelihood classifiers on Gabor graphs**. International Journal of Pattern Recognition and Artificial Intelligence, 23(3):433-461, 2009.
ToDo-List
=========
This documentation is still under development.
Here is a list of things that needs to be done:
.. todolist::
Indices and tables
==================
......
......@@ -9,94 +9,8 @@
Installation Instructions
=========================
As noted before, this package is part of the ``bob.bio`` packages, which in
turn are part of the signal-processing and machine learning toolbox Bob_. To
install Bob_, please read the `Installation Instructions <bobinstall_>`_.
Then, to install the ``bob.bio`` packages and in turn maybe the database
packages that you want to use, use conda_ to install them:
.. code-block:: sh
$ conda search "bob.bio.*" # searching
$ conda search "bob.db.*" # searching
$ conda install bob.bio.base bob.bio.<bioname> bob.db.<dbname>
where you would replace ``<bioname>`` and ``<dbname>`` with the name of
packages that you want to use.
An example installation
-----------------------
For example, you might want to run a video face recognition experiments using
the :py:class:`bob.bio.face.preprocessor.FaceDetect` and the
:py:class:`bob.bio.face.extractor.DCTBlocks` feature extractor defined in
:ref:`bob.bio.face <bob.bio.face>`, the
:py:class:`bob.bio.gmm.algorithm.IVector` algorithm defined in
:ref:`bob.bio.gmm <bob.bio.gmm>` and the video extensions defined in
:ref:`bob.bio.video <bob.bio.video>`, using the YouTube faces database
interface defined in :ref:`bob.db.youtube <bob.db.youtube>`. Running the
command line below will install all the required packages:
.. code-block:: sh
$ source activate <bob_conda_environment>
$ conda install bob.bio.base \
bob.bio.face \
bob.bio.gmm \
bob.bio.video \
bob.db.youtube
Databases
---------
With ``bob.bio`` you will run biometric recognition experiments using biometric
recognition databases. Though the verification protocols are implemented in
``bob.bio``, the raw data are **not included**. To download the raw
data of the databases, please refer to the according Web-pages. For a list of
supported databases including their download URLs, please refer to the
`biometric recognition databases`_.
After downloading the **raw data** for the databases, you will need to tell
``bob.bio``, where these databases can be found. This can be set using
our :ref:`bob.extension.rc`.
For instance, the name convention to be followed in the `~/.bobrc` file is: `<database_package_name>.directory`.
The command below shows how to set the path of the :ref:`bob.db.youtube`.
.. code-block:: sh
bob config set bob.db.youtube.directory /path/to/the/youtube/database
Test your Installation
----------------------
You can install the ``nose`` package to test your installation and use that to
verify your installation:
.. code-block:: sh
$ conda install nose # install nose
$ nosetests -vs bob.bio.base
$ nosetests -vs bob.bio.gmm
...
You should run the script running the nose tests for each of the ``bob.bio``
packages separately.
.. code-block:: sh
$ nosetests -vs bob.bio.base
$ nosetests -vs bob.bio.gmm
...
In case any of the tests fail for unexplainable reasons, please send a report
through our `mailing list`_.
.. note::
Usually, all tests should pass with the latest stable versions of Bob_
packages. In other versions, some of the tests may fail.
.. include:: links.rst
.. _bob.bio.base.legacy:
=============================================================
Legacy: Connecting legacy bob.bio.base to Vanilla Biometrics
=============================================================
.. todo::
Explain our past with bob.bio.base and explain the:
- Preprocessor Wrapper
- Extractor Wrapper
- Algorithm Wrapper
- Database Wrapper
.. _bob.bio.base.vanilla_biometrics_experiment:
=======================================================================
Vanilla Biometrics: From simple comparisons to large scale experiments.
=======================================================================
So far in our examples we've been comparing a couple of samples with our Vanilla Biometrics.
This section explains how to run benchmark using Vanilla Biometrics.
.. todo::
Explains here what an experiment is and why this is important
Vanilla Biometrics Pipeline
---------------------------
.. todo::
Explains here the three sub-pipelines.
Checkpointing experiments
=========================
.. todo::
Explain the checkpoint wrap with a code snipped and how to use it with ``bob bio pipelines.....``
Scaling up with Dask
====================
.. todo::
Explain the dask wrap with a code snipped and how to use it with ``bob bio pipelines.....``
Writing scores in a customized manner
=====================================
.. todo::
Explain the ScoreWriter (FourColumns and CSV)
The database interface
----------------------
.. todo::
Explains here the database interface structure
Evaluation
----------
.. todo::
Explains evaluation business
.. _bob.bio.base.vanilla_biometrics_intro:
=====================================================================
Vanilla Biometrics: Introduction to biometric recognition in practice
=====================================================================
In our very first example, we've shown how to compare two samples using the ``bob bio compare-samples`` command, where the "biometric" algorithm is set with the argument ``-p``.
The ``-p`` points to a so called :any:`bob.bio.base.pipelines.VanillaBiometricsPipeline`.
The Vanilla Biometrics represents **the simplest** biometrics pipeline possible and for this reason is the backbone for any biometric test in this library.
It's basically composed of:
**Transformer:** Instance of :py:class`sklearn.pipeline.Pipeline` or a `sklearn.base.BaseEstimator` that applies one or several transformations in an input sample.
**Biometric Algorithm:** Instance of :py:class:`bob.bio.base.pipelines.vanilla_biometrics.abstract_classes.BioAlgorithm` that implements the methods `enroll` and `score`.
Transformer
-----------
.. todo::
Explain what transformer is by pointing to scikit learn and ``bob.pipelines``.
Add a code sniped so people can copy and paste
Biometric Algorithm:
--------------------
.. todo::
Explain what Biometric algorithm is and what someone needs to do to implement their own Biome (for instance, implement the 2 primitives, enroll/score).
Add a code sniped so people can copy and paste
Markdown is supported
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