Python API

This is the Bob database entry for the Face Recognition Grand Challange (FRGC) database in version 2.0.

bob.db.frgc.get_config()

Returns a string containing the configuration information.

class bob.db.frgc.Database(original_directory='/idiap/resource/database/frgc/FRGC-2.0-dist', original_extension='.jpg')

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

The Database class reads the original XML lists and provides access using the common bob.db API.

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)

Returns the annotations for the given file as a dictionary {‘reye’:(y,x), ‘leye’:(y,x), ‘mouth’:(y,x), ‘nose’:(y,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(groups=None, protocol=None, purposes=None, mask_type='maskIII')

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

Keyword Parameters:

groups

One or several groups to which the models belong (‘world’, ‘dev’).

protocol

One or several of the FRGC protocols (‘2.0.1’, ‘2.0.2, ‘2.0.4’), required only if one of the groups is ‘dev’.

purposes

One or several groups for which files should be retrieved (‘enroll’, ‘probe’). Only used when the group is ‘dev’· For some protocol/mask_type pairs, not all clients are used for enrollment / for probe.

mask_type

One of the mask types (‘maskI’, ‘maskII’, ‘maskIII’).

Returns: A list containing all the client id’s 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_client_id_from_file_id(file_id, **kwargs)

Returns the client_id (real client id) attached to the given file_id

Keyword Parameters:

file_id

The file_id to consider

Returns: The client_id attached to the given file_id

get_client_id_from_model_id(model_id, **kwargs)

Returns the client_id attached to the given model_id.

Keyword Parameters:

model_id

The model_id to consider

Warning

The given model_id must have been the result of a previous call to model_ids() of the same database object, otherwise it will not be known or might be corrupted.

Returns: The client_id attached to the given model_id

groups(protocol=None)

Returns a list of groups for the given protocol

Keyword Parameters:

protocol

One or several of the FRGC protocols (‘2.0.1’, ‘2.0.2, ‘2.0.4’),

Returns: a list of groups

model_ids(groups=None, protocol=None, mask_type='maskIII')

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

The models are dependent on the protocol and the mask. Only those FRGC “target” files are returned that are required by the given mask!

Warning

Clients, models, and files are not identical for the FRGC database! Model ids are neither client nor file id’s, so please do not mix that up!

Keyword Parameters:

groups

One or several groups to which the models belong (‘world’, ‘dev’).

protocol

One or several of the FRGC protocols (‘2.0.1’, ‘2.0.2, ‘2.0.4’), required only if one of the groups is ‘dev’.

mask_type

One of the mask types (‘maskI’, ‘maskII’, ‘maskIII’).

Returns: A list containing all the model id’s belonging to the given group.

object_sets(groups=None, protocol='2.0.2', purposes=None, model_ids=None, mask_type='maskIII')

Using the specified restrictions, this function returns a list of FileSet objects.

Keyword Parameters:

groups

Here, only the ‘dev’ group is valid.

protocol

Here, only the FRGC protocol ‘2.0.2’ is valid. Only used, if ‘dev’ is amongst the groups.

purposes

One or several groups for which files should be retrieved (‘enroll’, ‘probe’). In FRGC terms, ‘enroll’ is “Target”, while ‘probe’ is “Target” (protocols ‘2.0.1’ and ‘2.0.2’) or “Query” (protocol ‘2.0.4’)

model_ids

If given (as a list of model id’s or a single one), only the files belonging to the specified model id is returned.

mask_type

One of the mask types (‘maskI’, ‘maskII’, ‘maskIII’).

objects(groups=None, protocol=None, purposes=None, model_ids=None, mask_type='maskIII')

Using the specified restrictions, this function returns a list of File objects.

Keyword Parameters:

groups

One or several groups to which the models belong (‘world’, ‘dev’). ‘world’ files are “Training”, whereas ‘dev’ files are “Target” and/or “Query”.

protocol

One or more of the FRGC protocols (‘2.0.1’, ‘2.0.2’, ‘2.0.4’). Only used, if ‘dev’ is amongst the groups. If not specified, all FRGC protocols will be taken into account.

purposes

One or several groups for which files should be retrieved (‘enroll’, ‘probe’). Only used when the group is ‘dev’· In FRGC terms, ‘enroll’ is “Target”, while ‘probe’ is “Target” (protocols ‘2.0.1’ and ‘2.0.2’) or “Query” (protocol ‘2.0.4’)

model_ids

If given (as a list of model id’s or a single one), only the files belonging to the specified model id is returned.

Warning

When querying objects of group ‘world’, model ids are expected to be client ids (as returned by ‘client_ids()’), whereas for group ‘dev’ model ids are real model ids (as returned by ‘model_ids()’)

mask_type

One of the mask types (‘maskI’, ‘maskII’, ‘maskIII’).

original_file_name(file, check_existence=True)

This function returns the original file name for the given File object.

Keyword parameters:

file : File or a derivative

The File objects for which the file name should be retrieved

check_existence : bool

Check if the original file exists?

Return value : str

The original file name for the given File object

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)

Returns True for every protocol for which file sets (instead of single files) are used for enrollment and probing. Currently, this is only the ‘2.0.2’, protocol.

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.

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.

class bob.db.frgc.File(signature, presentation, path)

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

This class is just the File object that is returned by the objects function. It will be created on need and is not stored anywhere.

make_path(directory=None, extension=None)

Wraps the current path so that a complete path is formed. If directory and extension ‘.jpg’ are specified, extensions are automatically replaced by ‘.JPG’ if necessary.

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)

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?

class bob.db.frgc.FileSet(frgc_file)

This class is just the FileSet object that is returned by the object_sets function. It will be created on need and is not stored anywhere.

class bob.db.frgc.Interface

Bases: bob.db.base.driver.Interface

add_commands(parser)

files()

Returns the list of files required for this interface to work, which is empty.

frgc_database_directory()

Returnes the FRGC database base directory, where the original FRGC file lists (XML) are stored. You might want to adapt this directory to your needs.

name()

setup_parser(parser, short_description, long_description)

Sets up the base parser for this database.

Keyword arguments:

short_description

A short description (one-liner) for this database

long_description

A more involved explanation of this database

Returns a subparser, ready to be added commands on

type()

Defines the type of the database, which is not SQL3, but text based

version()