Python API¶

A verification database based on filelists

bob.db.bio_filelist.get_config()[source]¶: Returns a string containing the configuration information.

class bob.db.bio_filelist.Client(client_id)[source]¶

Bases: object

The clients of this database contain ONLY client ids. Nothing special.

class bob.db.bio_filelist.Database(base_dir, original_directory=None, original_extension=None, annotation_directory=None, annotation_extension='.pos', annotation_type='eyecenter', dev_subdir=None, eval_subdir=None, world_filename=None, optional_world_1_filename=None, optional_world_2_filename=None, models_filename=None, probes_filename=None, scores_filename=None, tnorm_filename=None, znorm_filename=None, use_dense_probe_file_list=None, keep_read_lists_in_memory=True)[source]¶

Bases: object

This class provides a user-friendly interface to databases that are given as file lists.

Keyword parameters:

base_dir: The directory that contains the filelists defining the protocol(s). If you use the protocol attribute when querying the database, it will be appended to the base directory, such that several protocols are supported by the same class instance of bob.db.bio_filelist.
original_directory: The directory, where the original data can be found
original_extension: The filename extension of the original data, or multiple extensions
annotation_directory: The directory, where additional annotation files can be found
annotation_extension: The filename extension of the annoation files
annotation_type: The type of annotation that can be read. Currently, options are ‘eyecenter’, ‘named’, ‘idiap’. See bob.db.base.annotations.read_annotation_file() for details.
dev_subdir: Specify a custom subdirectory for the filelists of the development set (default is ‘dev’)
eval_subdir: Specify a custom subdirectory for the filelists of the development set (default is ‘eval’)
world_filename: Specify a custom filename for the training filelist (default is ‘norm/train_world.lst’)
optional_world_1_filename: Specify a custom filename for the (first optional) training filelist (default is ‘norm/train_optional_world_1.lst’)
optional_world_2_filename: Specify a custom filename for the (second optional) training filelist (default is ‘norm/train_optional_world_2.lst’)
models_filename: Specify a custom filename for the model filelists (default is ‘for_models.lst’)
probes_filename: Specify a custom filename for the probes filelists (default is ‘for_probes.lst’)
scores_filename: Specify a custom filename for the scores filelists (default is ‘for_scores.lst’)
tnorm_filename: Specify a custom filename for the T-norm scores filelists (default is ‘for_tnorm.lst’)
znorm_filename: Specify a custom filename for the Z-norm scores filelists (default is ‘for_znorm.lst’)
use_dense_probe_file_list: Specify which list to use among ‘probes_filename’ (dense) or ‘scores_filename’. If None it is tried to be estimated based on the given parameters.
keep_read_lists_in_memory: If set to true, the lists are read only once and stored in memory

annotations(file)[source]¶

Reads the annotations for the given file id from file and returns them in a dictionary.

If you don’t have a copy of the annotation files, you can download them under http://www.idiap.ch/resource/biometric.

Keyword parameters:

file: The File object for which the annotations should be read.
Return value: The annotations as a dictionary: {‘reye’:(re_y,re_x), ‘leye’:(le_y,le_x)}

check_parameters_for_validity(parameters, parameter_description, valid_parameters, default_parameters=None)[source]¶

Checks the given parameters for validity, i.e., if they are contained in the set of valid parameters. It also assures that the parameters form a tuple or a list. If parameters is ‘None’ or empty, the default_parameters will be returned (if default_parameters is omitted, all valid_parameters are returned). This function will return a tuple or list of parameters, or raise a ValueError.

This method was imported from the former bob.db.verification.utils

Keyword parameters:

parameters: The parameters to be checked. Might be a string, a list/tuple of strings, or None.
parameter_description: A short description of the parameter. This will be used to raise an exception in case the parameter is not valid.
valid_parameters: A list/tuple of valid values for the parameters.
default_parameters: The list/tuple of default parameters that will be returned in case parameters is None or empty. If omitted, all valid_parameters are used.

client_ids(protocol=None, groups=None)[source]¶

Returns a list of client ids for the specific query by the user.

Keyword Parameters:

protocol: The protocol to consider
groups: The groups to which the clients belong (“dev”, “eval”, “world”, “optional_world_1”, “optional_world_2”).

Returns: A list containing all the client ids which have the given properties.

clients(protocol=None, groups=None)[source]¶

Returns a list of Client objects for the specific query by the user.

Keyword Parameters:

protocol: The protocol to consider
groups: The groups to which the clients belong (“dev”, “eval”, “world”, “optional_world_1”, “optional_world_2”).

Returns: A list containing all the Client objects which have the given properties.

get_base_directory()[source]¶: Returns the base directory where the filelists defining the database are located.

get_client_id_from_model_id(model_id, groups=None, protocol=None)[source]¶

Returns the client id that is connected to the given model id.

Keyword parameters:

model_id: The model id for which the client id should be returned.
groups: (optional) the groups, the client belongs to. Might be one or more of (‘dev’, ‘eval’, ‘world’, ‘optional_world_1’, ‘optional_world_2’). If groups are given, only these groups are considered.
protocol: The protocol to consider

Returns: The client id for the given model id, if found.

get_client_id_from_tmodel_id(model_id, groups=None, protocol=None)[source]¶

Returns the client id that is connected to the given T-Norm model id.

Keyword parameters:

model_id: The model id for which the client id should be returned.
groups: (optional) the groups, the client belongs to. Might be one or more of (‘dev’, ‘eval’). If groups are given, only these groups are considered.
protocol: The protocol to consider

Returns: The client id for the given model id of a T-Norm model, if found.

get_list_file(group, type=None, protocol=None)[source]¶

groups(protocol=None)[source]¶

This function returns the list of groups for this database.

protocol: The protocol for which the groups should be retrieved.

Returns: a list of groups

implements_zt(protocol=None, groups=None)[source]¶

Checks if the file lists for the ZT score normalization are available.

Keyword Parameters:

protocol: The protocol for which the groups should be retrieved.
groups: The groups for which the ZT score normalization file lists should be checked (“dev”, “eval”).

Returns:	`True` if the all file lists for ZT score normalization exist, otherwise `False`.

model_ids(protocol=None, groups=None)[source]¶

Returns a list of model ids for the specific query by the user.

Keyword Parameters:

protocol: The protocol to consider
groups: The groups to which the models belong (“dev”, “eval”, “world”, “optional_world_1”, “optional_world_2”).

Returns: A list containing all the model ids which have the given properties.

objects(protocol=None, purposes=None, model_ids=None, groups=None, classes=None)[source]¶

Returns a set of File objects for the specific query by the user.

Keyword Parameters:

protocol: The protocol to consider
purposes: The purposes required to be retrieved (“enroll”, “probe”) or a tuple with several of them. If ‘None’ is given (this is the default), it is considered the same as a tuple with all possible values. This field is ignored for the data from the “world”, “optional_world_1”, “optional_world_2” groups.
model_ids: Only retrieves the files for the provided list of model ids (claimed client id). If ‘None’ is given (this is the default), no filter over the model_ids is performed.
groups: One of the groups (“dev”, “eval”, “world”, “optional_world_1”, “optional_world_2”) or a tuple with several of them. If ‘None’ is given (this is the default), it is considered the same as a tuple with all possible values.
classes: The classes (types of accesses) to be retrieved (‘client’, ‘impostor’) or a tuple with several of them. If ‘None’ is given (this is the default), it is considered the same as a tuple with all possible values. Note: classes are not allowed to be specified when the ‘probes_filename’ is used.

Returns: A list of File objects considering all the filtering criteria.

original_file_name(file, check_existence=True)[source]¶

Returns the original file name of the given file.

This interface supports several original extensions, so that file lists can contain images of different data types.

When multiple original extensions are specified, this function will check the existence of any of these file names, and return the first one that actually exists. In this case, the check_existence flag is ignored.

Keyword parameters

file: The py:class:File object for which the file name should be returned.
check_existence: Should the existence of the original file be checked? (Ignored when multiple original extensions were specified in the contructor.)

Returns str : The full path of the original data file.

set_base_directory(base_dir)[source]¶: Resets the base directory where the filelists defining the database are located.

tclient_ids(protocol=None, groups=None)[source]¶

Returns a list of T-Norm client ids for the specific query by the user.

Keyword Parameters:

protocol: The protocol to consider
groups: The groups to which the clients belong (“dev”, “eval”).

Returns: A list containing all the T-Norm client ids which have the given properties.

tclients(protocol=None, groups=None)[source]¶

Returns a list of T-Norm Client objects for the specific query by the user.

Keyword Parameters:

protocol: The protocol to consider
groups: The groups to which the clients belong (“dev”, “eval”).

Returns: A list containing all the T-Norm Client objects which have the given properties.

tmodel_ids(protocol=None, groups=None)[source]¶

Returns a list of T-Norm model ids for the specific query by the user.

Keyword Parameters:

protocol: The protocol to consider
groups: The groups to which the models belong (“dev”, “eval”).

Returns: A list containing all the T-Norm model ids belonging to the given group.

tobjects(protocol=None, model_ids=None, groups=None)[source]¶

Returns a list of File objects for enrolling T-norm models for score normalization.

Keyword Parameters:

protocol: The protocol to consider
model_ids: Only retrieves the files for the provided list of model ids (claimed client id). If ‘None’ is given (this is the default), no filter over the model_ids is performed.
groups: The groups to which the models belong (“dev”, “eval”).

Returns: A list of File objects considering all the filtering criteria.

zclient_ids(protocol=None, groups=None)[source]¶

Returns a list of Z-Norm client ids for the specific query by the user.

Keyword Parameters:

protocol: The protocol to consider
groups: The groups to which the clients belong (“dev”, “eval”).

Returns: A list containing all the Z-Norm client ids which have the given properties.

zclients(protocol=None, groups=None)[source]¶

Returns a list of Z-Norm Client objects for the specific query by the user.

Keyword Parameters:

protocol: The protocol to consider
groups: The groups to which the models belong (“dev”, “eval”).

Returns: A list containing all the Z-Norm Client objects which have the given properties.

zobjects(protocol=None, groups=None)[source]¶

Returns a list of File objects to perform Z-norm score normalization.

Keyword Parameters:

protocol: The protocol to consider
groups: The groups to which the clients belong (“dev”, “eval”).

Returns: A list of File objects considering all the filtering criteria.

class bob.db.bio_filelist.File(file_name, client_id, model_id=None, claimed_id=None)[source]¶

Bases: bob.db.base.File

Initialize the File object with the minimum required data.

If the model_id is not specified, model_id and client_id are identical. If the claimed_id is not specified, it is expected to be the client_id.

Parameters

client_id: The id of the client, this file belongs to. The type of it is dependent on your implementation. If you use an SQL database, this should be an SQL type like Integer or String.
path: The path of this file, relative to the basic directory. If you use an SQL database, this should be the SQL type String. Please do not specify any file extensions.
file_id: The id of the file. The type of it is dependent on your implementation. If you use an SQL database, this should be an SQL type like Integer or String. If you are using an automatically determined file id, you can skip selecting the file id.

load(directory=None, extension='.hdf5')[source]¶

Loads the data at the specified location and using the given extension. Override it if you need to load differently.

Keyword Parameters:

data: The data blob to be saved (normally a numpy.ndarray).
directory: [optional] If not empty or None, this directory is prefixed to the final file destination
extension: [optional] The extension of the filename - this will control the type of output and the codec for saving the input blob.

make_path(directory=None, extension=None)[source]¶

Wraps the current path so that a complete path is formed

Keyword Parameters:

directory: An optional directory name that will be prefixed to the returned result.
extension: An optional extension that will be suffixed to the returned filename. The extension normally includes the leading . character as in .jpg or .hdf5.

Returns a string containing the newly generated file path.

save(data, directory=None, extension='.hdf5', create_directories=True)[source]¶

Saves the input data at the specified location and using the given extension. Override it if you need to save differently.

Keyword Parameters:

data: The data blob to be saved (normally a numpy.ndarray).
directory: [optional] If not empty or None, this directory is prefixed to the final file destination
extension: [optional] The extension of the filename - this will control the type of output and the codec for saving the input blob.