Repository files navigation

Author:

• Ernesto Coto, University of Oxford –ecoto@robots.ox.ac.uk

License: BSD (seeLICENSE.md)

This repository includes a face-search service meant to serve requests generated by thevgg_frontend web interface. However, it could be easily adapted to serve other clients. The source code for the service is located in theservice folder. See the README file insideservice for more information.

The repository also includes a data-ingestion pipeline mechanism to extract face-features from a user-defined dataset of images or a collection of videos. The output of this pipeline is then used by the face-search service to obtain the results of any search. The source code for the data-ingestion is located in thepipeline folder. See the README file insidepipeline for more information.

The most important dependency is theRetinaFace detector. In the case of ingesting videosffmpeg is also a major dependency. They must be installed in thedependencies folder. See theLICENSE.md file for links to the license of these dependencies.

ThePytorch model used for feature-extraction must be located in themodels folder. It corresponds to theSE-Resnet-50-256DVGGFace2 model. See theLICENSE.md file for links to the license of this model.

Successfully deployed on Ubuntu 14/16 LTS, macOS High Sierra v10.13.3 and Windows10 x64.

Currently, thisPytorch version of RetinaFace is used for face detection on all platforms, for which Python 3 and Pytorch are needed.

In theinstall directory you will find installation scripts for Ubuntu and macOS. Using the GPU is supported as long as the Pytorch installation can have access to the GPU. See the next section for instructions on how to enable the GPU support.

If you want to install the service in Windows, see theWindows installer for VFF to get a rough idea of how to do the deployment.

Before running the service for the first time, please check theservice/settings.py file:

1. Check that theCUDA_ENABLED flag is set toFalse if you want to use the CPU or set it toTrue if you want to use the GPU.
2. Make sure thatDEPENDENCIES_PATH points to the location of the place where the dependency libraries (e.g. Pytorch_Retinaface) are installed.
3. Make sure thatDATASET_FEATS_FILE points to the location of your dataset features file. If you do not have one, you won't be able to run the service until you run the feature computationpipeline. See the README in thepipeline directory.
4. AdjustMAX_RESULTS_RETURN as you wish.
5. Only change the rest of the settings if you really know what you are doing.

If you already have adjusted the settings and have a dataset feature file, you should be ready to start the service. To do so, start a command-line terminal and use it to go inside theservice folder, then execute thestart_backend_service.sh script (start_backend_service.bat for Windows). Use that script file to define or modify any environment variables required by your local setup.

The service should be reachable at the HOST and PORT specified in the settings.

TheWiki explains the details about the communication API used in the service, as well as it includes other useful links and information.