Commit fb28b9f4 authored by Yannick DAYER's avatar Yannick DAYER

Merge branch 'new-doc' into 'master'

Updating to the documentation

Closes #39

See merge request !114
parents af2ae899 030e7ab7
Pipeline #48044 passed with stages
in 9 minutes and 12 seconds
......@@ -10,6 +10,7 @@ parts
src
develop-eggs
sphinx
build
dist
record.txt
results
......
......@@ -37,14 +37,17 @@ MIFS Database
.. autoclass:: bob.pad.face.database.mifs.MIFSPadDatabase
Transformers
------------
Pre-processors
------------------------------
==============
.. automodule:: bob.pad.face.preprocessor
Feature Extractors
------------------------------
==================
.. automodule:: bob.pad.face.extractor
......
......@@ -7,40 +7,40 @@
Executing Baseline Algorithms
===============================
This section explains how to execute face presentation attack detection (PAD) algorithms implemented
in ``bob.pad.face``.
This section explains how to execute face presentation attack detection (PAD)
algorithms implemented in ``bob.pad.face``.
Running Baseline Experiments
----------------------------
To run the baseline PAD experiments, the ``bob pad vanilla-pad`` script is used.
To see the description of the script you can type in the console:
To run the baseline PAD experiments, the ``bob pad vanilla-pad`` command is used.
To see the description of the command, you can type in the console:
.. code-block:: sh
$ bob pad vanilla-pad --help
This script is explained in more detail in :ref:`bob.pad.base.experiments`.
This command is explained in more detail in :ref:`bob.pad.base <bob.pad.base.vanilla_pad_features>`.
Usually it is a good idea to have at least verbose level 2 (i.e., calling
Usually, it is a good idea to have at least verbose level 2 (i.e., calling
``bob pad vanilla-pad --verbose --verbose``, or the short version
``bob pad vanilla-pad -vv``).
.. note:: **Running in Parallel**
To run the experiments in parallel, you can define a dask client
(multi-processing) configurations as explained in
:ref:`running_in_parallel`.
To run the experiments in parallel, you can use an existing or (define a new)
SGE grid or local host multiprocessing configuration. To run the experiment
in the Idiap SGE grid, you can simply add the ``--dask-client sge`` command
line option. To run experiments in parallel on the local machine, add the
``--dask-client local-parallel`` option.
In short, to run in the Idiap SGE grid, you can simply add the ``--grid``
command line option, with grid configuration parameters. To run experiments in parallel on
the local machine, simply add a ``--parallel <N>`` option, where ``<N>``
specifies the number of parallel jobs you want to execute.
See :ref:`this <bob.bio.base.vanilla_biometrics_advanced_features>` for more
details on dask configurations.
Database setups and baselines are encoded using
``bob.bio.base.configuration-files``, all stored inside the package root, in
``configuration-files``, all stored inside the package structure, in
the directory ``bob/pad/face/config``. Documentation for each resource
is available on the section :ref:`bob.pad.face.resources`.
......@@ -48,31 +48,27 @@ is available on the section :ref:`bob.pad.face.resources`.
You **cannot** run experiments just by executing the command line
instructions described in this guide. You **need first** to procure yourself
the raw data files that correspond to *each* database used here in order to
correctly run experiments with those data. Biometric data is considered
private date and, under EU regulations, cannot be distributed without a
consent or license. You may consult our
:ref:`bob.pad.face.resources.databases` resources section for checking
currently supported databases and accessing download links for the raw data
files.
the raw data files that correspond to *each* database used here to correctly
run experiments with those data. Biometric data is considered private and,
under EU regulations, cannot be distributed without a consent or license.
You may consult our :ref:`bob.pad.face.resources.databases` resources
section for checking currently supported databases and accessing download
links for the raw data files.
Once the raw data files have been downloaded, particular attention should be
given to the directory locations of those. Unpack the databases carefully
and annotate the root directory where they have been unpacked.
Once the raw data files have been downloaded, unpack the databases carefully
and take a note of the root directory where they have been unpacked.
Then, carefully read the *Databases* section of
:ref:`bob.pad.base.installation` on how to correctly setup the
``~/.bob_bio_databases.txt`` file.
Use the following commands to specify the correct parameters of your dataset
(see :ref:`bob.pad.face.resources.databases`):
Use the following keywords on the left side of the assignment (see
:ref:`bob.pad.face.resources.databases`):
.. code-block:: sh
.. code-block:: text
$ bob config set bob.db.replaymobile.directory /path/to/replayattack-database/
$ bob config set bob.db.replaymobile.extension .mov
[YOUR_REPLAY_ATTACK_DIRECTORY] = /complete/path/to/replayattack-database/
Notice it is rather important to use the strings as described above,
otherwise ``bob.pad.base`` will not be able to correctly load your images.
Notice it is rather important to correctly configure the database as
described above, otherwise ``bob.pad.base`` will not be able to correctly
load your data.
Once this step is done, you can proceed with the instructions below.
......@@ -84,31 +80,39 @@ is available on the section :ref:`bob.pad.face.resources`.
Baselines on REPLAY-ATTACK database
--------------------------------------
This section summarizes the results of baseline face PAD experiments on the REPLAY-ATTACK (`replayattack`_) database.
The description of the database-related settings, which are used to run face PAD baselines on the Replay-Attack is given here :ref:`bob.pad.face.resources.databases.replay`. To understand the settings in more details you can check the corresponding configuration file : ``bob/pad/face/config/replay_attack.py``.
This section summarizes the results of baseline face PAD experiments on the
REPLAY-ATTACK (`replayattack`_) database.
The description of the database-related settings, which are used to run face PAD
baselines on the Replay-Attack is given here
:ref:`bob.pad.face.resources.databases.replay`. To understand the settings in
more detail you can check the corresponding configuration file:
``bob/pad/face/config/replay_attack.py``.
LBP features of facial region + SVM classifier
===================================================
Detailed description of this PAD pipe-line is given at :ref:`bob.pad.face.resources.face_pad.lbp_svm_replayattack`.
Detailed description of this PAD pipe-line is given at
:ref:`bob.pad.face.resources.face_pad.lbp_svm_replayattack`.
To run this baseline on the `replayattack`_ database, using the ``grandtest`` protocol, execute the following:
To run this baseline on the `replayattack`_ database, using the ``grandtest``
protocol, execute the following:
.. code-block:: sh
$ bob pad vanilla-pad replay-attack lbp-64 svm-frames
$ bob pad vanilla-pad replay-attack lbp svm-frames -o <PATH_TO_STORE_THE_RESULTS>
.. tip::
If you are in `idiap`_ you can use SGE grid to speed-up the calculations.
Simply add ``--grid idiap`` argument to the above command. For example:
If you are at `idiap`_ you can use the SGE grid to speed-up the calculations.
Simply add the ``--dask-client sge`` (or ``-l sge``) argument to the above
command. For example:
.. code-block:: sh
$ spoof.py replay-attack lbp-svm \
--sub-directory <PATH_TO_STORE_THE_RESULTS> \
--grid idiap
$ bob pad vanilla-pad replay-attack lbp svm-frames \
--output <PATH_TO_STORE_THE_RESULTS> \
--dask-client idiap
To understand the settings of this baseline PAD experiment you can check the
corresponding configuration file: ``bob/pad/face/config/lbp_svm.py``
......@@ -119,15 +123,15 @@ following command:
.. code-block:: sh
bob pad evaluate \
<PATH_TO_STORE_THE_RESULTS>/grandtest/scores/scores-dev \
<PATH_TO_STORE_THE_RESULTS>/grandtest/scores/scores-eval \
<PATH_TO_STORE_THE_RESULTS>/scores-dev \
<PATH_TO_STORE_THE_RESULTS>/scores-eval \
--legends "LBP features of facial region + SVM classifier + REPLAY-ATTACK database" \
-e \
--criterion eer \
-o <PATH_TO_STORE_THE_RESULTS>/ROC.pdf
The EER/HTER errors for `replayattack`_ database are summarized in the Table below:
The error rates for `replayattack`_ database are summarized in the table below:
+-------------------+----------+----------+
| Protocol | EER,\% | HTER,\% |
......@@ -135,7 +139,7 @@ The EER/HTER errors for `replayattack`_ database are summarized in the Table bel
| ``grandtest`` | 15.117 | 15.609 |
+-------------------+----------+----------+
The ROC curves for the particular experiment can be downloaded from here:
The ROC curves for this particular experiment can be downloaded from here:
:download:`ROC curve <img/ROC_lbp_svm_replay_attack.pdf>`
......@@ -145,13 +149,13 @@ The ROC curves for the particular experiment can be downloaded from here:
Image Quality Measures as features of facial region + SVM classifier
========================================================================
Detailed description of this PAD pipe-line is given at :ref:`bob.pad.face.resources.face_pad.qm_svm_replayattack`.
Detailed description of this PAD pipeline is given at :ref:`bob.pad.face.resources.face_pad.qm_svm_replayattack`.
To run this baseline on the `replayattack`_ database, using the ``grandtest`` protocol, execute the following:
.. code-block:: sh
$ spoof.py replay-attack qm-svm \
$ bob pad vanilla-pad replay-attack qm svm-frames \
--sub-directory <PATH_TO_STORE_THE_RESULTS>
.. tip::
......@@ -174,7 +178,7 @@ following command:
--criterion eer \
-o <PATH_TO_STORE_THE_RESULTS>/ROC.pdf
The EER/HTER errors for `replayattack`_ database are summarized in the Table below:
The EER/HTER errors for `replayattack`_ database are summarized in the table below:
+-------------------+----------+----------+
| Protocol | EER,\% | HTER,\% |
......@@ -196,7 +200,7 @@ Baselines on REPLAY-MOBILE database
--------------------------------------
This section summarizes the results of baseline face PAD experiments on the `Replay-Mobile`_ database.
The description of the database-related settings, which are used to run face PAD baselines on the Replay-Mobile is given here :ref:`bob.pad.face.resources.databases.replay_mobile`. To understand the settings in more details you can check the corresponding configuration file : ``bob/pad/face/config/replay_mobile.py``.
The description of the database-related settings, which are used to run face PAD baselines on the Replay-Mobile is given here :ref:`bob.pad.face.resources.databases.replay_mobile`. To understand the settings in more detail you can check the corresponding configuration file : ``bob/pad/face/config/replay_mobile.py``.
LBP features of facial region + SVM classifier
......@@ -209,8 +213,8 @@ To run this baseline on the `Replay-Mobile`_ database, using the ``grandtest`` p
.. code-block:: sh
$ spoof.py replay-mobile lbp-svm \
--sub-directory <PATH_TO_STORE_THE_RESULTS>
$ bob pad vanilla-pad replay-mobile lbp svm_frame \
--output <PATH_TO_STORE_THE_RESULTS>
.. tip::
......@@ -232,7 +236,7 @@ following command:
--criterion eer \
-o <PATH_TO_STORE_THE_RESULTS>/ROC.pdf
The EER/HTER errors for the `Replay-Mobile`_ database are summarized in the Table below:
The EER/HTER errors for the `Replay-Mobile`_ database are summarized in the table below:
+-------------------+----------+----------+
| Protocol | EER,\% | HTER,\% |
......@@ -257,8 +261,8 @@ To run this baseline on the `Replay-Mobile`_ database, using the ``grandtest`` p
.. code-block:: sh
$ spoof.py replay-mobile qm-svm \
--sub-directory <PATH_TO_STORE_THE_RESULTS>
$ bob pad vanilla-pad replay-mobile qm svm-frames \
--output <PATH_TO_STORE_THE_RESULTS>
.. tip::
......@@ -280,7 +284,7 @@ following command:
--criterion eer \
-o <PATH_TO_STORE_THE_RESULTS>/ROC.pdf
The EER/HTER errors for the `Replay-Mobile`_ database are summarized in the Table below:
The EER/HTER errors for the `Replay-Mobile`_ database are summarized in the table below:
+-------------------+----------+----------+
| Protocol | EER,\% | HTER,\% |
......@@ -314,8 +318,8 @@ To run this baseline on the MIFS database, using the ``grandtest`` protocol, exe
.. code-block:: sh
$ spoof.py mifs lbp-svm \
--sub-directory <PATH_TO_STORE_THE_RESULTS>
$ bob pad vanilla-pad mifs lbp svm-frames \
--output <PATH_TO_STORE_THE_RESULTS>
To evaluate the results computing EER, HTER and plotting ROC you can use the
following command:
......@@ -330,7 +334,7 @@ following command:
--criterion eer \
-o <PATH_TO_STORE_THE_RESULTS>/ROC.pdf
The EER/HTER errors for the MIFS database are summarized in the Table below:
The EER/HTER errors for the MIFS database are summarized in the table below:
+-------------------+----------+----------+
| Protocol | EER,\% | HTER,\% |
......@@ -348,8 +352,8 @@ To run this baseline on the MIFS database, using the ``grandtest`` protocol, exe
.. code-block:: sh
$ spoof.py mifs qm-svm \
--sub-directory <PATH_TO_STORE_THE_RESULTS>
$ bob pad vanilla-pad mifs qm svm-frames \
--output <PATH_TO_STORE_THE_RESULTS>
To evaluate the results computing EER, HTER and plotting ROC you can use the
following command:
......@@ -364,7 +368,7 @@ following command:
--criterion eer \
-o <PATH_TO_STORE_THE_RESULTS>/ROC.pdf
The EER/HTER errors for the MIFS database are summarized in the Table below:
The EER/HTER errors for the MIFS database are summarized in the table below:
+-------------------+----------+----------+
| Protocol | EER,\% | HTER,\% |
......
......@@ -6,7 +6,7 @@
Library for Facial Presentation Attack Detection (PAD)
========================================================
The Facial Presentation Attack Detection Library is an open source tool consisting of a
The Facial Presentation Attack Detection Library is an open-source tool consisting of a
series of plugins for bob.pad.base_, our open-source biometric recognition
platform. As a result, it is fully extensible using bob.pad.base_ documented
types and techniques. Please refer to the manual of that package for a thorough
......
......@@ -5,17 +5,17 @@
Setting up Databases
======================
In order to run face PAD algorithms using this package, you'll need to make
sure to download the raw files corresponding to the databases you'd like to
process. The raw files are **not** distributed with Bob_ software as biometric
data is, to most countries, considered sensible data that cannot be obtained
without explicit licensing from a data controller. You must visit the websites
below, sign the license agreements and then download the data before trying out
to run the baselines.
To run face PAD algorithms using this package, you'll need to make sure to
download the raw files corresponding to the databases you'd like to process.
The raw files are **not** distributed with Bob_ software as biometric data is,
to most countries, considered sensible data that cannot be obtained without
explicit licensing from a data controller. You must visit the websites below,
sign the license agreements and then download the data before trying out to run
the baselines.
.. note::
If you're at the Idiap Research Institute in Switzlerand, the datasets in
If you're at the Idiap Research Institute in Switzerland, the datasets in
the baselines mentioned in this guide are already downloaded and
pre-installed on our shared file system. You don't need to re-download
databases.
......
......@@ -12,77 +12,46 @@ in ``bob.pad.face``.
.. warning::
Algorithms introduced in this section might be in the process of publishing. Therefore, it is not
allowed to publish results introduced in this section without permission of the owner of the package.
If you are planning to use the results from this section, please contact the owner of the package first.
Algorithms introduced in this section might be in the process of publishing.
Therefore, it is not allowed to publish results introduced in this section
without the permission of the owner of the package.
If you are planning to use the results from this section, please contact the
owner of the package first.
Please check the ``setup.py`` for contact information.
Running face PAD Experiments
------------------------------
To run the PAD experiments, the ``spoof.py`` script located in ``bin`` directory is used.
To see the description of the script you can type in the console:
To run the PAD experiments, use the ``bob pad`` command.
To see the description of this command you can type in the console:
.. code-block:: sh
$ spoof.py --help
$ bob pad --help
This script is explained in more detail in :ref:`bob.pad.base.experiments`.
This script is explained in more detail in :ref:`bob.pad.base`.
Usually it is a good idea to have at least verbose level 2 (i.e., calling
``spoof.py --verbose --verbose``, or the short version ``spoof.py
-vv``).
Usually, it is a good idea to have at least verbose level 2 (i.e., calling
``bob pad --verbose --verbose``, or the short version ``bob pad -vv``).
.. note:: **Running in Parallel**
To run the experiments in parallel, you can define an SGE grid or local host
(multi-processing) configurations as explained in
:ref:`running_in_parallel`.
To run the experiments in parallel, you can use an existing or (define a new)
SGE grid or local host multiprocessing configuration. To run the experiment
in the Idiap SGE grid, you can simply add the ``--dask-client sge`` command
line option. To run experiments in parallel on the local machine, add the
``--dask-client local-parallel`` option.
In short, to run in the Idiap SGE grid, you can simply add the ``--grid``
command line option, with grid configuration parameters. To run experiments in parallel on
the local machine, simply add a ``--parallel <N>`` option, where ``<N>``
specifies the number of parallel jobs you want to execute.
See :ref:`this <bob.bio.base.vanilla_biometrics_advanced_features>` for more
details on dask configurations.
Database setups and face PAD algorithms are encoded using
``bob.bio.base.configuration-files``, all stored inside the package root, in
the directory ``bob/pad/face/config``. Documentation for each resource
``bob.bio.base.configuration-files``, all stored inside the package structure,
in the directory ``bob/pad/face/config``. Documentation for each resource
is available on the section :ref:`bob.pad.face.resources`.
.. warning::
You **cannot** run experiments just by executing the command line
instructions described in this guide. You **need first** to procure yourself
the raw data files that correspond to *each* database used here in order to
correctly run experiments with those data. Biometric data is considered
private date and, under EU regulations, cannot be distributed without a
consent or license. You may consult our
:ref:`bob.pad.face.resources.databases` resources section for checking
currently supported databases and accessing download links for the raw data
files.
Once the raw data files have been downloaded, particular attention should be
given to the directory locations of those. Unpack the databases carefully
and annotate the root directory where they have been unpacked.
Then, carefully read the *Databases* section of
:ref:`bob.pad.base.installation` on how to correctly setup the
``~/.bob_bio_databases.txt`` file.
Use the following keywords on the left side of the assignment (see
:ref:`bob.pad.face.resources.databases`):
.. code-block:: text
[YOUR_REPLAY_ATTACK_DIRECTORY] = /complete/path/to/replayattack-database/
Notice it is rather important to use the strings as described above,
otherwise ``bob.pad.base`` will not be able to correctly load your images.
Once this step is done, you can proceed with the instructions below.
.. include:: links.rst
......
......@@ -18,7 +18,8 @@ Databases
------------
These configuration files/resources contain parameters of available databases.
The configuration files contain at least the following arguments of the ``spoof.py`` script:
The configuration files contain at least the following arguments of the
``bob pad vanilla-pad`` command:
* ``database``
* ``protocol``
......@@ -57,13 +58,12 @@ MIFS Database
Available face PAD systems
------------------------------
These configuration files/resources contain parameters of available face PAD systems/algorithms.
The configuration files contain at least the following arguments of the ``spoof.py`` script:
These configuration files/resources contain parameters of available face PAD
systems/algorithms.
The configuration files contain at least the following arguments of the
``bob pad vanilla-pad`` command:
* ``sub_directory``
* ``preprocessor``
* ``extractor``
* ``algorithm``
* ``pipeline`` containing zero, one, or more Transformers and one Classifier
.. _bob.pad.face.resources.face_pad.lbp_svm_replayattack:
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment