This package contains an interface for the evaluation protocol of the `YouTube Faces`_ database.
This package does not contain the original `YouTube Faces`_ data files, which need to be obtained through the link above.
Installation
------------
To install this package -- alone or together with other `Packages of Bob <https://github.com/idiap/bob/wiki/Packages>`_ -- please read the `Installation Instructions <https://github.com/idiap/bob/wiki/Installation>`_.
For Bob_ to be able to work properly, some dependent packages are required to be installed.
Please make sure that you have read the `Dependencies <https://github.com/idiap/bob/wiki/Dependencies>`_ for your operating system.
Documentation
-------------
For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/bob.db.youtube/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.db.youtube/master/index.html>`_ of the documentation.
For a list of tutorials on this or the other packages ob Bob_, or information on submitting issues, asking questions and starting discussions, please visit its website.
This package contains the access API and descriptions for the `YouTube Faces Database <http://www.cs.tau.ac.il/~wolf/ytfaces/>`_.
The actual raw data for the database should be downloaded from the original URL.
This package only contains the `Bob <http://www.idiap.ch/software/bob/>`_ accessor methods to use the DB directly from python, with our certified protocols.
You would normally not install this package unless you are maintaining it.
What you would do instead is to tie it in at the package you need to **use** it.
There are a few ways to achieve this:
1. You can add this package as a requirement at the ``setup.py`` for your own `satellite package <https://github.com/idiap/bob/wiki/Virtual-Work-Environments-with-Buildout>`_ or to your Buildout ``.cfg`` file, if you prefer it that way.
With this method, this package gets automatically downloaded and installed on your working environment, or
2. You can manually download and install this package using commands like ``easy_install`` or ``pip``.
The package is available in two different distribution formats:
1. You can download it from `PyPI <http://pypi.python.org/pypi>`_, or
2. You can download it in its source form from `its git repository <https://github.com/bioidiap/bob.db.youtube>`_.
When you download the version at the git repository, you will need to run a command to recreate the backend SQLite file required for its operation.
You can mix and match points 1/2 and a/b above based on your requirements.
Here are some examples:
Modify your setup.py and download from PyPI
===========================================
That is the easiest.
Edit your ``setup.py`` in your satellite package and add the following entry in the ``install_requires`` section (note: ``...`` means `whatever extra stuff you may have in-between`, don't put that on your script)::
install_requires=[
...
"bob.db.youtube",
],
Proceed normally with your ``boostrap/buildout`` steps and you should be all set.
That means you can now import the ``bob.db.youtube`` namespace into your scripts.
Modify your buildout.cfg and download from git
==============================================
You will need to add a dependence to `mr.developer <http://pypi.python.org/pypi/mr.developer/>`_ to be able to install from our git repositories.
Your ``buildout.cfg`` file should contain the following lines::
"""Returns the annotations for the given file id as a dictionary of dictionaries, e.g. {'1.56.jpg' : {'topleft':(y,x), 'bottomright':(y,x)}, '1.57.jpg' : {'topleft':(y,x), 'bottomright':(y,x)}, ...}.
Here, the key of the dictionary is the full image file name of the original image.
Keyword parameters:
directory_id
The id of the directory for which you want to retrieve the annotations
directory
The :py:class:`Directory` object for which you want to retrieve the annotations
image_names
If given, only the annotations for the given image names (without path, but including filaname extension) are extracted and returned
...
...
@@ -526,10 +526,7 @@ class Database(bob.db.verification.utils.SQLiteDatabase):
ifself.original_directoryisNone:
raiseValueError("Please specify the 'original_directory' in the constructor of this class to get the annotations.")
This database interface implements the default evaluation protocols as they are given on the `YouTube Faces Database web page <http://www.cs.tau.ac.il/~wolf/ytfaces>`_.
It implements the :py:mod:`bob.db.verifcation.utils` interface, so that it can be used like any other of our databases.
This package contains the access API and descriptions for the `YouTube Faces`_ database.
It only contains the Bob_ accessor methods to use the DB directly from python, with our certified protocols.
The actual raw data for the `YouTube Faces`_ database should be downloaded from the original URL (though we were not able to contact the corresponding Professor).
.. note::
This database interface does not include the original data.
To be able to run experiments on the YouTube Faces database, you need to get a copy of the original data from the above mentioned web page.
The Database Interface
----------------------
The :py:class:`bob.db.youtube.Database` complies with the standard biometric verification database as described in :ref:`commons`, implementing the interface :py:class:`bob.db.verification.utils.SQLiteDatabase`.
The Protocols
...
...
@@ -43,7 +46,7 @@ For example, to get the list of supported protocols, you can query the list of s
These protocol names define the 10 different splits of the YouTube Faces protocol, for which experiments can be run.
These protocol names define the 10 different splits of the `YouTube Faces`_ protocol, for which experiments can be run.
Some of the remaining query functions require a protocol to be selected.
For each protocol, the splits of the database are distributed into three different groups: ``('world', 'dev', 'eval')``.
...
...
@@ -61,13 +64,12 @@ For the final evaluation it is required that 10 different experiments are execut
Finally, the classification accuracy is reported as an average of the 10 classification results.
The Directory Objects
---------------------
The most important method of the interface is the :py:func:`bob.db.youtube.Database.objects` function.
You can use this function to query the `information` for the protocols.
For the YouTube database, the `information` consists of a list of :py:class:`bob.db.youtube.models.Directory`.
You can use this function to query the *information* for the protocols.
For the YouTube database, the information consists of a list of :py:class:`bob.db.youtube.models.Directory`.
Each ``Directory`` contains information about a video, such as the identity of the client, the shot id and the (relative) path of the directory in the database:
.. .. doctest::
...
...
@@ -83,7 +85,7 @@ Each ``Directory`` contains information about a video, such as the identity of t
1
>>> d.shot_id
0
>>> d.path
>>> d.path #doctest:+SKIP
u'AJ_Cook/0'
These ``Directory`` objects can be used to get the path for the image data.
...
...
@@ -97,8 +99,8 @@ Since the videos are stored as a list of frames, the ``Directory`` interface wil
[...]/AJ_Cook/0/0.123.jpg
.. warning::
Please note that -- in opposition to other bob.db database interfaces -- the ``original_file_name`` function returns a **list** of file names.
Likewise, ``original_file_names`` returns a list of lists of file names.
Please note that -- in opposition to most other bob.db database interfaces -- the :py:meth:`bob.db.youtube.Database.original_file_name` function returns a **list** of file names.
Likewise, :py:meth:`bob.db.youtube.Database.original_file_names` returns a list of lists of file names.
Finally, bounding boxes are annotated in the images.
...
...
@@ -108,23 +110,26 @@ In the example below, the annotations for the first 20 images are read and retur
.. code-block:: python
>>> file_name_stems = [os.path.basename(f) for f in file_names[:20]]
The annotations for one image can, for example, be used to cut out the face region from the image:
The annotations for one image can, for example, be used to cut out the face region from the image, using default functionality from other Bob_ packages:
