Metadata-Version: 1.1
Name: bob.hobpad2.veins
Version: 1.0.2
Summary: Software package to reproduce experiments of Chapter 18, "An Introduction to Vein Presentation Attacks and Detection" of the "Handbook of Biometric Anti-Spoofing: Presentation Attack Detection 2nd Edition" book
Home-page: https://gitlab.idiap.ch/bob/bob.hobpad2.veins
Author: Andre Anjos
Author-email: andre.anjos@idiap.ch
License: GPLv3
Description: .. vim: set fileencoding=utf-8 :
        .. Wed 14 Mar 14:41:21 2018 CET
        
        .. image:: https://gitlab.idiap.ch/bob/bob.hobpad2.veins/badges/v1.0.2/build.svg
           :target: https://gitlab.idiap.ch/bob/bob.hobpad2.veins/commits/v1.0.2
        .. image:: https://gitlab.idiap.ch/bob/bob.hobpad2.veins/badges/v1.0.2/coverage.svg
           :target: https://gitlab.idiap.ch/bob/bob.hobpad2.veins/commits/v1.0.2
        .. image:: https://img.shields.io/badge/gitlab-project-0000c0.svg
           :target: https://gitlab.idiap.ch/bob/bob.hobpad2.veins
        .. image:: https://img.shields.io/pypi/v/bob.hobpad2.veins.svg
           :target: https://pypi.python.org/pypi/bob.hobpad2.veins
        
        
        ============================================================
         An Introduction to Vein Presentation Attacks and Detection
        ============================================================
        
        This package is part of the signal-processing and machine learning toolbox
        Bob_. It reproduces results presented in Chapter 18 of the "Handbook of
        Biometric Anti- Spoofing: Presentation Attack Detection 2nd Edition".
        
        
        Installation
        ------------
        
        We use conda_ to manage the software stack installation. To install this
        package and all dependencies, first install conda_, and then run the
        following command on your shell::
        
          $ conda create --name hobpad2-veins --override-channels -c https://www.idiap.ch/software/bob/conda -c defaults python=3 bob.hobpad2.veins
          $ conda activate hobpad2-veins
          (hobpad2-veins) $ #type all commands inside this "activated" environment
        
        
        .. note::
        
           At the present time, Bob_ only offers support to Linux and MacOS operating
           systems. Windows installations are **not** supported.
        
        
        This will install all the required software to reproduce this paper.
        
        You now need to procure the raw data to run the experiments. Visit the web page
        for the `VERA FingerVein`_ and click on the "Download" link on that page.
        Follow the instructions to sign the End-User License Agreement (EULA) and then
        you'll be able to access the package with the data. Download and uncompress it.
        Annotate the directory leading to the root of the dataset. In this guide, we'll
        refer to it using a generic path ``/path/to/verafinger``.
        
        Once the data is downloaded and uncompressed, configure Bob_'s access to it by
        editing (or creating) a file called ``${HOME}/.bob_bio_databases.txt`` and set
        the path to the dataset there. Here is an example::
        
           (hobpad2-veins) $ cat ~/.bob_bio_databases.txt
           [YOUR_VERAFINGER_DIRECTORY] = /path/to/verafinger
        
        
        You're now all set. Proceed to the instructions to re-run algorithms and
        analysis routines available in this package.
        
        
        Re-running Vulnerability Analysis
        ---------------------------------
        
        To re-run results for vulnerability analysis, first run the baseline
        experiments based on Maximum Curvature and Miura Matching using the `Vera
        Fingervein`_ "Nom" Protocol::
        
           (hobpad2-veins) $ verify.py mc_bio
           (hobpad2-veins) $ verify.py mc_pa
        
        This should take about 2 hours to complete in a modest computer. If you have
        more cores available, it is adviseable to run the jobs in parallel. Just
        execute it like this instead::
        
           (hobpad2-veins) $ verify.py mc_bio parallel
        
        
        Results are stored in the ``results`` folder, which is created if it doesn't
        already exist. Then, run the analysis script to produce the vulnerability
        analysis merit figures for the algorithm/protocol above::
        
           (hobpad2-veins) $ bob vuln hist results/scores/mc/{Nom,Nom-va}/nonorm/scores-dev
        
        
        The last script should produce a figure like Figure 10 in the book chapter,
        together with error rates you can quote. Repeat the above analysis for other
        protocols like the following, for the "Full" protocol::
        
           (hobpad2-veins) $ verify.py --protocol='Full' mc_bio
           (hobpad2-veins) $ verify.py --protocol='Full-va' mc_pa
        
        There is a total of 4 different `Vera Fingervein`_ protocols supported: "Full",
        "Nom" (the default), "Fifty" and "B". There is a total of 3 different baseline
        algorithms that vary only on the feature extraction (binarisation) technique
        used. All baselines use pre-annotated regions of interest pre-processing and
        Miura Matching (correlation) for scoring: Maximum Curvature (configuration
        ``mc_bio``), Repeated Line Tracking (configuration ``rlt_bio``) and Wide-Line
        Detector (configuration ``wld_bio``). You may refer to the documentation of
        bob.bio.vein_ for details on the implementation. You can list available
        baselines using the following command::
        
           (hobpad2-veins) $ resources.py --types=config --packages=bob.hobpad2.veins
        
        
        Once you ran all baselines, you should be able to reproduce Table 2 in the
        book chapter.
        
        For your reference, these are the EER values at the operation point:
        
        +-----------------------+----------+-----------+-----------+
        | **Protocol/Baseline** |  **mc**  |  **rlt**  |  **wld**  |
        +-----------------------+----------+-----------+-----------+
        | *Nom*                 |    2%    |    19%    |     7%    |
        +-----------------------+----------+-----------+-----------+
        | *Full*                |    1%    |    11%    |     4%    |
        +-----------------------+----------+-----------+-----------+
        | *B*                   |    1%    |    17%    |     3%    |
        +-----------------------+----------+-----------+-----------+
        | *Fifty*               |    1%    |    17%    |     3%    |
        +-----------------------+----------+-----------+-----------+
        
        This is Impostor Attack Presentation Match Rate (IAPMR) for thresholds on the
        EER point for the baseline systems above:
        
        +-----------------------+----------+-----------+-----------+
        | **Protocol/Baseline** |  **mc**  |  **rlt**  |  **wld**  |
        +-----------------------+----------+-----------+-----------+
        | *Nom*                 |    83%   |    38%    |    76%    |
        +-----------------------+----------+-----------+-----------+
        | *Full*                |    89%   |    34%    |    80%    |
        +-----------------------+----------+-----------+-----------+
        | *B*                   |    86%   |    32%    |    75%    |
        +-----------------------+----------+-----------+-----------+
        | *Fifty*               |    77%   |    35%    |    70%    |
        +-----------------------+----------+-----------+-----------+
        
        
        Re-running Competition_ Baselines
        ---------------------------------
        
        You can re-run the baseline algorithm for presentation-attack detection
        provided by Idiap during "The 1st Competition_ on Counter Measures to Finger
        Vein Spoofing Attacks", presented on ICB 2018. To do so, run::
        
           (hobpad2-veins) $ #runs the FFT-based algorithm for the "full" PAD protocol
           (hobpad2-veins) $ spoof.py -vv verafinger-pad fourier
           (hobpad2-veins) $ # the same as above for the "cropped" protocol
           (hobpad2-veins) $ spoof.py -vv --protocol=cropped verafinger-pad fourier
        
        
        The above commands should get your scores in the directory ``results``. You may
        then run the analysis, which will lead you to results reported in Figure 11 in
        the book chapter (see the last two plots of each PDF)::
        
           (hobpad2-veins) $ bob bio hist --output=idiap-full.pdf --eval results/scores/fourier/full/nonorm/scores-{dev,eval}
           (hobpad2-veins) # The next line dumps a table with the calculated metrics
           (hobpad2-veins) $ bob bio metrics --eval results/scores/fourier/full/nonorm/scores-{dev,eval}
        
        
        Some of the results reported rely on scores provided by other teams that
        participated on the competition_. Those scores are loaded from the folder
        ``scores`` available within this package. You can find the directory containing
        the scores with the following command::
        
           (hobpad2-veins) $ bob_hobpad2_veins_scores.py
           Scores are located at /path/to/bob.hobpad2.veins/bob/hobpad2/veins/scores
           (hobpad2-veins) $ ls -l /path/to/bob.hobpad2.veins/bob/hobpad2/veins/scores
           total 0
           drwxr-xr-x  6 foobar users 204 Apr 16 15:02 pad-competition/
           drwxr-xr-x 10 foobar users 340 Apr 16 15:02 mc/
           drwxr-xr-x 10 foobar users 340 Apr 16 15:02 rlt/
           drwxr-xr-x 10 foobar users 340 Apr 16 15:02 wld/
        
        
        Results from Table 3 in the book chapter can be reproduced with the following
        script::
        
           mkdir competition-results
           SCORES_DIR=/path/to/bob.hobpad2.veins/bob/hobpad2/veins/scores
        
           for participant in idiap guc blab grip-priamus; do
             for protocol in full cropped; do
               plotfname="competition-results/${participant}-${protocol}.pdf"
               logfname="competition-results/${participant}-${protocol}.txt"
               echo "PAD of '${participant}' on protocol '${protocol}' -> ${logfname}"
               bob bio hist --output=${plotfname} --eval ${SCORES_DIR}/pad-competition/${participant}/${protocol}/scores-{dev,eval}
               bob bio metrics --output=${plotfname} --eval ${SCORES_DIR}/pad-competition/${participant}/${protocol}/scores-{dev,eval}
             done
           done
        
        
        By looking at all log files generated from the metrics commands, you should be
        able to reconstruct the data on Table 1 relative to results published
        alongside the 1st. Competition on Counter Measures to Fingervein Spoofing.
        Results shown here correspond to the HTER on the test set for a threshold
        chosen *a priori* on the development set EER (in parenthesis):
        
        +--------------+-------------+-------------+-------------+------------------+
        | **Protocol** |  **Idiap**  |   **GUC**   |  **B-Lab**  | **Grip-Priamus** |
        +--------------+-------------+-------------+-------------+------------------+
        | *full*       |   0% ( 0%)  |    4% (0%)  |   0% (0%)   |    0% (0%)       |
        +--------------+-------------+-------------+-------------+------------------+
        | *cropped*    |  19% (24%)  |    3% (0%)  |   1% (0%)   |    0% (0%)       |
        +--------------+-------------+-------------+-------------+------------------+
        
        
        Scores
        ------
        
        To improve reproducibility aspects, we include all pre-generated scores after
        running the systems described above, in the ``scores`` folder within this
        package. The contents are the same as ``results/scores`` if you run all
        variants described above. You may reproduce all analysis described in the book
        chapter only by using them, instead of running all baseline scripts. To do so,
        just replace the path on the relevant analysis command-line instructions above
        from ``results/scores`` to ``/path/to/scores``, which may obtained with the
        script ``bob_hobpad2_veins_scores.py`` as described above.
        
        The scores sub-directory also contains de-anonymized scores provided by
        competitors of our paper "The 1st Competition_ on Counter Measures to Finger
        Vein Spoofing Attacks", presented on ICB 2018. You'll need these to reproduce
        some of the figures shown in the book chapter. Notice we have not received
        source code contributions for competitors and therefore cannot reproduce or
        provide code to reproduce such results.
        
        
        Extending Functionality
        -----------------------
        
        To extend functionality provided by this package, you'll need to develop new
        components for either bob.bio.vein_ (our biometric vein recognition framework)
        or bob.pad.vein_ (our presentation-attack detection framework for vein
        recognition systems). Start by reading their user guides.
        
        
        Contact
        -------
        
        For questions or reporting issues to this software package, contact our
        development `mailing list`_.
        
        
        .. Place your references here:
        .. _conda: https://conda.io/
        .. _bob: https://www.idiap.ch/software/bob
        .. _installation: https://www.idiap.ch/software/bob/install
        .. _bob.bio.vein: https://pypi.python.org/pypi/bob.bio.vein
        .. _bob.pad.vein: https://pypi.python.org/pypi/bob.pad.vein
        .. _vera fingervein: https://www.idiap.ch/software/bob/docs/bob/bob.db.verafinger/v1.0.2/index.html
        .. _vera fingervein dataset: https://www.idiap.ch/dataset/vera-fingervein
        .. _competition: http://publications.idiap.ch/index.php/publications/show/3095
        .. _mailing list: https://www.idiap.ch/software/bob/discuss
        
Keywords: bob
Platform: UNKNOWN
Classifier: Framework :: Bob
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
