Python API

A verification database based on filelists

bob.db.verification.filelist.get_config()

Returns a string containing the configuration information.

class bob.db.verification.filelist.Client(client_id)

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

class bob.db.verification.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)

Bases: bob.db.verification.utils.database.ZTDatabase

This class provides a user-friendly interface to databases that are given as file lists. The API is comparable to other bob.db verification databases by implementing the bob.db.verification.utils.ZTDatabase interface.

Keyword parameters:

base_dir : str

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.verification.filelist.

original_directory : str or None

The directory, where the original data can be found

original_extension : str or [str] or None

The filename extension of the original data, or multiple extensions

annotation_directory : str or None

The directory, where additional annotation files can be found

annotation_extension : str or None

The filename extension of the annoation files

annotation_type : str or None

The type of annotation that can be read. Currently, options are ‘eyecenter’, ‘named’, ‘idiap’. See bob.db.verification.utils.read_annotation_file() for details.

dev_subdir : str or None

Specify a custom subdirectory for the filelists of the development set (default is ‘dev’)

eval_subdir : str or None

Specify a custom subdirectory for the filelists of the development set (default is ‘eval’)

world_filename : str or None

Specify a custom filename for the training filelist (default is ‘norm/train_world.lst’)

optional_world_1_filename : str or None

Specify a custom filename for the (first optional) training filelist (default is ‘norm/train_optional_world_1.lst’)

optional_world_2_filename : str or None

Specify a custom filename for the (second optional) training filelist (default is ‘norm/train_optional_world_2.lst’)

models_filename : str or None

Specify a custom filename for the model filelists (default is ‘for_models.lst’)

probes_filename : str or None

Specify a custom filename for the probes filelists (default is ‘for_probes.lst’)

scores_filename : str or None

Specify a custom filename for the scores filelists (default is ‘for_scores.lst’)

tnorm_filename : str or None

Specify a custom filename for the T-norm scores filelists (default is ‘for_tnorm.lst’)

znorm_filename : str or None

Specify a custom filename for the Z-norm scores filelists (default is ‘for_znorm.lst’)

use_dense_probe_file_list : bool or None

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 : bool

If set to true, the lists are read only once and stored in memory

Initializes the database with the file lists from the given base directory, and the given sub-directories and file names (which default to useful values if not given).

all_files(**kwargs)

Returns the list of all File objects that satisfy your query. For possible keyword arguments, please check the objects() function.

annotations(file)

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 : bob.db.verification.filelist.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_parameter_for_validity(parameter, parameter_description, valid_parameters, default_parameter=None)

Checks the given parameter for validity, i.e., if it is contained in the set of valid parameters. If the parameter is ‘None’ or empty, the default_parameter will be returned, in case it is specified, otherwise a ValueError will be raised.

This function will return the parameter after the check tuple or list of parameters, or raise a ValueError.

Keyword parameters:

parameter : str

The single parameter to be checked. Might be a string or None.

parameter_description : str

A short description of the parameter. This will be used to raise an exception in case the parameter is not valid.

valid_parameters : [str]

A list/tuple of valid values for the parameters.

default_parameters : [str] or None

The default parameter that will be returned in case parameter is None or empty. If omitted and parameter is empty, a ValueError is raised.

check_parameters_for_validity(parameters, parameter_description, valid_parameters, default_parameters=None)

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.

Keyword parameters:

parameters : str, [str] or None

The parameters to be checked. Might be a string, a list/tuple of strings, or None.

parameter_description : str

A short description of the parameter. This will be used to raise an exception in case the parameter is not valid.

valid_parameters : [str]

A list/tuple of valid values for the parameters.

default_parameters : [str] or None

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)

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

Keyword Parameters:

protocol : str or None

The protocol to consider

groups : str or [str] or None

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)

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

Keyword Parameters:

protocol : str or None

The protocol to consider

groups : str or [str] or None

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.

enroll_files(protocol=None, model_id=None, groups='dev', **kwargs)

Returns the list of enrollment File objects from the given model id of the given protocol for the given groups that satisfy your query. If the model_id is None (the default), enrollment files for all models are returned. For possible keyword arguments, please check the objects() function.

file_names(files, directory, extension)

This function returns the list of original file names for the given list of File objects.

Keyword parameters:

files : [File]

The list of File objects for which the file names should be retrieved

directory : str

The base directory where the files are stored

extension : str

The file name extension of the files

Return value : [str]

The file names for the given File objects, in the same order.

get_base_directory()

Returns the base directory where the filelists defining the database are located.

get_client_id_from_model_id(model_id, groups=None, protocol=None)

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

Keyword parameters:

model_id : str or None

The model id for which the client id should be returned.

groups : str or [str] or None

(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 : str or None

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)

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

Keyword parameters:

model_id : str or None

The model id for which the client id should be returned.

groups : str or [str] or None

