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
: 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.bio_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.base.annotations.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
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
: bob.db.bio_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_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
: 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)[source]

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)[source]

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.

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
: 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)[source]

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)[source]
groups(protocol=None)[source]

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)[source]

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)[source]

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)[source]

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)[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
: bob.db.bio_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.

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
: 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)[source]

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.

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
: 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)[source]

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.

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
: 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)[source]

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)[source]

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.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
: various type
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
: str
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
: various type
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.