{ "info": { "author": "Andre Anjos", "author_email": "andre.anjos@idiap.ch", "bugtrack_url": null, "classifiers": [], "description": "================================================\n Eye-Blink Detector to Counter Spoofing Attacks\n================================================\n\nThis package implements an eye-blink detector using a similar frame-differences\ntechnique as described at the paper `Counter-Measures to Photo\nAttacks in Face Recognition: a public database and a baseline`, by Anjos and\nMarcel, International Joint Conference on Biometrics, 2011.\n\nIf you use this package and/or its results, please cite the following\npublications:\n\n1. The original paper with the frame-differences and normalization technique\n explained in details::\n\n @inproceedings{Anjos_IJCB_2011,\n author = {Anjos, Andr{\\'{e}} and Marcel, S{\\'{e}}bastien},\n keywords = {Attack, Counter-Measures, Counter-Spoofing, Disguise, Dishonest Acts, Face Recognition, Face Verification, Forgery, Liveness Detection, Replay, Spoofing, Trick},\n month = oct,\n title = {Counter-Measures to Photo Attacks in Face Recognition: a public database and a baseline},\n booktitle = {International Joint Conference on Biometrics 2011},\n year = {2011},\n url = {http://publications.idiap.ch/downloads/papers/2011/Anjos_IJCB_2011.pdf}\n }\n\n2. Bob as the core framework used to run the experiments::\n\n @inproceedings{Anjos_ACMMM_2012,\n author = {A. Anjos AND L. El Shafey AND R. Wallace AND M. G\\\"unther AND C. McCool AND S. Marcel},\n title = {Bob: a free signal processing and machine learning toolbox for researchers},\n year = {2012},\n month = oct,\n booktitle = {20th ACM Conference on Multimedia Systems (ACMMM), Nara, Japan},\n publisher = {ACM Press},\n url = {http://publications.idiap.ch/downloads/papers/2012/Anjos_Bob_ACMMM12.pdf},\n }\n\n3. If you decide to use the REPLAY-ATTACK database, you should also mention the\n following paper, where it is introduced::\n\n @inproceedings{Chingovska_BIOSIG_2012,\n author = {Chingovska, Ivana and Anjos, Andr{\\'{e}} and Marcel, S{\\'{e}}bastien},\n keywords = {Attack, Counter-Measures, Counter-Spoofing, Face Recognition, Liveness Detection, Replay, Spoofing},\n month = sep,\n title = {On the Effectiveness of Local Binary Patterns in Face Anti-spoofing},\n booktitle = {IEEE Biometrics Special Interest Group},\n year = {2012},\n url = {http://publications.idiap.ch/downloads/papers/2012/Chingovska_IEEEBIOSIG2012_2012.pdf},\n }\n\nIf you wish to report problems or improvements concerning this code, please\ncontact the authors of the above mentioned papers.\n\nRaw data\n--------\n\nThis method was originally conceived to work with the `the PRINT-ATTACK\ndatabase `_, but has since evolved to\nwork with the whole of the `the REPLAY-ATTACK database\n`_, which is a super-set of the\nPRINT-ATTACK database. You are allowed to select protocols in each of the\napplications described in this manual.\n\nThe data used in these experiments is publicly available and should be\ndownloaded and installed **prior** to try using the programs described in this\npackage.\n\nAnnotations\n-----------\n\nAnnotations for this work were generated with the free-software package called\n`flandmark `_. Please cite that\nwork as well if you use the results of this package on your own publication.\n\nInstallation\n------------\n\n.. note:: \n\n If you are reading this page through our GitHub portal and not through PyPI,\n note **the development tip of the package may not be stable** or become\n unstable in a matter of moments.\n\n Go to `http://pypi.python.org/pypi/antispoofing.eyeblink\n `_ to download the latest\n stable version of this package.\n\nThere are 2 options you can follow to get this package installed and\noperational on your computer: you can use automatic installers like `pip\n`_ (or `easy_install\n`_) or manually download, unpack and\nuse `zc.buildout `_ to create a\nvirtual work environment just for this package.\n\nUsing an automatic installer\n============================\n\nUsing ``pip`` is the easiest (shell commands are marked with a ``$`` signal)::\n\n $ pip install antispoofing.eyeblink\n\nYou can also do the same with ``easy_install``::\n\n $ easy_install antispoofing.eyeblink\n\nThis will download and install this package plus any other required\ndependencies. It will also verify if the version of Bob you have installed\nis compatible.\n\nThis scheme works well with virtual environments by `virtualenv\n`_ or if you have root access to your\nmachine. Otherwise, we recommend you use the next option.\n\nUsing ``zc.buildout``\n=====================\n\nDownload the latest version of this package from `PyPI\n`_ and unpack it in your\nworking area. The installation of the toolkit itself uses `buildout\n`_. You don't need to understand its inner workings\nto use this package. Here is a recipe to get you started::\n \n $ python bootstrap.py \n $ ./bin/buildout\n\nThese 2 commands should download and install all non-installed dependencies and\nget you a fully operational test and development environment.\n\n.. note::\n\n The python shell used in the first line of the previous command set\n determines the python interpreter that will be used for all scripts developed\n inside this package. Because this package makes use of `Bob\n `_, you must make sure that the ``bootstrap.py``\n script is called with the **same** interpreter used to build Bob, or\n unexpected problems might occur.\n\n If Bob is installed by the administrator of your system, it is safe to\n consider it uses the default python interpreter. In this case, the above 3\n command lines should work as expected. If you have Bob installed somewhere\n else on a private directory, edit the file ``buildout.cfg`` **before**\n running ``./bin/buildout``. Find the section named ``buildout`` and edit the\n line ``prefixes`` to point to the directory where Bob is installed or built.\n For example::\n\n [buildout]\n ...\n prefixes=/Users/crazyfox/work/bob/build\n\nUser Guide\n----------\n\nIt is assumed you have followed the installation instructions for the package\nand got this package installed and the REPLAY-ATTACK (or PRINT-ATTACK) database\ndownloaded and uncompressed in a directory to which you have read access.\nThrough this manual, we will call this directory ``/root/of/database``. That\nwould be the directory that *contains* the sub-directories ``train``, ``test``,\n``devel`` and ``face-locations``.\n\nNote for Grid Users\n===================\n\nAt Idiap, we use the powerful Sun Grid Engine (SGE) to parallelize our job\nsubmissions as much as we can. At the Biometrics group, we have developed a\n`little toolbox ` that can submit and\nmanage jobs at the Idiap computing grid through SGE. If you are at Idiap, you\ncan download and install this toolset by adding ``gridtk`` at the ``eggs``\nsection of your ``buildout.cfg`` file, if it is not already there. If you are\nnot, you still may look inside for tips on automated parallelization of\nscripts.\n\nThe following sections will explain how to reproduce the paper results in\nsingle (non-gridified) jobs. A note will be given where relevant explaining how\nto parallalize the job submission using ``gridtk``.\n\n.. note::\n\n If you decide to run using the grid at Idiap, please note that our Lustre\n filesystem does not work well with SQLite. So, do **not** place the\n ``xbob.db.replay`` package inside that filesystem. You can and **should**\n save your results on ``/idiap/temp`` though.\n\nCalculate Frame Differences\n===========================\n\nThe eye-blink detector calculates normalized frame differences like our face\n*versus* background motion detector at the `antispoofing.motion package\n`_, except it does it for\nthe eye region and face remainer (the part of the face that does not contain\nthe eye region). In the first stage of the processing, we compute the eye\nand face remainder regions normalized frame differences for each input video.\nTo do this, just execute::\n\n $ ./bin/framediff.py /root/of/database /root/of/annotations results/framediff\n\nThere are more options for the `framediff.py` script you can use (such as the\nsub-protocol selection). Note that, by default, all applications are tunned to\nwork with the **whole** of the replay attack database. Just type `--help` at\nthe command line for instructions.\n\nThere is one parameter in special you may need tunning on the above script,\nwhich relates to the ``--maximum-displacement`` option. This option controls\nthe percentage in eye-center movement in which the method still considers the\ncurrent detection is valid, w.r.t. the previous frame. If the eye-center\npositions between the current and previous frame move more than the specified\nratio of the eye-width, then the detection is considered invalid and is\ndiscarded.\n\n.. note::\n\n To parallelize this job, do the following::\n\n $ ./bin/jman submit --array=1300 ./bin/framediff.py /root/of/database /root/of/annotations results/framediff\n\n The `magic` number of `1300` entries can be found by executing::\n\n $ ./bin/framediff.py --grid-count\n\n Which just prints the number of jobs it requires for the grid execution.\n\nCreating Partial Score Files\n============================\n\nTo create the final score files, you will need to execute ``make_scores.py``,\nwhich contains a simple strategy for producing a single score per input frame\nin every video. The final score is calculated from the input eye and face\nremainder frame differences in the following way::\n\n S = ratio(eye/face_rem) - running_average(ratio(eye/face_rem))\n\n The final score is set to S, unless any of the following conditions are met:\n\n 1\n S < running_std_deviation(ratio(...))\n\n 2\n eye == 0\n\n 3\n S < running_average(ratio(...))\n\n In these cases S is replaced by the output of running_average(ratio(...)).\n\nTo compute the scores ``S`` for every frame in every input video, do the\nfollowing::\n\n $ ./bin/make_scores.py --verbose results/framediff results/partial_scores\n\nThere are more options for the `framediff.py` script you can use (such as the\nsub-protocol selection). Note that, by default, all applications are tunned to\nwork with the **whole** of the replay attack database. Just type `--help` at\nthe command line for instructions.\n\nWe don't provide a grid-ified version of this step because the job runs quite\nfast, even for the whole database.\n\nCounting Eye-Blinks\n===================\n\nThe next step of the process is to use the partial scores for each video (a\nsignal through time) to count the number of blinks perceived in every database\nelement. You can use the ``count_blinks.py`` script for that::\n\n $ ./bin/count_blinks.py --verbose results/partial_scores results/blinks\n\nThe output files will have integer values as scores for each frame, with the\nnumber of blinks accounted up to that point in time. These files can be used as\nscore output files for fusion processes.\n\nMerging Scores\n==============\n\nIf you wish to create a single `5-column format file\n`_\nby combining this counter-measure scores for every video into a single file\nthat can be fed to external analysis utilities such as our\n`antispoofing.evaluation `\npackage, you should use the script ``count_blinks.py``. The merged scores\nrepresent the number of eye-blinks computed for each video sequence. You will\nhave to specify how many of the scores in every video you will want to consider\nand the input directory containing the scores files that will be merged (by\ndefault, the procedure considers only the first 220 frames, which is some sort\nof *common denominator* between real-access and attack video number of frames).\n\nThe output of the program consists of a single 5-column formatted file with the\nclient identities and scores for **every video** in the input directory. A line\nin the output file corresponds to a video from the database. \n\nYou run this program on the output of ``make_scores.py``. So, it should look\nlike this if you followed the previous example::\n\n $ ./bin/merge_scores.py --verbose results/partial_scores results/blinks\n\nThe above commandline example will generate 3 text files on the ``results``\ndirectory containing the training, development and test scores, accumulated\nover each video in the respective subsets. You can use other options to limit\nthe number of outputs in each file such as the protocol or support to use.\n\nThere are two main options you may need to tweak on this program:\n``--skip-frames`` and ``--threshold-ratio``. The first one, ``--skip-frames``,\ndetermines how many frames to skip between eye-blinks, to avoid multiple\neye-blink detections on a single user blink (defaults to ``10``). The other\nparameter defines how many standard-deviations from the running mean, a given\nsignal peak should be considered as originating from an eye-blink. It is set by\ndefault to ``3.0``.\n\nCreating Movies\n===============\n\nYou can create animated movies showing the detector operation using the\n``make_movie.py`` script. This script will combine all the above steps in the\ndetection process and will generate a movie file showing the original input\nmovie that is being analyzed, facial landmarks, the light normalization result\nand the resulting score evolution, together with instantaneous eye-blink\nthresholds. You can use it to debug the eye-blinking detector and better tune\nthe parameters for batch processing. The script takes the full path to a movie\nfile in the REPLAY-ATTACK database and an output movie filename::\n\n $ ./bin/make_movie.py database/train/attack/hand/attack_print_client001_session01_highdef_photo_controlled.mov test.avi\n\nYou can use many of the tweaking options defined in the batch processing\nscripts to fine tune the output behavior. Use ``--help`` to find-out more\ninformation about this program.\n\nProblems\n--------\n\nIn case of problems, please contact any of the authors of the paper.", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "http://pypi.python.org/pypi/antispoofing.eyeblink", "keywords": null, "license": "GPLv3", "maintainer": null, "maintainer_email": null, "name": "antispoofing.eyeblink", "package_url": "https://pypi.org/project/antispoofing.eyeblink/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/antispoofing.eyeblink/", "project_urls": { "Download": "UNKNOWN", "Homepage": "http://pypi.python.org/pypi/antispoofing.eyeblink" }, "release_url": "https://pypi.org/project/antispoofing.eyeblink/1.0.4/", "requires_dist": null, "requires_python": null, "summary": "Eye-blinking counter-measures for the REPLAY-ATTACK database", "version": "1.0.4" }, "last_serial": 819094, "releases": { "1.0.0": [ { "comment_text": "", "digests": { "md5": "fc01d3e26f93ac047016b65c5dfd6572", "sha256": "185ecc93f4870563d60271b1ca729e97293ba5ea0450cf7309ed7596a2be8713" }, "downloads": -1, "filename": "antispoofing.eyeblink-1.0.0.zip", "has_sig": false, "md5_digest": "fc01d3e26f93ac047016b65c5dfd6572", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 40403, "upload_time": "2012-09-28T11:33:12", "url": "https://files.pythonhosted.org/packages/17/f8/05d3b5f3e65ef6676c1015883b33d3c254061c8961819f2ce97ab31ff56b/antispoofing.eyeblink-1.0.0.zip" } ], "1.0.1": [ { "comment_text": "", "digests": { "md5": "19e158d2efa21c28a6a1b576cf263919", "sha256": "8b49516d234ec5899da671598ce9002b31b334c26b383598ab491395a1d9a61f" }, "downloads": -1, "filename": "antispoofing.eyeblink-1.0.1.zip", "has_sig": false, "md5_digest": "19e158d2efa21c28a6a1b576cf263919", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 40406, "upload_time": "2012-10-03T12:59:45", "url": "https://files.pythonhosted.org/packages/2c/3a/b97e792d5ddd1e8f4352703d2e9b49c888ed20bbda6fd4f4ebb7cdaaf4bb/antispoofing.eyeblink-1.0.1.zip" } ], "1.0.2": [ { "comment_text": "", "digests": { "md5": "d0d3b43729bca1b4831be78b830d5989", "sha256": "d05a201745755eb24b955ffdc56ce11b6d428162be86d68bf572c1a33674adc0" }, "downloads": -1, "filename": "antispoofing.eyeblink-1.0.2.zip", "has_sig": false, "md5_digest": "d0d3b43729bca1b4831be78b830d5989", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 37728, "upload_time": "2013-02-19T12:00:46", "url": "https://files.pythonhosted.org/packages/9b/7f/51059a4544fcb275914f11c862e1ea23335dc2d130895f30334f620a0f80/antispoofing.eyeblink-1.0.2.zip" } ], "1.0.3": [ { "comment_text": "", "digests": { "md5": "d846362f205be5ec3e9a07b5c749eecc", "sha256": "78f1199ad5172d8b63b48efc56d65f3bcce6fec72ff7ba180f220e9d59e828e2" }, "downloads": -1, "filename": "antispoofing.eyeblink-1.0.3.zip", "has_sig": false, "md5_digest": "d846362f205be5ec3e9a07b5c749eecc", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 37717, "upload_time": "2013-02-19T14:39:39", "url": "https://files.pythonhosted.org/packages/f0/64/2e3bd02769f70ff6400f62575797386d3988e834deb9a9428f6ff7775d6a/antispoofing.eyeblink-1.0.3.zip" } ], "1.0.4": [ { "comment_text": "", "digests": { "md5": "26edfa62160d5d5e1f7140d4d7e19910", "sha256": "eb3fddee5aa467d8832822f27edeffc44fadd888c6d5b4b038b5ce1dbcfb6845" }, "downloads": -1, "filename": "antispoofing.eyeblink-1.0.4.zip", "has_sig": false, "md5_digest": "26edfa62160d5d5e1f7140d4d7e19910", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 38275, "upload_time": "2013-07-19T12:50:32", "url": "https://files.pythonhosted.org/packages/59/9d/6b269ae17cc630cdaaf7244521b2a8788c35c7eccf16be463341ce5e4e02/antispoofing.eyeblink-1.0.4.zip" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "26edfa62160d5d5e1f7140d4d7e19910", "sha256": "eb3fddee5aa467d8832822f27edeffc44fadd888c6d5b4b038b5ce1dbcfb6845" }, "downloads": -1, "filename": "antispoofing.eyeblink-1.0.4.zip", "has_sig": false, "md5_digest": "26edfa62160d5d5e1f7140d4d7e19910", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 38275, "upload_time": "2013-07-19T12:50:32", "url": "https://files.pythonhosted.org/packages/59/9d/6b269ae17cc630cdaaf7244521b2a8788c35c7eccf16be463341ce5e4e02/antispoofing.eyeblink-1.0.4.zip" } ] }