(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 : str or None

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)

groups(protocol=None)

This function returns the list of groups for this database.

protocol : str or None

The protocol for which the groups should be retrieved.

Returns: a list of groups

implements_zt(protocol=None, groups=None)

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

Keyword Parameters:

protocol : str or None

The protocol for which the groups should be retrieved.

groups : str or [str] or None

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)

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

Keyword Parameters:

protocol : str or None

The protocol to consider

groups : str or [str] or None

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)

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

Keyword Parameters:

protocol : str or None

The protocol to consider

purposes : str or [str] or None

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 : str or [str] or None

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 : str or [str] or None

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 : str or [str] or None

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)

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 a single original extension is specified, the base class function bob.db.verification.utils.original_file_name() will be called.

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 : bob.db.verification.filelist.File

The py:class:File object for which the file name should be returned.

check_existence : bool

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.

original_file_names(files, check_existence=True)

This function returns the list of original file names for the given list of File objects.

Keyword parameters:

files : [File]

The list of File objects for which the file names should be retrieved

check_existence : bool

Check if the original files exists?

Return value : [str]

The original file names for the given File objects, in the same order.

probe_files(protocol=None, model_id=None, groups='dev', **kwargs)

Returns the list of probe File objects to probe the model with the given model id of the given protocol for the given groups that satisfy your query. If the model_id is None (the default), all possible probe files are returned. For possible keyword arguments, please check the objects() function.

provides_file_set_for_protocol(protocol=None)

Returns True if the given protocol specifies file sets for probes, instead of a single probe file. In this default implementation, False is returned, throughout. If you need different behavior, please overload this function in your derived class.

set_base_directory(base_dir)

Resets the base directory where the filelists defining the database are located.

t_enroll_files(protocol, model_id, groups='dev', **kwargs)

Returns the list of T-Norm model enrollment File objects from the given model id of the given protocol for the given group that satisfy your query. For possible keyword arguments, please check the tobjects() function.

t_model_ids(protocol, groups='dev', **kwargs)

Returns the list of model ids used for T-Norm of the given protocol for the given group that satisfy your query. For possible keyword arguments, please check the tmodel_ids() function.

tclient_ids(protocol=None, groups=None)

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

Keyword Parameters:

protocol : str or None

The protocol to consider

groups : str or [str] or None

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)

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

Keyword Parameters:

protocol : str or None

The protocol to consider

groups : str or [str] or None

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

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

test_files(protocol=None, groups='dev', **kwargs)

Returns the list of all test File objects of the given groups that satisfy your query. Test objects are all File objects that serve either for enrollment or probing. For possible keyword arguments, please check the objects() function.

tmodel_ids(protocol=None, groups=None)

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

Keyword Parameters:

protocol : str or None

The protocol to consider

groups : str or [str] or None

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)

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

Keyword Parameters:

protocol : str or None

The protocol to consider

model_ids : str or [str] or None

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 : str or [str] or None

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

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

training_files(protocol=None, **kwargs)

Returns the list of all training (world) File objects that satisfy your query. For possible keyword arguments, please check the objects() function.

uniquify(file_list)

Sorts the given list of File objects and removes duplicates from it.

Keyword parameters:

file_list : [File]

A list of File objects to be handled. Also other objects can be handled, as long as they are sortable.

Returns

A sorted copy of the given file_list with the duplicates removed.

z_probe_files(protocol, groups='dev', **kwargs)

Returns the list of Z-Norm probe File objects to probe the model with the given model id of the given protocol for the given group that satisfy your query. For possible keyword arguments, please check the zobjects() function.

zclient_ids(protocol=None, groups=None)

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

Keyword Parameters:

protocol : str or None

The protocol to consider

groups : str or [str] or None

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)

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

Keyword Parameters:

protocol : str or None

The protocol to consider

groups : str or [str] or None

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)

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

Keyword Parameters:

protocol : str or None

The protocol to consider

groups : str or [str] or None

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

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

class bob.db.verification.filelist.File(file_name, client_id, model_id=None, claimed_id=None)

Bases: bob.db.verification.utils.file.File

Files of this database are composed from the client id, a file id, (a model id) and a claimed (client) id.

Both the bob.db.verification.utils.File.id and the bob.db.verification.utils.File.path are set to the given file_name parameter. 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.

make_path(directory=None, extension=None)

Wraps the current path so that a complete path is formed

Keyword parameters:

directory : str or None

An optional directory name that will be prefixed to the returned result.

extension : str or None

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)

Saves the input data at the specified location and using the given extension.

Keyword parameters:

data : various types

The data blob to be saved (normally a numpy.ndarray).

directory : str or None

If not empty or None, this directory is prefixed to the final file destination

extension : str or None

The extension of the filename. This extension will control the type of output and the codec for saving the input blob.

create_directories : bool

Should the directory structure be created (if necessary) before writing the data?