Commit 6e21f431 authored by Manuel Günther's avatar Manuel Günther
Browse files

renamed LGBPHS algorithm to Histogram; added and corrected documentation

parent 85f05c73
......@@ -21,6 +21,8 @@
Run face recognition algorithms
=================================
This package is part of the ``bob.bio`` packages, which allow to run comparable and reproducible biometric recognition experiments on publicly available databases.
This package contains functionality to run face recognition experiments.
It is an extension to the `bob.bio.base <http://pypi.python.org/pypi/bob.bio.base>`_ package, which provides the basic scripts.
In this package, utilities that are specific for face recognition are contained, such as:
......
......@@ -8,7 +8,7 @@ import numpy
from bob.bio.base.algorithm import Algorithm
class LGBPHS (Algorithm):
class Histogram (Algorithm):
"""Tool chain for computing local Gabor binary pattern histogram sequences"""
def __init__(
......
from .GaborJet import GaborJet
from .LGBPHS import LGBPHS
from .Histogram import Histogram
# gets sphinx autodoc done right - don't remove it
__all__ = [_ for _ in dir() if not _.startswith('_')]
......@@ -3,7 +3,7 @@
import bob.bio.face
import bob.math
algorithm = bob.bio.face.algorithm.LGBPHS(
algorithm = bob.bio.face.algorithm.Histogram(
distance_function = bob.math.histogram_intersection,
is_distance_function = False
)
......@@ -6,8 +6,8 @@ import math
# feature extraction
extractor = bob.bio.face.extractor.LGBPHS(
# block setup
block_size = 10,
block_overlap = 4,
block_size = 8,
block_overlap = 0,
# Gabor parameters
gabor_sigma = math.sqrt(2.) * math.pi,
# LBP setup (we use the defaults)
......
......@@ -123,7 +123,7 @@ CONFIGURATIONS = {
'lgbphs': dict(
preprocessor = ('tan-triggs-crop', 'tan-triggs'),
extractor = 'lgbphs',
algorithm = 'lgbphs',
algorithm = 'histogram',
),
'bic': dict(
......
......@@ -77,37 +77,37 @@ def test_gabor_jet():
assert abs(jets.score_for_multiple_probes(model, [feature, feature]) - 1.) < 1e-8
def test_lgbphs():
lgbphs = bob.bio.base.load_resource("lgbphs", "algorithm")
assert isinstance(lgbphs, bob.bio.face.algorithm.LGBPHS)
assert isinstance(lgbphs, bob.bio.base.algorithm.Algorithm)
assert not lgbphs.performs_projection
assert not lgbphs.requires_projector_training
assert not lgbphs.use_projected_features_for_enrollment
assert not lgbphs.split_training_features_by_client
assert not lgbphs.requires_enroller_training
def test_histogram():
histogram = bob.bio.base.load_resource("histogram", "algorithm")
assert isinstance(histogram, bob.bio.face.algorithm.Histogram)
assert isinstance(histogram, bob.bio.base.algorithm.Algorithm)
assert not histogram.performs_projection
assert not histogram.requires_projector_training
assert not histogram.use_projected_features_for_enrollment
assert not histogram.split_training_features_by_client
assert not histogram.requires_enroller_training
# read input
feature1 = bob.bio.base.load(pkg_resources.resource_filename('bob.bio.face.test', 'data/lgbphs_sparse.hdf5'))
feature2 = bob.bio.base.load(pkg_resources.resource_filename('bob.bio.face.test', 'data/lgbphs_with_phase.hdf5'))
# enroll model from sparse features
model1 = lgbphs.enroll([feature1, feature1])
model1 = histogram.enroll([feature1, feature1])
assert model1.shape == feature1.shape
assert numpy.allclose(model1, feature1)
# enroll from non-sparse features
model2 = lgbphs.enroll([feature2, feature2])
model2 = histogram.enroll([feature2, feature2])
assert model2.shape == feature2.shape
assert numpy.allclose(model2, feature2)
# score without phase and sparse
reference = 40960.
assert abs(lgbphs.score(model1, feature1) - reference) < 1e-5
assert abs(lgbphs.score_for_multiple_probes(model1, [feature1, feature1]) - reference) < 1e-5
assert abs(histogram.score(model1, feature1) - reference) < 1e-5
assert abs(histogram.score_for_multiple_probes(model1, [feature1, feature1]) - reference) < 1e-5
# score with phase, but non-sparse
# reference doubles since we have two times more features
reference *= 2.
assert abs(lgbphs.score(model2, feature2) - reference) < 1e-5
assert abs(lgbphs.score_for_multiple_probes(model2, [feature2, feature2]) - reference) < 1e-5
assert abs(histogram.score(model2, feature2) - reference) < 1e-5
assert abs(histogram.score_for_multiple_probes(model2, [feature2, feature2]) - reference) < 1e-5
......@@ -2,7 +2,7 @@
.. author: Manuel Günther <manuel.guenther@idiap.ch>
.. date: Thu Sep 20 11:58:57 CEST 2012
.. _baselines:
.. _bob.bio.face.baselines:
=============================
Executing Baseline Algorithms
......@@ -140,17 +140,17 @@ Additionally, the following algorithms can be executed, when the :ref:`bob.bio.c
- feature : :py:class:`bob.bio.csu.extractor.LRPCA`
- algorithm : :py:class:`bob.bio.csu.algorithm.LRPCA`
* ``lda_ir``: The LDA-IR (a.k.a. CohortLDA [LBP+12]_) extracts color information from images after, and computes a PCA+LDA projection on two color layers.
* ``lda-ir``: The LDA-IR (a.k.a. CohortLDA [LBP+12]_) extracts color information from images after, and computes a PCA+LDA projection on two color layers.
- preprocessor : :py:class:`bob.bio.csu.preprocessor.LDAIR`
- feature : :py:class:`bob.bio.csu.extractor.LDAIR`
- algorithm : :py:class:`bob.bio.csu.algorithm.LDAIR`
.. note::
The ``lrpca`` and ``ldair`` algorithms require hand-labeled eye locations.
The ``lrpca`` and ``lda-ir`` algorithms require hand-labeled eye locations.
Therefore, they can not be run on the default ``atnt`` database.
.. _baseline_results:
.. _bob.bio.base.baseline_results:
Baseline Results
----------------
......@@ -183,12 +183,15 @@ For the `AT&T database`_ the results should be as follows:
+-------------+-------------+-------------+-------------+-------------+-------------+-------------+-------------+
| eigenface | lda | gaborgraph | lgbphs | gmm | isv | plda | bic |
+=============+=============+=============+=============+=============+=============+=============+=============+
| 8.368% | 9.763% | 4.579% | 8.500% | 1.237% | 0.053% | 7.921% | 3.526% |
| 8.368% | 9.763% | 4.579% | 8.500% | 0.684% | 0.421% | 7.921% | 3.526% |
+-------------+-------------+-------------+-------------+-------------+-------------+-------------+-------------+
.. note::
The results for ``gmm`` and ``isv`` were run with the parallelized scripts.
Though the results obtained with the sequential script should be similar, it might be that they are not identical.
.. note::
The ``lrpca`` and ``lda_ir`` algorithms require hand-labeled eye positions to run.
The ``lrpca`` and ``lda-ir`` algorithms require hand-labeled eye positions to run.
Since the AT&T database does not provide eye positions, it is not possible to provide baseline results on AT&T for these two algorithms.
.. include:: links.rst
......@@ -246,8 +246,14 @@ autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-
# For inter-documentation mapping:
from bob.extension.utils import link_documentation
intersphinx_mapping = link_documentation(['python', 'numpy', 'bob.bio.gmm', 'bob.bio.csu'])
intersphinx_mapping = link_documentation(['python', 'numpy', 'bob.bio.gmm', 'bob.bio.csu', 'bob.db.lfw'])
def skip(app, what, name, obj, skip, options):
# Do not skip the __call__ function as we have special implementations for them.
if name in ("__call__"):
return False
return skip
def setup(app):
pass
app.connect("autodoc-skip-member", skip)
doc/img/CMC.png

23.2 KB | W: | H:

doc/img/CMC.png

21.9 KB | W: | H:

doc/img/CMC.png
doc/img/CMC.png
doc/img/CMC.png
doc/img/CMC.png
  • 2-up
  • Swipe
  • Onion skin
doc/img/DET.png

33.5 KB | W: | H:

doc/img/DET.png

30.8 KB | W: | H:

doc/img/DET.png
doc/img/DET.png
doc/img/DET.png
doc/img/DET.png
  • 2-up
  • Swipe
  • Onion skin
doc/img/ROC.png

39.8 KB | W: | H:

doc/img/ROC.png

39.9 KB | W: | H:

doc/img/ROC.png
doc/img/ROC.png
doc/img/ROC.png
doc/img/ROC.png
  • 2-up
  • Swipe
  • Onion skin
......@@ -133,7 +133,7 @@ Here is the list of files and replacement strings for all databases that are reg
- Images (taken from MBGC-V1): ``[YOUR_MBGC-V1_DIRECTORY]``
* Labeled Faces in the Wild (LFW): ``'lfw-restricted'``, `'lfw-unrestricted'``
* Labeled Faces in the Wild (LFW): ``'lfw-restricted'``, ``'lfw-unrestricted'``
- Images (aligned with funneling): ``[YOUR_LFW_FUNNELED_DIRECTORY]``
......@@ -170,7 +170,7 @@ Preprocessors
~~~~~~~~~~~~~
Photometric enhancement algorithms are -- by default -- registered without face cropping, as ``'base'`` (no enhancement), ``'histogram'`` (histogram equalization), ``'tan-triggs'``, ``'self-quotient'`` (self quotient image) and ``'inorm-lbp'``.
These resources should only be used, when original images are already cropped (such as in the `AT&T database`_.
These resources should only be used, when original images are already cropped (such as in the `AT&T database`_).
The default face cropping is performed by aligning the eye locations such that the eyes (in subject perspective) are located at: right eye: ``(16, 15)``, left eye: ``(16, 48)``, and the image is cropped to resolution ``(80, 64)`` pixels.
This cropper is registered under the resource key ``'face-crop-eyes'``.
......@@ -192,6 +192,19 @@ Only four types of features are registered as resources here:
* ``'dct-blocks'``: DCT blocks with 12 pixels and full overlap, extracting 35 DCT features per block
* ``'eigenface'``: Pixel vectors projected to face space keeping 95 % variance
* ``'grid-graph'``: Gabor jets in grid graphs, with 4 pixels distance between nodes
* ``'grid-graph'``: Gabor jets in grid graphs, with 8 pixels distance between nodes
* ``'lgbphs'``: Local Gabor binary pattern histogram sequences with block-size of 8 and no overlap
.. _bob.bio.face.algorithms:
Face Recognition Algorithms
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ``'gabor-jet'``: Compares graphs of Gabor jets with using a dedicated Gabor jet similarity function [GHW12]_
* ``'histogram'``: Compares histograms using histogram comparison functions
* ``'bic-jet'``: Uses the :py:class:`bob.bio.base.algorithm.BIC` with vectors of Gabor jet similarities
.. note:: One particularity of this resource is that the function to compute the feature vectors to be classified in the BIC algorithm is actually implemented *in the configuration file*.
.. include:: links.rst
......@@ -37,7 +37,7 @@ Face Recognition Algorithms
.. autosummary::
bob.bio.face.algorithm.GaborJet
bob.bio.face.algorithm.LGBPHS
bob.bio.face.algorithm.Histogram
Preprocessors
......
......@@ -45,15 +45,8 @@ Reference Manual
:maxdepth: 2
implemented
py_api
.. include:: references.rst
ToDo-List
=========
This documentation is still under development.
Here is a list of things that needs to be done:
.. todolist::
......@@ -155,7 +155,7 @@ setup(
'bob.bio.algorithm': [
'gabor-jet = bob.bio.face.config.algorithm.gabor_jet:algorithm', # Gabor jet comparison
'lgbphs = bob.bio.face.config.algorithm.lgbphs:algorithm', # LGBPHS histograms
'histogram = bob.bio.face.config.algorithm.histogram:algorithm', # LGBPHS histograms
'bic-jets = bob.bio.face.config.algorithm.bic_jets:algorithm', # BIC on gabor jets
],
},
......
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