.. vim: set fileencoding=utf-8 :
.. Tiago de Freitas Pereira <tiago.pereira@idiap.ch>

.. _bob.thesis.tiago:

===============================================================
 Learning How To Recognize Faces In Heterogeneous Environments
===============================================================

The goal of this package is to provide the instructions to reproduce ALL the experiments from the Ph.D thesis "Learning How To Recognize Faces In Heterogeneous Environments
"
This package is an extension of the
`bob.bio.base <https://www.idiap.ch/software/bob/docs/bob/bob.bio.base/stable/index.html>`_ framework.


Installation
============

The installation instructions are based on conda (**LINUX and MACOSX ONLY**).
Please `install conda <https://conda.io/docs/install/quick.html#linux-miniconda-install>`_ before continuing.

With miniconda set, do the following steps::

  $ conda install bob.thesis.tiago #Installation
  $ bob bio htface --help #Checking if everything is alright
      Usage: bob bio htface [OPTIONS] COMMAND [ARGS]...

      Face Ongoing Commands.

    Options:
      -h, -?, --help  Show this message and exit.

    Commands:
      create_block_image   This click command generates as block based...
      evaluate_and_squash  This script runs CMC, DET plots and...
      fft_analysis         This click command does FFT ANALISYS of some...
      filter_ldhf          This click command take as input the scores...
      htface_baseline      Run a biometric recognition baseline.
      htface_train_dsu     Trains a CNN using the domain specific units...
      isv_intuition        This click command plots the ISV intuition...



If you are interested in the Domain Specific Units chapter, you must download all the priors used.
Typing the command below will download and set everything::

  $ bob bio face_ongoing download_models



.. warning::
  Before the magic begins, it's necessary to set a set of paths for the databases.
  Sorry, but there is no other way.
  Please, edit this file according to your own work environment::

  $ vim ~/.bobrc



Follow below how this file looks like::

    {
    "bob.bio.htface.experiment-directory": "[PATH-WHERE-THE-EXPERIMENTS-WILL-BE-EXECUTED]",
    
    "bob.bio.htface.cufs_path": "[CUHK-CUFS-DB-PATH]",
    "bob.bio.htface.arface_path": "[ARFACE-DB-PATH]",
    "bob.bio.htface.xm2vts_path": "[XM2VTS-DB-PATH]",
    "bob.bio.htface.cufs_extension": [".jpg", ".JPG", ".ppm"],
    
    "bob.bio.htface.nivl_path": "[NIVL-DB-PATH]",
    "bob.bio.htface.nivl_extension": ".png",

    "bob.bio.htface.polathermal_path": "[POLATHERMAL-DB-PATH]",
    "bob.bio.htface.polathermal_extension": ".png",

    "bob.bio.htface.casia_nir_vis_path": "[CBSR-NIR-VIS-2-DB-PATH]",
    "bob.bio.htface.casia_nir_vis_extension": [".bmp", ".jpg"],

    "bob.bio.htface.cufsf_path": "[CUHK-CUFSF-PATH]",
    "bob.bio.htface.feret_path": "[FERET-PATH]",
    "bob.bio.htface.cufsf_extension": [".jpg",".tif"],
    
    "bob.bio.htface.fargo_path":"[FARGO-DB-PATH]",
    "bob.bio.htface.fargo_annotations":"[FARGO-ANNOTATIONS-PATH]",

     "bob.bio.htface.ldhf_path": "[LDHF-PATH]",
     "bob.bio.htface.ldhf_extension": ".JPG",

 
    "bob.bio.face_ongoing.idiap_casia_inception_v1_centerloss_gray": "[INCEPTIONV1-GRAY-MODEL-PATH]",
    "bob.bio.face_ongoing.idiap_casia_inception_v1_centerloss_rgb": "[INCEPTIONV1-RGB-MODEL-PATH],
    "bob.bio.face_ongoing.idiap_casia_inception_v2_centerloss_gray": "[INCEPTIONV2-GRAY-MODEL-PATH],
    "bob.bio.face_ongoing.idiap_casia_inception_v2_centerloss_rgb": "[INCEPTIONV2-RGB-MODEL-PATH],
    
    "bob.bio.face_ongoing.msceleb-inception-v1_batchnorm_gray": "[INCEPTIONV1-GRAY-MODEL-PATH]",
    "bob.bio.face_ongoing.msceleb-inception-v1_batchnorm_rgb": "[INCEPTIONV1-RGB-MODEL-PATH],
    "bob.bio.face_ongoing.msceleb-inception-v2_batchnorm_gray": "[INCEPTIONV2-GRAY-MODEL-PATH],
    "bob.bio.face_ongoing.msceleb-inception-v2_batchnorm_rgb": "[INCEPTIONV2-RGB-MODEL-PATH]

    }

.. warning::  
  Sorry, but there is no other way, you have to set all these things
  
  
  
Instructions for developers
---------------------------
  
If you want to **DEVELOP** this package, follow below one possible set of instructions::

  $ git clone https://gitlab.idiap.ch/bob/bob.thesis.tiago
  $ cd bob.thesis.tiago
  $ conda env create -f environment.yml
  $ source activate bob.bio.htface  # activate the environment
  $ buildout

  
   
========
The task
========


The task of Heterogeneous Face Recognition consists in matching face images that are sensed in different domains, such as sketches to photographs (visual spectra images), thermal images to photographs or near-infrared images to photographs.

Follow below possible Heteregenous Face Recognition Scenarious.

.. image:: ./img/hfr_schema.png
 :scale: 100 %


==========
Databases
==========

This subsection describes the databases used in this work.

.. toctree::
   :maxdepth: 2

   databases



==========
Hypotheses
==========

.. toctree::
   :maxdepth: 2

   chapter_3
   chapter_4
   chapter_5


========
See also
========
  
.. toctree::
   :maxdepth: 2

   FAQ


==========
References
==========
.. toctree::
   :maxdepth: 3

   references