Python API

Note

If this section is empty, please go to the console and type:

$ ./bin/sphinx-build doc sphinx

again, after you have successfully patched the CSU code.

LRPCA

LDA-IR

Details

Generic functions

bob.bio.csu.get_config()

Returns a string containing the configuration information.

bob.bio.csu.load_pickle(file_like) → data

Loads a file that was written with the save_pickle() function and returns its content.

Keyword Parameters

file_like: bob.io.base.HDF5File or str

The file containing the data to be read.

Returns*

data : various types

The data read from the file.

bob.bio.csu.save_pickle(data, file_like) → None

Saves the given data in the given file using the pickle module.

The data is first pickled into a string, which is written into the given file

Keyword Parameters

data : various types

The data write into the file. The data type must support pickling.

file_like: bob.io.base.HDF5File or str

The file or the name of the file to write. If file_like is of type bob.io.base.HDF5File, it needs to be open for writing.

Preprocessors

class bob.bio.csu.preprocessor.LDAIR(REGION_ARGS, REGION_KEYWORDS)

Bases: bob.bio.base.preprocessor.Preprocessor.Preprocessor

This class defines a wrapper for the facerec2010.baseline.lda.LRLDA class to be used as an image bob.bio.base.preprocessor.Preprocessor.

Parameters:

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.

__call__(image, annotations)

Preprocesses the image using the LDA-IR preprocessor facerec2010.baseline.lda.LRLDA.preprocess().

Parameters:

image : pyvision.Image or 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.

read_data(data_file) → data

Reads the preprocessed data from file. In this base class implementation, it uses bob.bio.base.load() to do that. If you have different format, please overwrite this function.

Parameters:

data_file : str or bob.io.base.HDF5File

The file open for reading or the name of the file to read from.

Returns:

data : object (usually numpy.ndarray)

The preprocessed data read from file.

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 : pyvision.Image

The image read from file.

write_data(data, data_file)

Writes the given preprocessed data to a file with the given name. In this base class implementation, we simply use bob.bio.base.save() for that. If you have a different format (e.g. not images), please overwrite this function.

Parameters:

data : object

The preprocessed data, i.e., what is returned from __call__().

data_file : str or bob.io.base.HDF5File

The file open for writing, or the name of the file to write.

class bob.bio.csu.preprocessor.LRPCA(TUNING)

Bases: bob.bio.base.preprocessor.Preprocessor.Preprocessor

This class defines a wrapper for the facerec2010.baseline.lda.LRPCA class to be used as an image bob.bio.base.preprocessor.Preprocessor.

Parameters:

TUNING : dict

The tuning for the LRPCA algorithm as taken from the facerec2010.baseline.lrpca.GBU_TUNING.

__call__(image, annotations) → preprocessed

Preprocesses the image using the facerec2010.baseline.lrpca.LRPCA.preprocess() function.

Parameters:

image : pyvision.Image or 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.

read_data(data_file) → data

Reads the preprocessed data from file. In this base class implementation, it uses bob.bio.base.load() to do that. If you have different format, please overwrite this function.

Parameters:

data_file : str or bob.io.base.HDF5File

The file open for reading or the name of the file to read from.

Returns:

data : object (usually numpy.ndarray)

The preprocessed data read from file.

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 : pyvision.Image

The image read from file.

write_data(data, data_file)

Writes the given preprocessed data to a file with the given name. In this base class implementation, we simply use bob.bio.base.save() for that. If you have a different format (e.g. not images), please overwrite this function.

Parameters:

data : object

The preprocessed data, i.e., what is returned from __call__().

data_file : str or bob.io.base.HDF5File

The file open for writing, or the name of the file to write.

Extractors

class bob.bio.csu.extractor.LDAIR(REGION_ARGS, REGION_KEYWORDS)

Bases: bob.bio.base.extractor.Extractor.Extractor

This class defines a wrapper for the facerec2010.baseline.lda.LRLDA class to be used as an image bob.bio.base.extractor.Extractor.

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.

__call__(image) → extracted

Extracts image features using LDA-IR.

Parameters:

image : 3D numpy.ndarray

The color image to project.

Returns:

extracted : facerec2010.baseline.common.FaceRecord

The extracted image feature.

load(extractor_file)

Loads the LDA-IR from the given extractor file using the bob.bio.csu.load_pickle() function.

Parameters:

