{ "info": { "author": "Manuel Guenther", "author_email": "manuel.guenther@idiap.ch", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Framework :: Bob", "Intended Audience :: Developers", "License :: OSI Approved :: GNU General Public License v3 (GPLv3)", "Natural Language :: English", "Programming Language :: Python", "Topic :: Scientific/Engineering :: Artificial Intelligence" ], "description": ".. vim: set fileencoding=utf-8 :\n.. Manuel Guenther \n.. Tue 24 Mar 14:55:33 CET 2015\n\n===============================================================\n Impact of Eye Detection Error on Face Recognition Performance\n===============================================================\n\nThis package provides the source code to run the experiments published in the paper `Impact of Eye Detection Error on Face Recognition Performance `_.\nIt relies on the FaceRecLib_ to execute the face recognition experiments, which in turn uses the face recognition algorithms and the database interface of Bob_.\n\n.. note::\n Currently, this package only works in Unix-like environments and under MacOS.\n Due to limitations of the Bob_ library, MS Windows operating systems are not supported.\n We are working on a port of Bob_ for MS Windows, but it might take a while.\n In the meanwhile you could use our VirtualBox_ images that can be downloaded `here `__.\n\nWhen you use this source code in a scientific publication, we would be happy if you would cite::\n\n @article{Dutta2015,\n author = \"Abhishek Dutta and Manuel G\\\"unther and Laurent El Shafey and S\\'ebastien Marcel\",\n title = \"Impact of Eye Detection Error on Face Recognition Performance\",\n year = 2015\n journal = {IET Biometrics},\n issn = {2047-4938},\n url = {http://digital-library.theiet.org/content/journals/10.1049/iet-bmt.2014.0037},\n pdf = {http://publications.idiap.ch/downloads/papers/2015/Dutta_IETBIOMETRICS_2014.pdf}\n }\n\n\n\nInstallation\n============\nThis package uses several Bob_ libraries, which will be automatically installed locally using the command lines as listed below.\nHowever, in order for the Bob_ packages to compile, certain `Dependencies `_ need to be installed.\n\nThis package\n------------\nThe installation of this package relies on the `BuildOut `_ system.\nBy default, the command line sequence::\n\n $ ./python bootstrap-buildout.py\n $ ./bin/buildout\n\nshould download and install all required packages of Bob_ in the versions that we used to produce the results.\nOther versions of the packages might generate sightly different results.\nTo use the latest versions of all Bob_ packages, please remove the strict version numbers that are given in the **buildout.cfg** file in the main directory of this package.\n\nImage Database\n--------------\nThe experiments are run on an external image database.\nWe do not provide the images from the database themselves.\nHence, please contact the database owners to obtain a copy of the images.\nThe Multi-PIE database used in our experiments can be downloaded `here `__.\n\n.. note::\n Unfortunately, the Multi-PIE database is not free of charge.\n If you do not have a copy of the database yet, and you are not willing to pay for it, you cannot reproduce the results of the paper directly.\n Nevertheless, you can use other databases, some of which are free of charge.\n A complete list of supported databases and their according evaluation protocols can be found in the FaceRecLib_ documentation.\n\n\nImportant!\n''''''''''\nAfter downloading the databases, you will need to tell our software, where it can find them by changing the **configuration file**.\nIn particular, please update the ``MULTIPIE_IMAGE_DIRECTORY`` in **xfacereclib/paper/IET2015/configuration/database.py**.\n\n\nUnpacking the Annotations\n-------------------------\nAfter the database is set up correctly, you'll need to unpack the eye annotations that are used in the experiments.\nPlease run the script::\n\n $ ./bin/unpack_annotations\n\nto extract the annotations in the desired directory structure.\nIf you want, you can specify another directory to unpack the annotations (see ``./bin/unpack_annotations.py --help``), but all other functions and configurations will have their defaults set according to the default directory.\n\n\nTesting your Installation\n-------------------------\nAfter you have set up the database, you should be able to run our test suite::\n\n $ ./bin/nosetests\n\nPlease make sure that all tests pass.\n\nTODO::\n\n Implement tests.\n\nGetting help\n------------\nIn case anything goes wrong, please feel free to open a new ticket in our GitHub_ page, start a new discussion in our `Mailing List `_ or send an email to manuel.guenther@idiap.ch.\n\n\nRecreating the Results of the Paper_\n====================================\nAfter successfully setting up the database, you are now able to run the face recognition experiments as explained in the Paper_.\nParticularly, you will be able to reproduce Figure 4, Figure 7 and Figure 13.\nBe aware that we were running more than 1000 individual face recognition experiments, each of which used a slightly different experiment configuration.\n\n\nThe Experiment Configuration\n----------------------------\nThe face recognition experiment are run using the FaceRecLib_.\nIn total, we are testing five different face recognition algorithms, each of which uses the *default configuration* from the FaceRecLib_:\n\n* ``eigenfaces``: a PCA is trained on pixel gray values, and the projected features are compared with Euclidean distance.\n* ``fisherfaces``: a combined PCA + LDA matrix is trained on pixel gray values, and the projected features are compared with Euclidean distance.\n* ``gabor-jet``: Gabor jets are extracted at grid locations in the image and compared with a Gabor-phase-based similarity function.\n* ``lgbphs``: extended local Gabor binary pattern histogram sequences are extracted from image blocks, and the histograms are compared with histogram intersection.\n* ``isv``: DCT features are extracted from image blocks and modeled with a Gaussian mixture model and an additional inter-session variability model, and the score is computed as a likelihood ratio.\n\nAs input, all these algorithms expect images, where the face is extracted and aligned, so that the eye centers are always placed on the same location in the image.\nFor this alignment procedure, labeled eye locations must be available.\nThe main focus of this paper is **not** on the face recognition algorithms themselves, but on how they perform in case that the eye locations are slightly misplaced, as it might happen in both manual and automatic annotations.\n\nRunning the Experiments\n-----------------------\nFor convenience, we have generated a wrapper script that allows to run a set of face recognition experiments in sequence -- or even in parallel, see below.\nThis wrapper script *abuses* one functionality of the FaceRecLib_, namely the *parameter testing*, which is an easy way to perform a grid search on a set of parameters.\nFor our purposes, these parameters are:\n\n* Figure 4: the eye position shifts in horizontal and vertical direction, as well as the rotation angle.\n* Figure 7: the standard deviations of the Normal distributed shifts of eye positions in horizontal and vertical direction, as well as a random seed.\n\nThe according configurations are given in **fixed_perturbation.py** (Figure 4) and **random_perturbation.py** (Figure 7).\nThere, you can find the setup as it was used to generate the according plots, but in case you want to run only a sub-set of experiments, you can reduce the parameters in each list.\n\nThe experiments can be run using the ``./bin/parameter_test.py`` script.\nThis script has several options, the most important of which are:\n\n* ``--configuration-file``: the configuration file that contains the parameters that we want to test.\n For our experiments, these are the two files **fixed_perturbation.py** (Figure 4) and **random_perturbation.py** (Figure 7).\n\n* ``--database``: the database that should be used in the experiments, which will be ``multipie-m`` in all cases.\n\n* ``--executable``: the (pythonic) name of the face verification function that will be executed.\n Since we had to modify the default script a bit, our script needs to be specified (see below).\n\n* ``--sub-directory``: the name of a directory (will be created on need), where all experiments for the given configuration file are stored.\n\n* ``--grid``: a name of a grid configuration to run algorithms in parallel (see below).\n\n* ``--verbose``: Print out additional information or debug information during the execution of the experiments.\n The ``--verbose`` option can be used several times, increasing the level to Warning (1), Info (2) and Debug (3). By default, only Error (0) messages are printed.\n The Info (aka ``-vv``) option is recommended.\n\n* ``--dry-run``: Use this option to print the calls to the FaceRecLib_ without executing them.\n Again, it is recommended to use this flag once, i.e., to check that everything is correct before running the experiments.\n\nAdditionally, parameters can be passed directly to the ``./bin/faceverify.py`` script from the FaceRecLib_.\nPlease use a ``--`` to separate parameters for ``./bin/faceverify.py`` form parameters for ``./bin/parameter_test.py``.\nUseful parameters might be the ``--result-directory`` and the ``--temp-directory`` options.\nFor a complete list of options, please check ``./bin/faceverify.py --help``.\n\nFinally, the command lines to run the experiments for Figures 4 and 7, call::\n\n $ ./bin/parameter_test.py --configuration-file fixed_perturbation.py --database multipie-m --sub-directory fixed --executable xfacereclib.paper.IET2015.script.faceverify -- --temp-directory [YOUR_TEMP_DIRECTORY] --result-directory [YOUR_RESULT_DIRECTORY]\n\n $ ./bin/parameter_test.py --configuration-file random_perturbation.py --database multipie-m --sub-directory random --executable xfacereclib.paper.IET2015.script.faceverify -- --temp-directory [YOUR_TEMP_DIRECTORY] --result-directory [YOUR_RESULT_DIRECTORY]\n\nThe last set of experiments, i.e., to regenerate Figure 13 can be run using the ``./bin/annotation_types`` script.\nAgain, this script has a set of options, most of which have proper default values:\n\n* ``--image-directory``: the base directory of the Multi-PIE database; needs to be specified.\n* ``--annotation-directory``: the base directory, where the annotations have been extracted to.\n* ``--algorithms``: a list of algorithms that should be tested; by default all five algorithms are run.\n* ``--world-types``: a list of annotation types, which should serve to train the algorithms and to enroll the models with.\n* ``--probe-types``: a list of annotation types, which should be probed against the enrolled models.\n\nAgain, the same ``--verbose`` option and options passed to the ``./bin/faceverify.py`` script exists.\nHence, the last set of experiments to be run can be started with::\n\n $ ./bin/annotation_types --image-directory [MULTIPIE_IMAGE_DIRECTORY] -vv -- --temp-directory [YOUR_TEMP_DIRECTORY] --result-directory [YOUR_RESULT_DIRECTORY]\n\n\nParallel Execution\n------------------\nSince the two command lines above execute more than 1000 individual face recognition algorithms, you might want to run them in parallel.\nFor this purpose, you can use the ``--grid`` option of the ``./bin/parameter_test.py`` script.\nThis will trigger the usage of GridTK_, a tool originally developed to submit and monitor jobs in an SGE processing farm.\nIf you have access to such a farm, you can use the ``--grid sge`` option to submit the experiments to the SGE grid (you might need to set up the SGE configuration in the grid configuration file **xfacereclib/paper/IET2015/configuration/grid.py**, in the **facereclib/utils/grid.py** of the FaceRecLib_ or in the GridTK_ itself).\n\nOn the other hand, when you have a powerful machine with lots of processing units, you can use the ``--grid local`` option.\nThis will submit jobs to the \"local\" queue, which you have to start them manually by::\n\n $ ./bin/jman --local --database [DIR]/submitted.sql3 -vv run-scheduler --parallel [NUMBER_OF_SLOTS] --die-when-finished\n\nPlease refer to the GridTK_ manual for more details.\n\n.. note::\n When submitting to the either the local queue or the SGE, several job databases called **submitted.sql3** are stored in sub-directories of the **grid_db** directory.\n You can use ``./bin/jman --database [DIR]/submitted.sql3 list`` to see the current status of the jobs stored in the given database.\n Of course, you can also use the default SGE tools (such as ``qstat``) to check the statuses of the jobs.\n\n.. warning::\n For the random experiment, please do not use more than one parallel job to preprocess the images.\n Otherwise, the random seed might be applied several times, leading to inexact results.\n\n.. note::\n The same ``--grid`` option can be used for the ``./bin/annotation_types`` script.\n Here, only one **submitted.sql3** file is written, in the current directory.\n\n\nEvaluating the Experiments\n--------------------------\nAfter all experiments have finished successfully, the resulting score files can be evaluated.\nThe figures in the paper were generated using a mix of python and R scripts, i.e., to make them look more beautiful.\nHowever, for this package we will plot the figures solely using matplotlib.\nThe ``./bin/plot_results`` script can be used to create the plots similar to the ones in Figures 4, 7 and 13.\nAdditionally, it will write **.csv** files containing the exact numbers, i.e., the Figures in in the Paper_ rely on these files.\n\nAs usual, the ``./bin/plot_results`` has a list of command line options, most of which have proper default values:\n\n* ``--scores-directory``: the base directory, where the score files have been produced.\n\n* ``--experiments``: a list of experiments to evaluate.\n By default, all three experiments are evaluated.\n\n* ``--algorithms``: a list of algorithms to evaluate.\n By default, all five algorithms are evaluated.\n\nSome more options are available, see ``./bin/plot_results --help`` for a complete list.\nHence, to produce all three plots from Figures 4, 7, and 13, simply call::\n\n $ ./bin/plot_results -vv --scores-directory [YOUR_RESULT_DIRECTORY]\n\nAfterward, the plots can be found in the **plots** directory.\nFor Figure 4, they are called **HTER_fixed.pdf** and **AUC_fixed.pdf**, while for Figure 7 they are **HTER_random.pdf** and **AUC_random.pdf**.\nThe HTER plots should be identical to the ones found in the Paper_.\nThe AUC plots have a different color coding than in the Paper_, but the contents are identical.\nFinally, the file **plots/ROCs.pdf** contains the ROC curves of Figure 13, except that the FAR range is slightly higher.\n\n\n\n.. _paper: http://publications.idiap.ch/index.php/publications/show/2981\n.. _idiap: http://www.idiap.ch\n.. _bob: http://www.idiap.ch/software/bob\n.. _facereclib: http://pypi.python.org/pypi/facereclib\n.. _github: http://github.com/bioidiap/xfacereclib.paper.IET2015\n.. _virtualbox: http://www.virtualbox.org\n.. _gridtk: http://pypi.python.org/pypi/gridtk", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "http://github.com/bioidiap/xfacereclib.paper.IET2015", "keywords": "face recognition,eye detection,geometric normalization,facereclib", "license": "GPLv3", "maintainer": null, "maintainer_email": null, "name": "xfacereclib.paper.IET2015", "package_url": "https://pypi.org/project/xfacereclib.paper.IET2015/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/xfacereclib.paper.IET2015/", "project_urls": { "Download": "UNKNOWN", "Homepage": "http://github.com/bioidiap/xfacereclib.paper.IET2015" }, "release_url": "https://pypi.org/project/xfacereclib.paper.IET2015/1.0.1/", "requires_dist": null, "requires_python": null, "summary": "Source code to reproduce the paper \"Impact of Eye Detection Error on Face Recognition Performance\"", "version": "1.0.1" }, "last_serial": 1524774, "releases": { "1.0.0": [ { "comment_text": "", "digests": { "md5": "004f058aaa2ec39f7bee3f5aeb6b361c", "sha256": "94059aa986c305353e6dea194b72a93ac0a754efc256bc84e9433ebb82260558" }, "downloads": -1, "filename": "xfacereclib.paper.IET2015-1.0.0.zip", "has_sig": false, "md5_digest": "004f058aaa2ec39f7bee3f5aeb6b361c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 55716, "upload_time": "2015-03-25T17:24:21", "url": "https://files.pythonhosted.org/packages/a6/e0/1aaac514fa84aec46a5f09ac6d7e70524e28c360b4ddb759d6848c57a4e8/xfacereclib.paper.IET2015-1.0.0.zip" } ], "1.0.0a0": [], "1.0.1": [ { "comment_text": "", "digests": { "md5": "a80b6267b75960b10b0acd2ffaac335c", "sha256": "f0e1cde58b53789991b48ba15d053aa295c8776e475c94d17676e3a2c5f707ff" }, "downloads": -1, "filename": "xfacereclib.paper.IET2015-1.0.1.zip", "has_sig": false, "md5_digest": "a80b6267b75960b10b0acd2ffaac335c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 58188, "upload_time": "2015-04-28T16:10:16", "url": "https://files.pythonhosted.org/packages/d4/9b/a16ca6ce082b51696c8277161d7459b2992bb5f73580707ad964e73a032b/xfacereclib.paper.IET2015-1.0.1.zip" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "a80b6267b75960b10b0acd2ffaac335c", "sha256": "f0e1cde58b53789991b48ba15d053aa295c8776e475c94d17676e3a2c5f707ff" }, "downloads": -1, "filename": "xfacereclib.paper.IET2015-1.0.1.zip", "has_sig": false, "md5_digest": "a80b6267b75960b10b0acd2ffaac335c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 58188, "upload_time": "2015-04-28T16:10:16", "url": "https://files.pythonhosted.org/packages/d4/9b/a16ca6ce082b51696c8277161d7459b2992bb5f73580707ad964e73a032b/xfacereclib.paper.IET2015-1.0.1.zip" } ] }