[sphinx] Clean up documentation and prepare the floor for Manuel's students

bob/bio/face/preprocessor/FaceCrop.py

@@ -93,7 +93,7 @@ class FaceCrop(Base):
       your database easily. If you are sure about your input, you can set this flag to
       ``True``.
 
-    annotator : :any:`bob.bio.base.annotator.Annotator`
+    annotator : `bob.bio.base.annotator.Annotator`
       If provided, the annotator will be used if the required annotations are
       missing.
 

bob/bio/face/preprocessor/HistogramEqualization.py

@@ -28,8 +28,8 @@ from bob.pipelines.sample import SampleBatch
 class HistogramEqualization(Base):
     """Crops the face (if desired) and performs histogram equalization to photometrically enhance the image.
 
-      Parameters:
-      -----------
+      Parameters
+      ----------
 
       face_cropper : str or :py:class:`bob.bio.face.preprocessor.FaceCrop` or :py:class:`bob.bio.face.preprocessor.FaceDetect` or ``None``
         The face image cropper that should be applied to the image.

doc/annotators.rst

@@ -7,7 +7,7 @@
 =================
 
 This packages provides several face annotators (using RGB images) that you can
-use to annotate biometric databases. See :ref:`bob.bio.base.annotations` for
+use to annotate biometric databases. See :any:`bob.bio.base.annotator` for
 a guide on the general usage of this feature.
 
 .. warning::

doc/baselines.rst

@@ -8,60 +8,51 @@
 Executing Baseline Algorithms
 =============================
 
-.. todo::
-   Here we should:   
-     - Brief how to run an experiment
-     - Point to bob.bio.base for further explanation
-     - Show the baselines available
-     - Show the databases available
 
+In this section we introduce the baselines available in this pakcage.
+To execute one of then in the databases available just run the following command::
 
-The baselines
--------------
+$ bob bio pipelines vanilla-biometrics [DATABASE_NAME] [BASELINE]
 
-The algorithms present an (incomplete) set of state-of-the-art face recognition algorithms. Here is the list of short-cuts:
+.. note::
+  Both, `[DATABASE_NAME]` and `[BASELINE]` can be either python resources or
+  python files.
 
-* ``eigenface``: The eigenface algorithm as proposed by [TP91]_. It uses the pixels as raw data, and applies a *Principal Component Analysis* (PCA) on it:
+  Please, refer to :ref:`bob.bio.base <bob.bio.base>` for more information.  
 
-  - preprocessor : :py:class:`bob.bio.face.preprocessor.FaceCrop`
-  - feature : :py:class:`bob.bio.base.extractor.Linearize`
-  - algorithm : :py:class:`bob.bio.base.algorithm.PCA`
 
-* ``lda``: The LDA algorithm applies a *Linear Discriminant Analysis* (LDA), here we use the combined PCA+LDA approach [ZKC98]_:
 
-  - preprocessor : :py:class:`bob.bio.face.preprocessor.FaceCrop`
-  - feature : :py:class:`bob.bio.face.extractor.Eigenface`
-  - algorithm : :py:class:`bob.bio.base.algorithm.LDA`
+Baselines available
+-------------------
 
-* ``gaborgraph``: This method extract grid graphs of Gabor jets from the images, and computes a Gabor phase based similarity [GHW12]_.
+The algorithms below constains all the face recognition baselines available.
+It is split in two groups, before and after deep learning era.
 
-  - preprocessor : :py:class:`bob.bio.face.preprocessor.INormLBP`
-  - feature : :py:class:`bob.bio.face.extractor.GridGraph`
-  - algorithm : :py:class:`bob.bio.face.algorithm.GaborJet`
 
+Before Deep learning era
+========================
 
-Further algorithms are available, when the :ref:`bob.bio.gmm <bob.bio.gmm>` package is installed:
 
-* ``gmm``: *Gaussian Mixture Models* (GMM) [MM09]_ are extracted from *Discrete Cosine Transform* (DCT) block features.
+* ``eigenface``: The eigenface algorithm as proposed by [TP91]_. It uses the pixels as raw data, and applies a *Principal Component Analysis* (PCA) on it.
 
-  - preprocessor : :py:class:`bob.bio.face.preprocessor.TanTriggs`
-  - feature : :py:class:`bob.bio.face.extractor.DCTBlocks`
-  - algorithm : :py:class:`bob.bio.gmm.algorithm.GMM`
+* ``lda``: The LDA algorithm applies a *Linear Discriminant Analysis* (LDA), here we use the combined PCA+LDA approach [ZKC98]_
 
-* ``isv``: As an extension of the GMM algorithm, *Inter-Session Variability* (ISV) modeling [WMM11]_ is used to learn what variations in images are introduced by identity changes and which not.
+* ``gabor_graph``: This method extract grid graphs of Gabor jets from the images, and computes a Gabor phase based similarity [GHW12]_.
 
-  - preprocessor : :py:class:`bob.bio.face.preprocessor.TanTriggs`
-  - feature : :py:class:`bob.bio.face.extractor.DCTBlocks`
-  - algorithm : :py:class:`bob.bio.gmm.algorithm.ISV`
+* ``lgbphs``: Local Gabor binary pattern histogram sequence (LGBPHS) implemented in [ZSG05]_
 
-* ``ivector``: Another extension of the GMM algorithm is *Total Variability* (TV) modeling [WM12]_ (aka. I-Vector), which tries to learn a subspace in the GMM super-vector space.
 
-  - preprocessor : :py:class:`bob.bio.face.preprocessor.TanTriggs`
-  - feature : :py:class:`bob.bio.face.extractor.DCTBlocks`
-  - algorithm : :py:class:`bob.bio.gmm.algorithm.IVector`
+Deep learning baselines
+=======================
 
-.. note::
-  The ``ivector`` algorithm needs a lot of training data and fails on small databases such as the `AT&T database`_.
+* ``facenet-sanderberg``: FaceNet trained by `David Sanderberg <https://github.com/davidsandberg/facenet>`_
+
+* ``inception-resnetv2-msceleb``: Inception Resnet v2 model trained using the MSCeleb dataset in the context of the work published by [TFP18]_
+
+* ``inception-resnetv1-msceleb``: Inception Resnet v1 model trained using the MSCeleb dataset in the context of the work published by [TFP18]_
+
+* ``inception-resnetv2-casiawebface``: Inception Resnet v2 model trained using the Casia Web dataset in the context of the work published by [TFP18]_
 
-.. _bob.bio.base.baseline_results:
+* ``inception-resnetv1-casiawebface``: Inception Resnet v1 model trained using the Casia Web dataset in the context of the work published by [TFP18]_
 
+* ``arcface-insightface``: Arcface model from `Insightface <https://github.com/deepinsight/insightface>`_

doc/implemented.rst

@@ -14,15 +14,11 @@ Databases
    bob.bio.face.database.ARFaceBioDatabase
    bob.bio.face.database.AtntBioDatabase
    bob.bio.face.database.MobioBioDatabase
-   bob.bio.face.database.CaspealBioDatabase
    bob.bio.face.database.ReplayBioDatabase
    bob.bio.face.database.ReplayMobileBioDatabase
    bob.bio.face.database.GBUBioDatabase
    bob.bio.face.database.LFWBioDatabase
    bob.bio.face.database.MultipieBioDatabase
-   bob.bio.face.database.XM2VTSBioDatabase
-   bob.bio.face.database.FRGCBioDatabase
-   bob.bio.face.database.SCFaceBioDatabase
    bob.bio.face.database.FargoBioDatabase
 
 

doc/index.rst

@@ -4,9 +4,9 @@
 
 .. _bob.bio.face:
 
-=============================
- Open Source Face Recognition
-=============================
+=====================================
+ Open Source Face Recognition Library
+=====================================
 
 
 This package provide open source tools to run comparable and reproducible face recognition experiments.
@@ -15,32 +15,30 @@ This includes:
 * Preprocessors to detect, align and photometrically enhance face images
 * Feature extractors that extract features from facial images
 * Facial image databases including their protocols.
-* Scripts that trains CNNs
-
-For more detailed information about how this package is structured, please refer to the documentation of :ref:`bob.bio.base <bob.bio.base>`.
+* Scripts that trains CNNs for face recognition.
 
 
 Get Started
-============
+===========
 
 The easiest way to get started is by simply comparing two faces::
 
-$ bob bio compare-samples -p gabor_graph me.png not_me.png
+$ bob bio compare-samples -p facenet-sanderberg me.png not_me.png
 
 .. warning::
    No face detection is carried out with this command.
 
 Check out all the face recognition algorithms available by doing::
 
-$ resources.py --type p
+$ resources.py --types p
 
 
 Get Started, serious 
 ====================
 
-.. todo::
-
-   Briefing about baselines
+For detailed information on how this package is structured and how
+to run experiments with it, please refer to the documentation of :ref:`bob.bio.base <bob.bio.base>`
+and get to know the vanilla biometrics and how to integrate both, algorithm and database protocols with it.
  
 
 Users Guide
@@ -50,7 +48,7 @@ Users Guide
    :maxdepth: 2
 
    baselines
-   leaderboad
+   leaderboard/leaderboard
    references
    annotators
 

doc/leaderboard.rst

-.. vim: set fileencoding=utf-8 :
-
-.. _bob.bio.face.learderboard:
-
-=============================
-Leaderboad
-=============================
-
-.. todo::
-   Here we should:   
-     - Present a custom Leaderboad per database
-     - Present a script that runs at least one experiment of this leader board
-
-

doc/leaderboard/arface.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard.arface:
+
+==============
+ARFACE Dataset
+==============
+
+
+.. todo::
+   Present benchmarks
+
+   Probably for Manuel's students
\ No newline at end of file

doc/leaderboard/banca.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard.banca:
+
+=============
+Banca Dataset
+=============
+
+
+.. todo::
+   Present benchmarks
+
+   Probably for Manuel's students
\ No newline at end of file

doc/leaderboard/gbu.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard.gbu:
+
+===========
+GBU Dataset
+===========
+
+
+.. todo::
+   Present benchmarks
+
+   Probably for Manuel's students
\ No newline at end of file

doc/leaderboard/ijbc.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard.ijbc:
+
+=============
+IJB-C Dataset
+=============
+
+
+.. todo::
+   Present benchmarks
+
+   Probably for Manuel's students
\ No newline at end of file

doc/leaderboard/leaderboard.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard:
+
+==========
+Leaderboad
+==========
+
+In the following pages we present a face recognition learderboard with some popular datasets.
+
+Datasets
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   mobio
+   lfw
+   meds
+   morph
+   ijbc
+   uccs
+   multipie
+   arface
+   xm2vts
+   gbu
+   banca
+   

doc/leaderboard/lfw.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard.lfw:
+
+===========
+LFW Dataset
+===========
+
+
+.. todo::
+   Present benchmarks
+
+   Probably for Manuel's students
\ No newline at end of file

doc/leaderboard/meds.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard.meds:
+
+============
+MEDS Dataset
+============
+
+
+.. todo::
+   Present benchmarks
+
+   Probably for Manuel's students
\ No newline at end of file

doc/leaderboard/mobio.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard.mobio:
+
+=============
+Mobio Dataset
+=============
+
+
+.. todo::
+   Benchmarks on Mobio Database
+
+   Probably for Manuel's students
\ No newline at end of file

doc/leaderboard/morph.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard.morph:
+
+=============
+Morph Dataset
+=============
+
+
+.. todo::
+   Present benchmarks
+
+   Probably for Manuel's students
\ No newline at end of file

doc/leaderboard/multipie.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard.multipie:
+
+================
+Multipie Dataset
+================
+
+
+.. todo::
+   Benchmarks on Multipie Database
+
+   Probably for Manuel's students
\ No newline at end of file

doc/leaderboard/uccs.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard.uccs:
+
+============
+UCCS Dataset
+============
+
+
+.. todo::
+   Present benchmarks
+
+   Probably for Manuel's students
\ No newline at end of file

doc/leaderboard/xm2vts.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.bio.face.learderboard.xm2vts:
+
+==============
+XM2VTS Dataset
+==============
+
+
+.. todo::
+   Present benchmarks
+
+   Probably for Manuel's students
\ No newline at end of file

doc/references.rst

@@ -8,19 +8,12 @@ References
 
 .. [TP91]    *M. Turk and A. Pentland*. **Eigenfaces for recognition**. Journal of Cognitive Neuroscience, 3(1):71-86, 1991.
 .. [ZKC98]  *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.
-.. [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.
 .. [GHW12]   *M. Günther, D. Haufe and R.P. Würtz*. **Face recognition with disparity corrected Gabor phase differences**. In Artificial neural networks and machine learning, volume 7552 of Lecture Notes in Computer Science, pages 411-418. 9/2012.
 .. [ZSG05]  *W. Zhang, S. Shan, W. Gao, X. Chen and H. Zhang*. **Local Gabor binary pattern histogram sequence (LGBPHS): a novel non-statistical model for face representation and recognition**. Computer Vision, IEEE International Conference on, 1:786-791, 2005.
-.. [MM09]    *C. McCool, S. Marcel*. **Parts-based face verification using local frequency bands**. In Advances in biometrics, volume 5558 of Lecture Notes in Computer Science. 2009.
-.. .. [WMM12]  *R. Wallace, M. McLaren, C. McCool and S. Marcel*. **Cross-pollination of normalisation techniques from speaker to face authentication using Gaussian mixture models**. IEEE Transactions on Information Forensics and Security, 2012.
 .. [WMM11]  *R. Wallace, M. McLaren, C. McCool and S. Marcel*. **Inter-session variability modelling and joint factor analysis for face authentication**. International Joint Conference on Biometrics. 2011.
-.. [Pri07]   *S. J. D. Prince*. **Probabilistic linear discriminant analysis for inferences about identity**. Proceedings of the International Conference on Computer Vision. 2007.
-.. [ESM13]  *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.
-.. [WM12]    *R. Wallace and M. McLaren*. **Total variability modelling for face verification**. IET Biometrics, vol.1, no.4, 188-199, 12/2012
 .. [TT10]    *X. Tan and B. Triggs*. **Enhanced local texture feature sets for face recognition under difficult lighting conditions**. IEEE Transactions on Image Processing, 19(6):1635-1650, 2010.
 .. [WLW04]   *H. Wang, S.Z. Li and Y. Wang*. **Face recognition under varying lighting conditions using self quotient image**. In IEEE International Conference on Automatic Face and Gesture Recognition (AFGR), pages 819-824. 2004.
-.. .. [HRM06]   *G. Heusch, Y. Rodriguez, and S. Marcel*. **Local Binary Patterns as an Image Preprocessing for Face Authentication**. In IEEE International Conference on Automatic Face and Gesture Recognition (AFGR), 2006.
 .. [WFK97]   *L. Wiskott, J.-M. Fellous, N. Krüger and C.v.d. Malsburg*. **Face recognition by elastic bunch graph matching**. IEEE Transactions on Pattern Analysis and Machine Intelligence, 19:775-779, 1997.
 .. [ZSQ09]  *W. Zhang, S. Shan, L. Qing, X. Chen and W. Gao*. **Are Gabor phases really useless for face recognition?** Pattern Analysis & Applications, 12:301-307, 2009.
-.. [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.
-.. .. [GWM12]   *M. Günther, R. Wallace and S. Marcel*. **An Open Source Framework for Standardized Comparisons of Face Recognition Algorithms**. Computer Vision - ECCV 2012. Workshops and Demonstrations, LNCS, 7585, 547-556, 2012.
+.. [TFP18] de Freitas Pereira, Tiago, André Anjos, and Sébastien Marcel. "Heterogeneous face recognition using domain specific units." IEEE Transactions on Information Forensics and Security 14.7 (2018): 1803-1816.
+.. [HRM06]   *G. Heusch, Y. Rodriguez, and S. Marcel*. **Local Binary Patterns as an Image Preprocessing for Face Authentication**. In IEEE International Conference on Automatic Face and Gesture Recognition (AFGR), 2006.