Commit ea0d273d authored by Manuel Günther's avatar Manuel Günther

Added documentation

parent 2aaa3c47
......@@ -16,16 +16,17 @@
:target: http://www.cs.colostate.edu/facerec
===================================================================
FaceRecLib Wrapper classes for the CSU Face Recognition Resources
===================================================================
================================================================
bob.bio Wrapper classes for the CSU Face Recognition Resources
================================================================
This satellite package to the FaceRecLib_ provides wrapper classes for the CSU face recognition resources, which can be downloaded from http://www.cs.colostate.edu/facerec.
Two algorithms are provided by the CSU toolkit (and also by this satellite package): the local region PCA (LRPCA) and the LDA-IR (also known as CohortLDA).
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 provides wrapper classes for the CSU face recognition resources, which can be downloaded from http://www.cs.colostate.edu/facerec.
Two algorithms are provided by the CSU toolkit (and also by this package): the local region PCA (LRPCA) and the LDA-IR (also known as CohortLDA).
For more information about the LRPCA and the LDA-IR algorithm, please refer to the documentation on http://www.cs.colostate.edu/facerec/.
For further information about the FaceRecLib_, please read `its Documentation <http://pythonhosted.org/facereclib/index.html>`_.
On how to use this package in a face recognition experiment, please see http://pypi.python.org/pypi/xfacereclib.paper.BeFIT2012
For further information about ``bob.bio``, please read `its Documentation <http://pythonhosted.org/bob.bio.base/index.html>`_.
Installation Instructions
......@@ -38,18 +39,17 @@ Please make sure that you have read installation instructions in the Documentati
Since the original CSU resources are not Python3 compatible, this package only supports Python2.
For external dependencies of the CSU resources, please read their `README <http://www.cs.colostate.edu/facerec/algorithms/README.pdf>`__.
The FaceRecLib_ and parts of this package rely on Bob_, an open-source signal-processing and machine learning toolbox.
The ``bob.bio`` packages and parts of this package rely on Bob_, an open-source signal-processing and machine learning toolbox.
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.
Documentation
-------------
For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/xfacereclib.extension.CSU/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/xfacereclib.extension.CSU/master/index.html>`_ of the documentation.
For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/bob.bio.csu/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.bio.csu/master/index.html>`_ of the documentation.
For a list of tutorials on packages ob Bob_, or information on submitting issues, asking questions and starting discussions, please visit its website.
.. _bob: https://www.idiap.ch/software/bob
.. _facereclib: http://pypi.python.org/pypi/facereclib
.. _documentation: http://pythonhosted.org/bob.bio.csu/index.html
......@@ -23,8 +23,22 @@ import bob.bio.base
from .. import utils
class LDAIR (bob.bio.base.algorithm.Algorithm):
"""This class defines a wrapper for the facerec2010.baseline.lda.LRLDA class to be used as a face recognition :py:class:`facereclib.tools.Tool` in the :ref:`FaceRecLib <facereclib>`."""
"""This class defines a wrapper for the :py:class:`facerec2010.baseline.lda.LRLDA` class to be used as an image :py:class:`bob.bio.base.algorithm.Algorithm`.
**Parameters:**
REGION_ARGS : list
The region arguments as taken from facerec2010.baseline.lda.CohortLDA_REGIONS
REGION_KEYWORDS : dict
The region keywords as taken from facerec2010.baseline.lda.CohortLDA_KEYWORDS
multiple_model_scoring : str
The scoring strategy if models are enrolled from several images, see :py:func:`bob.bio.base.score_fusion_strategy` for more information.
multiple_probe_scoring : str
The scoring strategy if a score is computed from several probe images, see :py:func:`bob.bio.base.score_fusion_strategy` for more information.
"""
def __init__(
self,
REGION_ARGS,
......@@ -32,20 +46,6 @@ class LDAIR (bob.bio.base.algorithm.Algorithm):
multiple_model_scoring = 'max', # by default, compute the average between several models and the probe
multiple_probe_scoring = 'max' # by default, compute the average between the model and several probes
):
"""Constructor Documentation:
REGION_ARGS
The region arguments as taken from facerec2010.baseline.lda.CohortLDA_REGIONS
REGION_KEYWORDS
The region keywords as taken from facerec2010.baseline.lda.CohortLDA_KEYWORDS
multiple_model_scoring
The scoring strategy if models are enrolled from several images, see facereclib.tools.Tool for more information.
multiple_probe_scoring
The scoring strategy if a score is computed from several probe images, see facereclib.tools.Tool for more information.
"""
bob.bio.base.algorithm.Algorithm.__init__(self, multiple_model_scoring=multiple_model_scoring, multiple_probe_scoring=multiple_probe_scoring, **REGION_KEYWORDS)
self.ldair = facerec2010.baseline.lda.LRLDA(REGION_ARGS, **REGION_KEYWORDS)
self.use_cohort = 'cohort_adjust' not in REGION_ARGS[0] or REGION_ARGS[0]['cohort_adjust']
......@@ -56,9 +56,16 @@ class LDAIR (bob.bio.base.algorithm.Algorithm):
assert isinstance(feature, facerec2010.baseline.common.FaceRecord)
assert hasattr(feature, "features")
def load_projector(self, projector_file):
"""This function loads the Projector from the given projector file.
This is only required when the cohort adjustment is enabled.
**Parameters:**
projector_file : str
The name of the projector file.
The file is actually not used, but instead we load the extractor file, which needs to be in the same directory, and must be called "Extractor.hdf5"
"""
# To avoid re-training the Projector, we load the Extractor file instead.
# This is only required when the cohort adjustment is enabled, otherwise the default parametrization of LDA-IR should be sufficient.
......@@ -69,19 +76,56 @@ class LDAIR (bob.bio.base.algorithm.Algorithm):
def enroll(self, enroll_features):
"""Enrolls a model from features from several images by simply storing all given features."""
"""enroll(enroll_features) -> model
Enrolls a model from features from several images by simply storing all given features.
**Parameters:**
enroll_features : [:py:class:`facerec2010.baseline.common.FaceRecord`]
The features used to enroll the model.
**Returns:**
model : [:py:class:`facerec2010.baseline.common.FaceRecord`]
The model, which is identical to the ``enroll_features``.
"""
[self._check_feature(f) for f in enroll_features]
# just store all features (should be of type FaceRecord)
# since the given features are already in the desired format, there is nothing to do.
return enroll_features
def write_model(self, model, model_file):
"""Saves the enrolled model to file using the pickle module."""
"""Saves the enrolled model to file using the :py:func:`bob.bio.csu.save_pickle` function.
**Parameters:**
model : [:py:class:`facerec2010.baseline.common.FaceRecord`]
The model to be written.
model_file : str
The name of the model file that is written.
"""
# just dump the model to .pkl file
utils.save_pickle(model, model_file)
def read_model(self, model_file):
"""Loads an enrolled model from file using the pickle module."""
"""read_model(model_file) -> model
Loads an enrolled model from file using the :py:func:`bob.bio.csu.load_pickle` function.
**Parameters:**
model_file : str
The name of the model file to be read.
**Returns:**
model : [:py:class:`facerec2010.baseline.common.FaceRecord`]
The model read from file.
"""
# just read the model from .pkl file
return utils.load_pickle(model_file)
......@@ -89,7 +133,23 @@ class LDAIR (bob.bio.base.algorithm.Algorithm):
read_probe = read_model
def score(self, model, probe):
"""Compute the score for the given model (a list of FaceRecords) and a probe (a FaceRecord)"""
"""score(model, probe) -> score
Compute the score for the given model (a list of FaceRecords) and a probe (a FaceRecord).
**Parameters:**
model : [:py:class:`facerec2010.baseline.common.FaceRecord`]
The model to compare, which is actually a list of extracted features.
probe : :py:class:`facerec2010.baseline.common.FaceRecord`
The probe to compare.
**Returns**:
score : float
A score that was fused using the fusion function defined in the constructor of this class.
"""
if isinstance(model, list):
# compute score fusion strategy with several model features (which is implemented in the base class)
return self.score_for_multiple_models(model, probe)
......
......@@ -25,7 +25,19 @@ from .. import utils
class LRPCA (bob.bio.base.algorithm.Algorithm):
"""This class defines a wrapper for the facerec2010.baseline.lrpca.LRPCA class to be used as a face recognition :py:class:`facereclib.tools.Tool` in the :ref:`FaceRecLib <facereclib>`."""
"""This class defines a wrapper for the :py:class:`facerec2010.baseline.lda.LRPCA` class to be used as an image :py:class:`bob.bio.base.algorithm.Algorithm`.
**Parameters:**
TUNING : dict
The tuning for the LRPCA algorithm as taken from the :py:attr:`facerec2010.baseline.lrpca.GBU_TUNING`.
multiple_model_scoring : str
The scoring strategy if models are enrolled from several images, see :py:func:`bob.bio.base.score_fusion_strategy` for more information.
multiple_probe_scoring : str
The scoring strategy if a score is computed from several probe images, see :py:func:`bob.bio.base.score_fusion_strategy` for more information.
"""
def __init__(
self,
......@@ -33,18 +45,6 @@ class LRPCA (bob.bio.base.algorithm.Algorithm):
multiple_model_scoring = 'max', # by default, compute the average between several models and the probe
multiple_probe_scoring = 'max' # by default, compute the average between the model and several probes
):
"""Constructor Documentation:
TUNING
The tuning for the LRPCA algorithm as taken from the facerec2010.baseline.lrpca.GBU_TUNING
multiple_model_scoring
The scoring strategy if models are enrolled from several images, see facereclib.tools.Tool for more information.
multiple_probe_scoring
The scoring strategy if a score is computed from several probe images, see facereclib.tools.Tool for more information.
"""
bob.bio.base.algorithm.Algorithm.__init__(self, multiple_model_scoring=multiple_model_scoring, multiple_probe_scoring=multiple_probe_scoring, **TUNING)
# initialize LRPCA (not sure if this is really required)
self.lrpca = facerec2010.baseline.lrpca.LRPCA(**TUNING)
......@@ -63,7 +63,20 @@ class LRPCA (bob.bio.base.algorithm.Algorithm):
def enroll(self, enroll_features):
"""Enrolls a model from features from several images by simply storing all given features."""
"""enroll(enroll_features) -> model
Enrolls a model from features from several images by simply storing all given features.
**Parameters:**
enroll_features : [:py:class:`numpy.ndarray`]
The features used to enroll the model.
**Returns:**
model : [:py:class:`facerec2010.baseline.pca.FaceRecord`]
The model, which a collection of face records, storing the given ``enroll_features``.
"""
# no rule to enroll features in the LRPCA setup, so we just store all features
# create model Face records
model_records = []
......@@ -75,19 +88,57 @@ class LRPCA (bob.bio.base.algorithm.Algorithm):
def write_model(self, model, model_file):
"""Saves the enrolled model to file using the pickle module."""
"""Saves the enrolled model to file using the :py:func:`bob.bio.csu.save_pickle` function.
**Parameters:**
model : [:py:class:`facerec2010.baseline.pca.FaceRecord`]
The model to be written.
model_file : str
The name of the model file that is written.
"""
# just dump the model to .pkl file
utils.save_pickle(model, model_file)
def read_model(self, model_file):
"""Loads an enrolled model from file using the pickle module."""
"""read_model(model_file) -> model
Loads an enrolled model from file using the :py:func:`bob.bio.csu.load_pickle` function.
**Parameters:**
model_file : str
The name of the model file to be read.
**Returns:**
model : [:py:class:`facerec2010.baseline.pca.FaceRecord`]
The model read from file.
"""
# just read the model from .pkl file
return utils.load_pickle(model_file)
def score(self, model, probe):
"""Computes the score for the given model (a list of FaceRecords) and a probe feature (a numpy.ndarray)"""
"""score(model, probe) -> score
Compute the score for the given model (a list of FaceRecords) and a probe (a FaceRecord).
**Parameters:**
model : [:py:class:`facerec2010.baseline.pca.FaceRecord`]
The model to compare, which is actually a list of extracted features.
probe : :py:class:`numpy.ndarray`
The probe to compare.
**Returns**:
score : float
A score that was fused using the fusion function defined in the constructor of this class.
"""
if isinstance(model, list):
# compute score fusion strategy with several model features (which is implemented in the base class)
return self.score_for_multiple_models(model, probe)
......
......@@ -29,17 +29,17 @@ logger = logging.getLogger("bob.bio.csu")
from .. import utils
class LDAIR (bob.bio.base.extractor.Extractor):
"""This class defines a wrapper for the facerec2010.baseline.lda.LRLDA class to be used as a :py:class:`facereclib.feature.Extractor` in the :ref:`FaceRecLib <facereclib>`."""
"""This class defines a wrapper for the :py:class:`facerec2010.baseline.lda.LRLDA` class to be used as an image :py:class:`bob.bio.base.extractor.Extractor`.
def __init__(self, REGION_ARGS, REGION_KEYWORDS):
"""Constructor Documentation:
**Parameters:**
REGION_ARGS
The region arguments as taken from facerec2010.baseline.lda.CohortLDA_REGIONS
REGION_ARGS : list
The region arguments as taken from :py:attr:`facerec2010.baseline.lda.CohortLDA_REGIONS`.
REGION_KEYWORDS
The region keywords as taken from facerec2010.baseline.lda.CohortLDA_KEYWORDS
"""
REGION_KEYWORDS : dict
The region keywords as taken from :py:attr:`facerec2010.baseline.lda.CohortLDA_KEYWORDS`.
"""
def __init__(self, REGION_ARGS, REGION_KEYWORDS):
bob.bio.base.extractor.Extractor.__init__(self, requires_training=True, split_training_data_by_client=True, **REGION_KEYWORDS)
self.ldair = facerec2010.baseline.lda.LRLDA(REGION_ARGS, **REGION_KEYWORDS)
self.layers = len(REGION_ARGS)
......@@ -72,13 +72,24 @@ class LDAIR (bob.bio.base.extractor.Extractor):
return [py_image.copy() for i in range(self.layers)]
def train(self, image_list, extractor_file):
"""Trains the LDA-IR module with the given image list and saves its result into the given extractor file using the pickle module."""
[self._check_image(image) for client_images in image_list for image in client_images]
def train(self, training_images, extractor_file):
"""Trains the LDA-IR module with the given image list.
The resulting object will be saved into the given ``extractor_file`` using the :py:func:`bob.bio.csu.save_pickle` function.
**Parameters:**
training_images : [[numpy.ndarray]]
The list of training images, which is split into images of the same clients.
extractor_file : str
The file to write into.
"""
[self._check_image(image) for client_images in training_images for image in client_images]
train_count = 0
for client_index in range(len(image_list)):
for client_index, client_images in enumerate(training_images):
# Initializes an arrayset for the data
for image in image_list[client_index]:
for image in client_images:
# create PIL image (since there are differences in the
# implementation of pyvision according to different image types)
# Additionally, PIL used pixels in (x,y) order
......@@ -96,7 +107,7 @@ class LDAIR (bob.bio.base.extractor.Extractor):
if self.use_cohort:
logger.info(" -> Adding cohort images")
# add image cohort for score normalization
for client_images in image_list:
for client_images in training_images:
# Initializes an arrayset for the data
for image in client_images:
pyimage = self._py_image(image)
......@@ -106,22 +117,35 @@ class LDAIR (bob.bio.base.extractor.Extractor):
# and write the result to file, which in this case simply used pickle
utils.save_pickle(self.ldair, extractor_file)
# remember the length of the produced feature
# self.feature_length = self.ldair.regions[0][2].lda_vecs.shape[1]
# for r in self.ldair.regions: assert r[2].lda_vecs.shape[1] == self.feature_length
def load(self, extractor_file):
"""Loads the LDA-IR from the given extractor file using the pickle module."""
"""Loads the LDA-IR from the given extractor file using the :py:func:`bob.bio.csu.load_pickle` function.
**Parameters:**
extractor_file : str
The file to be read, which has been written by the :py:meth:`train` function.
"""
# read LDA-IR extractor
self.ldair = utils.load_pickle(extractor_file)
# remember the length of the produced feature
# self.feature_length = self.ldair.regions[0][2].lda_vecs.shape[1]
# for r in self.ldair.regions: assert r[2].lda_vecs.shape[1] == self.feature_length
def __call__(self, image):
"""Projects the data using LDA-IR."""
"""__call__(image) -> extracted
Extracts image features using LDA-IR.
**Parameters:**
image : 3D :py:class:`numpy.ndarray`
The color image to project.
**Returns:**
extracted : :py:class:`facerec2010.baseline.common.FaceRecord`
The extracted image feature.
"""
self._check_image(image)
# create pvimage
pyimage = self._py_image(image)
......@@ -132,13 +156,35 @@ class LDAIR (bob.bio.base.extractor.Extractor):
def write_feature(self, feature, feature_file):
"""Saves the projected LDA-IR feature to file using the pickle module."""
"""Saves the extracted LDA-IR feature to file using :py:func:`bob.bio.csu.save_pickle`.
**Parameters:**
feature : :py:class:`facerec2010.baseline.common.FaceRecord`
The extracted feature to be written.
feature_file : str or :py:class:`bob.io.base.HDF5File`
The name of the file, or the file opened for writing.
"""
# write the feature to a .pkl file
# (since FaceRecord does not have a save method)
utils.save_pickle(feature, feature_file)
def read_feature(self, feature_file):
"""Reads the projected LDA-IR feature from file using the pickle module."""
"""read_feature(feature_file) -> feature
Reads the extracted LDA-IR feature from file using :py:func:`bob.bio.csu.load_pickle`.
**Parameters:**
feature_file : str or :py:class:`bob.io.base.HDF5File`
The name of the file, or the file opened for reading.
**Returns:**
feature : :py:class:`facerec2010.baseline.common.FaceRecord`
The read feature.
"""
# read the feature from .pkl file
return utils.load_pickle(feature_file)
......@@ -29,14 +29,15 @@ import logging
logger = logging.getLogger("bob.bio.csu")
class LRPCA (bob.bio.base.extractor.Extractor):
"""This class defines a wrapper for the facerec2010.baseline.lrpca.LRPCA class to be used as a :py:class:`facereclib.feature.Extractor` in the :ref:`FaceRecLib <facereclib>`."""
"""This class defines a wrapper for the :py:class:`facerec2010.baseline.lda.LRPCA` class to be used as an image :py:class:`bob.bio.base.extractor.Extractor`.
def __init__(self, TUNING):
"""Constructor Documentation:
**Parameters:**
TUNING
The tuning for the LRPCA algorithm as taken from the facerec2010.baseline.lrpca.GBU_TUNING
"""
TUNING : dict
The tuning for the LRPCA algorithm as taken from the :py:attr:`facerec2010.baseline.lrpca.GBU_TUNING`.
"""
def __init__(self, TUNING):
bob.bio.base.extractor.Extractor.__init__(self, requires_training=True, split_training_data_by_client=True, **TUNING)
self.lrpca = facerec2010.baseline.lrpca.LRPCA(**TUNING)
......@@ -60,11 +61,22 @@ class LRPCA (bob.bio.base.extractor.Extractor):
return py_image
def train(self, image_list, extractor_file):
"""Trains the LRPCA module with the given image list and saves the result into the given extractor file using the pickle module."""
def train(self, training_images, extractor_file):
"""Trains the LRPCA module with the given image list.
The resulting object will be saved into the given ``extractor_file`` using the :py:func:`bob.bio.csu.save_pickle` function.
**Parameters:**
training_images : [[numpy.ndarray]]
The list of training images, which is split into images of the same clients.
extractor_file : str
The file to write into.
"""
train_count = 0
for client_index in range(len(image_list)):
for image in image_list[client_index]:
for client_index, client_images in enumerate(training_images):
for image in client_images:
# convert the image into a data type that is understood by FaceRec2010
pyimage = self._py_image(image)
......@@ -83,13 +95,34 @@ class LRPCA (bob.bio.base.extractor.Extractor):
def load(self, extractor_file):
"""Loads the trained LRPCA feature extractor from the given extractor file using the pickle module."""
"""Loads the trained LRPCA feature extractor from the given ``extractor_file`` using the :py:func:`bob.bio.csu.load_pickle` function.
**Parameters:**
extractor_file : str
The file to be read, which has been written by the :py:meth:`train` function.
"""
# read LRPCA projector
self.lrpca = utils.load_pickle(extractor_file)
def __call__(self, image):
"""Projects the image data using the LRPCA projector and returns a numpy.ndarray."""
"""__call__(image) -> extracted
Extracts image features using LRPCA.
The returned value is just the :py:attr:`facerec2010.baseline.common.FaceRecord.feature` array.
**Parameters:**
image : 2D :py:class:`numpy.ndarray`
The color image to project.
**Returns:**
extracted : :py:class:`numpy.ndarray`
The extracted image feature.
"""
# create pvimage
pyimage = self._py_image(image)
# Projects the data by creating a "FaceRecord"
......
......@@ -23,25 +23,40 @@ import numpy
import bob.bio.base
class LDAIR (bob.bio.base.preprocessor.Preprocessor):
"""This class defines a wrapper for the facerec2010.baseline.lda.LRLDA class to be used as an image :py:class:`facereclib.preprocessing.Preprocessor` in the :ref:`FaceRecLib <facereclib>`."""
"""This class defines a wrapper for the :py:class:`facerec2010.baseline.lda.LRLDA` class to be used as an image :py:class:`bob.bio.base.preprocessor.Preprocessor`.
def __init__(self, REGION_ARGS, REGION_KEYWORDS):
"""Constructor Documentation:
**Parameters:**
REGION_ARGS
The region arguments as taken from facerec2010.baseline.lda.CohortLDA_REGIONS
REGION_ARGS
The region arguments as taken from :py:attr:`facerec2010.baseline.lda.CohortLDA_REGIONS`.
REGION_KEYWORDS
The region keywords as taken from facerec2010.baseline.lda.CohortLDA_KEYWORDS
"""
REGION_KEYWORDS
The region keywords as taken from :py:attr:`facerec2010.baseline.lda.CohortLDA_KEYWORDS`.
"""
def __init__(self, REGION_ARGS, REGION_KEYWORDS):
bob.bio.base.preprocessor.Preprocessor.__init__(self, **REGION_KEYWORDS)
self.ldair = facerec2010.baseline.lda.LRLDA(REGION_ARGS, **REGION_KEYWORDS)
self.layers = len(REGION_ARGS)
def __call__(self, image, annotations):
"""Preprocesses the image using the LDA-IR preprocessor facerec2010.baseline.lda.LRLDA.preprocess"""
"""Preprocesses the image using the LDA-IR preprocessor :py:meth:`facerec2010.baseline.lda.LRLDA.preprocess`.
**Parameters:**
image : :py:class:`pyvision.Image` or :py:class:`numpy.ndarray`
The color image that should be preprocessed.
annotations : dict
The eye annotations for the image.
They need to be specified as ``{'reye' : (re_y, re_x), 'leye' : (le_y, le_x)}``, where right and left is in subject perspective.
**Returns:**
preprocessed : 3D numpy.ndarray
The preprocessed color image, in default Bob format.
"""
# assure that the eye positions are in the set of annotations
if annotations is None or 'leye' not in annotations or 'reye' not in annotations:
......@@ -83,6 +98,19 @@ class LDAIR (bob.bio.base.preprocessor.Preprocessor):
def read_original_data(self, image_file):
"""Reads the original images using functionality from pyvision."""
"""read_original_data(image_file) -> image
Reads the original images using functionality from pyvision.
**Parameters:**
image_file : str
The image file to be read, can contain a gray level or a color image.
**Returns:**
image : :py:class:`pyvision.Image`
The image read from file.
"""
# we use pyvision to read the images. Hence, we don't have to struggle with conversion here
return pyvision.Image(str(image_file))
......@@ -23,20 +23,37 @@ import numpy
import bob.bio.base
class LRPCA (bob.bio.base.preprocessor.Preprocessor):
"""This class defines a wrapper for the facerec2010.baseline.lrpca.LRPCA class to be used as an image :py:class:`facereclib.preprocessing.Preprocessor` in the :ref:`FaceRecLib <facereclib>`."""
"""This class defines a wrapper for the :py:class:`facerec2010.baseline.lda.LRPCA` class to be used as an image :py:class:`bob.bio.base.preprocessor.Preprocessor`.
def __init__(self, TUNING):
"""Constructor Documentation:
**Parameters:**
TUNING
The tuning for the LRPCA algorithm as taken from the facerec2010.baseline.lrpca.GBU_TUNING
"""
TUNING : dict
The tuning for the LRPCA algorithm as taken from the :py:attr:`facerec2010.baseline.lrpca.GBU_TUNING`.
"""
def __init__(self, TUNING):
bob.bio.base.preprocessor.Preprocessor.__init__(self, **TUNING)
self.lrpca = facerec2010.baseline.lrpca.LRPCA(**TUNING)
def __call__(self, image, annotations):
"""Preprocesses the image using the facerec2010.baseline.lrpca.LRPCA.preprocess function"""
"""__call__(image, annotations) -> preprocessed
Preprocesses the image using the :py:meth:`facerec2010.baseline.lrpca.LRPCA.preprocess` function.
**Parameters:**
image : :py:class:`pyvision.Image` or :py:class:`numpy.ndarray`
The gray level or color image that should be preprocessed.
annotations : dict
The eye annotations for the image.
They need to be specified as ``{'reye' : (re_y, re_x), 'leye' : (le_y, le_x)}``, where right and left is in subject perspective.
**Returns:**
preprocessed : numpy.ndarray
The preprocessed image, in default Bob format.
"""
assert isinstance(image, (pyvision.Image, numpy.ndarray))
# assure that the eye positions are in the set of annotations
......@@ -58,6 +75,19 @@ class LRPCA (bob.bio.base.preprocessor.Preprocessor):
def read_original_data(self, image_file):
"""Reads the original images using functionality from pyvision."""
"""read_original_data(image_file) -> image
Reads the original images using functionality from pyvision.
**Parameters:**
image_file : str
The image file to be read, can contain a gray level or a color image.
**Returns:**
image : :py:class:`pyvision.Image`
The image read from file.
"""
# we use pyvision to read the images. Hence, we don't have to struggle with conversion here
return pyvision.Image(str(image_file))
......@@ -130,12 +130,12 @@ if sphinx.__version__ >= "1.0":
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = ''
html_logo = 'img/logo.png'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
html_favicon = ''
html_favicon = 'img/favicon.ico'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
......@@ -243,8 +243,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', 'bob.io.base', 'bob.bio.base'])
intersphinx_mapping = link_documentation()
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)
......@@ -8,11 +8,20 @@
Wrapper classes for the CSU facerec2010 classes
=================================================
This satellite package to the FaceRecLib_ provides wrapper classes for the `CSU Face Recognition Resources`_.
This package is part of the ``bob.bio`` packages.
It provides wrapper classes for the `CSU Face Recognition Resources`_.
Two algorithms are provided by the CSU toolkit (and also by this satellite package): the local region PCA (LRPCA) and the LDA-IR (also known as CohortLDA).
This package does not include the source code of the `CSU Face Recognition Resources`_ itself.
For installation instructions of the original source code, please read :ref:`bob.bio.csu.installation`.
For more detailed information about the structure of the ``bob.bio`` packages, please refer to the documentation of :ref:`bob.bio.base <bob.bio.base>`.
Particularly, the installation of this and other ``bob.bio`` packages, please read the :ref:`bob.bio.base.installation`.
In the following, we provide more detailed information about the particularities of this package only.
In fact, this satallite package just provides the source to be able to execute experiments using LRPCA and LDA-IR.