openface/docs/setup.md

Setup

The following instructions are for Linux and OSX only. Please contribute modifications and build instructions if you are interested in running this on other operating systems.

• We strongly recommend using the Docker container unless you are experienced with building Linux software from source.
• In OSX, you may have to change the hashbangs from python2 to python.
• OpenFace has been tested in Ubuntu 14.04 and OSX 10.10 and may not work well on other distributions. Please let us know of any challenges you had to overcome getting OpenFace to work on other distributions.

Warning for architectures other than 64-bit x86

See #42.

Check out git submodules

Clone with --recursive or run git submodule init && git submodule update after checking out.

Download the models

Run models/get-models.sh to download pre-trained OpenFace models on the combined CASIA-WebFace and FaceScrub database. This also downloads dlib's pre-trained model for face landmark detection. This will incur about 500MB of network traffic for the compressed models that will decompress to about 1GB on disk.

Be sure the md5 checksums match the following. Use md5sum in Linux and md5 in OSX.

openface(master)$ md5sum models/{dlib/*.dat,openface/*.{pkl,t7}}
73fde5e05226548677a050913eed4e04  models/dlib/shape_predictor_68_face_landmarks.dat
c0675d57dc976df601b085f4af67ecb9  models/openface/celeb-classifier.nn4.v1.pkl
a59a5ec1938370cd401b257619848960  models/openface/nn4.v1.t7

With Docker

This repo can be deployed as a container with Docker for CPU mode. Be sure you have checked out the submodules and downloaded the models as described above. Depending on your Docker configuration, you may need to run the docker commands as root.

To use, place your images in openface on your host and access them from the shared Docker directory.

docker build -t openface ./docker
docker run -p 9000:9000 -t -i -v $PWD:/openface openface /bin/bash
cd /openface
./demos/compare.py images/examples/{lennon*,clapton*}

Docker in OSX

In OSX, follow the Docker Mac OSX Installation Guide and start a docker machine and connect your shell to it before trying to build the container. In the simplest case, this can be done with:

docker-machine create --driver virtualbox --virtualbox-memory 4096 default
eval $(docker-machine env default)

Docker memory issues in OSX

Some users have reported the following silent Torch/Lua failure when running batch-represent caused by an out of memory issue.

/root/torch/install/bin/luajit: /openface/batch-represent/dataset.lua:191: attempt to perform arithmetic on a nil value

If you're experiencing this, make sure you have created a Docker machine with at least 4GB of memory with --virtualbox-memory 4096.

By hand

Be sure you have checked out the submodules and downloaded the models as described above. See the Dockerfile as a reference.

This project uses python2 because of the opencv and dlib dependencies. Install the packages the Dockerfile uses with your package manager. With pip2, install numpy, pandas, scipy, scikit-learn, and scikit-image.

Next, manually install the following.

OpenCV

Download OpenCV 2.4.11 and follow their build instructions.

dlib

dlib can alternatively by installed from pypi, but might be slower than building manually because they are not compiled with AVX support.

dlib requires boost libraries to be installed.

To build manually, start by downloading dlib v18.16, then:

mkdir -p ~/src
cd ~/src
tar xf dlib-18.16.tar.bz2
cd dlib-18.16/python_examples
mkdir build
cd build
cmake ../../tools/python
cmake --build . --config Release
cp dlib.so ..

At this point, you should be able to start your python2 interpreter and successfully run import cv2; import dlib.

In OSX, you may get a Fatal Python error: PyThreadState_Get: no current thread. You may be able to resolve by rebuilding python and boost-python as reported in #21, but please file a new issue with us or dlib if you are unable to resolve this.

Torch

Install Torch from the instructions on their website and install the dependencies with luarocks install.

• dpnn: luarocks install dpnn
• nn: luarocks install nn
• optim: luarocks install optim
• csvigo: luarocks install csvigo
• If you want CUDA support, also install cudnn.torch

At this point, the command-line program th should be available in your shell.