extractor_file : str

The file to be read, which has been written by the train() function.

read_feature(feature_file) → feature

Reads the extracted LDA-IR feature from file using bob.bio.csu.load_pickle().

Parameters:

feature_file : str or bob.io.base.HDF5File

The name of the file, or the file opened for reading.

Returns:

feature : facerec2010.baseline.common.FaceRecord

The read feature.

train(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 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.

write_feature(feature, feature_file)

Saves the extracted LDA-IR feature to file using bob.bio.csu.save_pickle().

Parameters:

feature : facerec2010.baseline.common.FaceRecord

The extracted feature to be written.

feature_file : str or bob.io.base.HDF5File

The name of the file, or the file opened for writing.

class bob.bio.csu.extractor.LRPCA(TUNING)

Bases: bob.bio.base.extractor.Extractor.Extractor

This class defines a wrapper for the facerec2010.baseline.lda.LRPCA class to be used as an image bob.bio.base.extractor.Extractor.

Parameters:

TUNING : dict

The tuning for the LRPCA algorithm as taken from the facerec2010.baseline.lrpca.GBU_TUNING.

__call__(image) → extracted

Extracts image features using LRPCA. The returned value is just the facerec2010.baseline.common.FaceRecord.feature array.

Parameters:

image : 2D numpy.ndarray

The color image to project.

Returns:

extracted : numpy.ndarray

The extracted image feature.

load(extractor_file)

Loads the trained LRPCA feature extractor from the given extractor_file using the bob.bio.csu.load_pickle() function.

Parameters:

extractor_file : str

The file to be read, which has been written by the train() function.

read_feature(feature_file)

Reads the extracted feature from file. In this base class implementation, it uses bob.bio.base.load() to do that. If you have different format, please overwrite this function.

Parameters:

feature_file : str or bob.io.base.HDF5File

The file open for reading or the name of the file to read from.

Returns:

feature : object (usually numpy.ndarray)

The feature read from file.

train(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 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.

write_feature(feature, feature_file)

Writes the given extracted feature to a file with the given name. In this base class implementation, we simply use bob.bio.base.save() for that. If you have a different format, please overwrite this function.

Parameters:

feature : object

The extracted feature, i.e., what is returned from __call__().

feature_file : str or bob.io.base.HDF5File

The file open for writing, or the name of the file to write.

Algorithms

class bob.bio.csu.algorithm.LDAIR(REGION_ARGS, REGION_KEYWORDS, multiple_model_scoring='max', multiple_probe_scoring='max')

Bases: bob.bio.base.algorithm.Algorithm.Algorithm

This class defines a wrapper for the facerec2010.baseline.lda.LRLDA class to be used as an image 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 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 bob.bio.base.score_fusion_strategy() for more information.

enroll(enroll_features) → model

Enrolls a model from features from several images by simply storing all given features.

Parameters:

enroll_features : [facerec2010.baseline.common.FaceRecord]

The features used to enroll the model.

Returns:

model : [facerec2010.baseline.common.FaceRecord]

The model, which is identical to the enroll_features.

load_enroller(enroller_file)

Loads the parameters required for model enrollment from file. This function usually is only useful in combination with the train_enroller() function. This function is always called after calling load_projector(). In this base class implementation, it does nothing.

Parameters:

enroller_file : str

The file to read the enroller from.

load_projector(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”

project(feature) → projected

This function will project the given feature. It must be overwritten by derived classes, as soon as performs_projection = True was set in the constructor. It is assured that the load_projector() was called once before the project function is executed.

Parameters:

feature : object

The feature to be projected.

Returns:

projected : object

The projected features. Must be writable with the write_feature() function and readable with the read_feature() function.

read_feature(feature_file) → feature

Reads the projected feature from file. In this base class implementation, it uses bob.io.base.load() to do that. If you have different format, please overwrite this function.

Please register performs_projection = True in the constructor to enable this function.

Parameters:

feature_file : str or bob.io.base.HDF5File

The file open for reading, or the file name to read from.

Returns:

feature : object

The feature that was read from file.

read_model(model_file) → model

Loads an enrolled model from file using the bob.bio.csu.load_pickle() function.

Parameters:

model_file : str

The name of the model file to be read.

Returns:

model : [facerec2010.baseline.common.FaceRecord]

The model read from file.

read_probe(model_file)

read_model(model_file) -> model

Loads an enrolled model from file using the bob.bio.csu.load_pickle() function.

Parameters:

model_file : str

The name of the model file to be read.

Returns:

model : [facerec2010.baseline.common.FaceRecord]

The model read from file.

score(model, probe) → score

Compute the score for the given model (a list of FaceRecords) and a probe (a FaceRecord).

Parameters:

model : [facerec2010.baseline.common.FaceRecord]

The model to compare, which is actually a list of extracted features.

probe : 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.

score_for_multiple_models(models, probe) → score

This function computes the score between the given model list and the given probe. In this base class implementation, it computes the scores for each model using the score() method, and fuses the scores using the fusion method specified in the constructor of this class. Usually this function is called from derived class score() functions.

Parameters:

models : [object]

A list of model objects.

probe : object

The probe object to compare the models with.

Returns:

score : float

The fused similarity between the given models and the probe.

score_for_multiple_probes(model, probes) → score

This function computes the score between the given model and the given probe files. In this base class implementation, it computes the scores for each probe file using the score() method, and fuses the scores using the fusion method specified in the constructor of this class.

Parameters:

model : object

A model object to compare the probes with.

probes : [object]

The list of probe object to compare the models with.

Returns:

score : float

The fused similarity between the given model and the probes.

train_enroller(training_features, enroller_file)

This function can be overwritten to train the model enroller. If you do this, please also register the function by calling this base class constructor and enabling the training by require_enroller_training = True.

Parameters:

training_features : [object] or [[object]]

A list of extracted features that can be used for training the projector. Features will be split into lists, each of which contains the features of a single (training-)client.

enroller_file : str

The file to write. This file should be readable with the load_enroller() function.

train_projector(training_features, projector_file)

This function can be overwritten to train the feature projector. If you do this, please also register the function by calling this base class constructor and enabling the training by requires_projector_training = True.

Parameters:

training_features : [object] or [[object]]

A list of extracted features that can be used for training the projector. Features will be provided in a single list, if split_training_features_by_client = False was specified in the constructor, otherwise the features will be split into lists, each of which contains the features of a single (training-)client.

projector_file : str

The file to write. This file should be readable with the load_projector() function.

write_feature(feature, feature_file)

Saves the given projected feature to a file with the given name. In this base class implementation:

• If the given feature has a save attribute, it calls feature.save(bob.io.base.HDF5File(feature_file), 'w'). In this case, the given feature_file might be either a file name or a bob.io.base.HDF5File.
• Otherwise, it uses bob.io.base.save() to do that.

If you have a different format, please overwrite this function.

Please register ‘performs_projection = True’ in the constructor to enable this function.

Parameters:

feature : object

A feature as returned by the project() function, which should be written.

feature_file : str or bob.io.base.HDF5File

The file open for writing, or the file name to write to.

write_model(model, model_file)

Saves the enrolled model to file using the bob.bio.csu.save_pickle() function.

Parameters:

model : [facerec2010.baseline.common.FaceRecord]

The model to be written.

model_file : str

The name of the model file that is written.

class bob.bio.csu.algorithm.LRPCA(TUNING, multiple_model_scoring='max', multiple_probe_scoring='max')

Bases: bob.bio.base.algorithm.Algorithm.Algorithm

This class defines a wrapper for the facerec2010.baseline.lda.LRPCA class to be used as an image bob.bio.base.algorithm.Algorithm.

Parameters:

TUNING : dict

The tuning for the LRPCA algorithm as taken from the facerec2010.baseline.lrpca.GBU_TUNING.

multiple_model_scoring : str

The scoring strategy if models are enrolled from several images, see 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 bob.bio.base.score_fusion_strategy() for more information.

enroll(enroll_features) → model

Enrolls a model from features from several images by simply storing all given features.

Parameters:

enroll_features : [numpy.ndarray]

The features used to enroll the model.

Returns:

model : [facerec2010.baseline.pca.FaceRecord]

The model, which a collection of face records, storing the given enroll_features.

load_enroller(enroller_file)

Loads the parameters required for model enrollment from file. This function usually is only useful in combination with the train_enroller() function. This function is always called after calling load_projector(). In this base class implementation, it does nothing.

Parameters:

enroller_file : str

The file to read the enroller from.

load_projector(projector_file)

Loads the parameters required for feature projection from file. This function usually is useful in combination with the train_projector() function. In this base class implementation, it does nothing.

Please register performs_projection = True in the constructor to enable this function.

Parameters:

projector_file : str

The file to read the projector from.

project(feature) → projected

This function will project the given feature. It must be overwritten by derived classes, as soon as performs_projection = True was set in the constructor. It is assured that the load_projector() was called once before the project function is executed.

Parameters:

feature : object

The feature to be projected.

Returns:

projected : object

The projected features. Must be writable with the write_feature() function and readable with the read_feature() function.

read_feature(feature_file) → feature

Reads the projected feature from file. In this base class implementation, it uses bob.io.base.load() to do that. If you have different format, please overwrite this function.

Please register performs_projection = True in the constructor to enable this function.

Parameters:

feature_file : str or bob.io.base.HDF5File

The file open for reading, or the file name to read from.

Returns:

feature : object

The feature that was read from file.

read_model(model_file) → model

Loads an enrolled model from file using the bob.bio.csu.load_pickle() function.

Parameters:

model_file : str

The name of the model file to be read.

Returns:

model : [facerec2010.baseline.pca.FaceRecord]

The model read from file.

read_probe(probe_file) → probe

Reads the probe feature from file. By default, the probe feature is identical to the projected feature. Hence, this base class implementation simply calls read_feature().

If your algorithm requires different behavior, please overwrite this function.

Parameters:

probe_file : str or bob.io.base.HDF5File

The file open for reading, or the file name to read from.

Returns:

probe : object

The probe that was read from file.

score(model, probe) → score

Compute the score for the given model (a list of FaceRecords) and a probe (a FaceRecord).

Parameters:

model : [facerec2010.baseline.pca.FaceRecord]

The model to compare, which is actually a list of extracted features.

probe : 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.

score_for_multiple_models(models, probe) → score

This function computes the score between the given model list and the given probe. In this base class implementation, it computes the scores for each model using the score() method, and fuses the scores using the fusion method specified in the constructor of this class. Usually this function is called from derived class score() functions.

Parameters:

models : [object]

A list of model objects.

probe : object

The probe object to compare the models with.

Returns:

score : float

The fused similarity between the given models and the probe.

score_for_multiple_probes(model, probes) → score

This function computes the score between the given model and the given probe files. In this base class implementation, it computes the scores for each probe file using the score() method, and fuses the scores using the fusion method specified in the constructor of this class.

Parameters:

model : object

A model object to compare the probes with.

probes : [object]

The list of probe object to compare the models with.

Returns:

score : float

The fused similarity between the given model and the probes.

train_enroller(training_features, enroller_file)

This function can be overwritten to train the model enroller. If you do this, please also register the function by calling this base class constructor and enabling the training by require_enroller_training = True.

Parameters:

training_features : [object] or [[object]]

A list of extracted features that can be used for training the projector. Features will be split into lists, each of which contains the features of a single (training-)client.

enroller_file : str

The file to write. This file should be readable with the load_enroller() function.

train_projector(training_features, projector_file)

This function can be overwritten to train the feature projector. If you do this, please also register the function by calling this base class constructor and enabling the training by requires_projector_training = True.

Parameters:

training_features : [object] or [[object]]

A list of extracted features that can be used for training the projector. Features will be provided in a single list, if split_training_features_by_client = False was specified in the constructor, otherwise the features will be split into lists, each of which contains the features of a single (training-)client.

projector_file : str

The file to write. This file should be readable with the load_projector() function.

write_feature(feature, feature_file)

Saves the given projected feature to a file with the given name. In this base class implementation:

• If the given feature has a save attribute, it calls feature.save(bob.io.base.HDF5File(feature_file), 'w'). In this case, the given feature_file might be either a file name or a bob.io.base.HDF5File.
• Otherwise, it uses bob.io.base.save() to do that.

If you have a different format, please overwrite this function.

Please register ‘performs_projection = True’ in the constructor to enable this function.

Parameters:

feature : object

A feature as returned by the project() function, which should be written.

feature_file : str or bob.io.base.HDF5File

The file open for writing, or the file name to write to.

write_model(model, model_file)

Saves the enrolled model to file using the bob.bio.csu.save_pickle() function.

Parameters:

model : [facerec2010.baseline.pca.FaceRecord]

The model to be written.

model_file : str

The name of the model file that is written.