.. vim: set fileencoding=utf-8 :
.. @author: Manuel Guenther <Manuel.Guenther@idiap.ch>
.. @date:   Thu Dec  6 12:28:25 CET 2012

==============
 User's Guide
==============


The GBU (Good, Bad and Ugly) database consists of parts of the MBGC-V1 image set.
It defines three protocols, i.e., ``Good``, ``Bad`` and ``Ugly`` for which different model and probe images are used.

Installation
------------
To be able to use this database, please have a look at the NIST webpage: http://www.nist.gov/itl/iad/ig/focs.cfm and download **The Multiple Biometric Grand Challenge (MBGC)-V1 image database**.

Unfortunately, the directory structure in this image database changed.
If you have an older version of it, and the ``bob_dbmanage.py gbu checkfiles --directory <YOUR_PATH_TO_MBGC-V1>`` fails (i.e. reports missing files), you have two possible options:

* Call:

  .. code-block:: sh

    $ bob_dbmanage.py gbu create --recreate --rescan-image-directory <YOUR_PATH_TO_MBGC-V1>

  (you might need root access to recreate the database)

* Copy (or link) the images of the MBGC-V1 database into a directory that has the required directory structure by calling:

  .. code-block:: sh

    $ bob_dbmanage.py gbu copy-image-files --soft-link --original-image-directory <YOUR_PATH_TO_MBGC-V1> --new-image-directory <NEW_IMAGE_PATH_TO_BE_CREATED>

To be sure that the procedure succeeded, please call ``bob_dbmanage.py gbu checkfiles --directory <YOUR_PATH_TO_MBGC-V1>`` or ``bob_dbmanage.py gbu checkfiles --directory <NEW_IMAGE_PATH_TO_BE_CREATED>`` afterwards.
If this fails again, your copy of the MBGC-V1 database is corrupted, and you might consider to get a new copy of it.


The Database Interface
----------------------

The :py:class:`bob.db.gbu.Database` complies with the standard biometric verification database as described in `bob.db.base <bob.db.base>`, implementing the interface :py:class:`bob.db.base.SQLiteDatabase`.


Particularities of this Database Interface
------------------------------------------
This implementation of the GBU database wrapper provides two different types of protocols:

* 'gbu': In the original protocol models are extracted for each file.
  This means that there may be several models for the same client.
* 'multi': The new protocol provides one **or more** files for each model.
  Hence, only one model per client is generated.

There are slight differences between the two protocol types:

1. The amount of models differs, and so the amount of scores does.
2. The ``model_id``\s differ.
   For a ``'multi'`` protocol, ``model_id`` and ``client_id`` are the same, whereas for a ``'gbu'`` protocol, ``model_id`` and ``file_id`` are identical.
3. Only the results generated by the ``'gbu'`` protocol are comparable to results that other groups reported on the GBU database.

.. note::
  To be consistent with results published in literature, the default protocol type is ``'gbu'``.

.. warning::
  Do never mix ``'gbu'`` and ``'multi'`` protocol types.
  When you are lucky, you will get an exception, if not, other weird things might happen without you noticing!


The three protocols ``'Good'``, ``'Bad'`` and ``'Ugly'`` are provided for both protocol types.
Additionally, there are four different training sets (sub-worlds), called ``'x1'``, ``'x2'``, ``'x4'`` and ``'x8'`` with different numbers of training images (the number of training identities is the same for all training sets).

The GBU protocols do only provide a ``'dev'`` set, but no ``'eval'`` set.
The default measurement reported is the ROC curve on the 'dev' set.
When a single number is required, usually the FRR (or the CAR) at FAR=0.1% is reported by other researchers.


.. _bob: https://www.idiap.ch/software/bob