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.

With Docker

This repo can be used as a container with Docker for CPU mode. Depending on your Docker configuration, you may need to run the docker commands as root.

Automated Docker Build

The quickest way to getting started is to use our pre-built automated Docker build, which is available from bamos/openface. This does not require or use a locally checked out copy of OpenFace. To use on your images, share a directory between your host and the Docker container.

docker pull bamos/openface
docker run -p 9000:9000 -p 8000:8000 -t -i bamos/openface /bin/bash
cd /root/src/openface
./run-tests.sh
./demos/compare.py images/examples/{lennon*,clapton*}
./demos/classifier.py infer models/openface/celeb-classifier.nn4.v2.pkl ./images/examples/carell.jpg
./demos/web/start-servers.sh

Building a Docker Container

This builds a Docker container from a locally checked out copy of OpenFace, which will take about 2 hours on a modern machine. Be sure you have checked out the git submodules. Run the following commands from the openface directory.

docker build -t openface .
docker run -p 9000:9000 -p 8000:8000 -t -i openface /bin/bash
cd /root/src/openface
nosetests-2.7 -v -d test.py
./demos/compare.py images/examples/{lennon*,clapton*}
./demos/classifier.py infer models/openface/celeb-classifier.nn4.v2.pkl ./images/examples/carell.jpg
./demos/web/start-servers.sh

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 be installed from pypi or built manually and depends on boost libraries. Building dlib manually with AVX support provides higher performance.

To build manually, download dlib v18.16, then run the following commands. For the final command, make sure the directory is in your default Python path, which can be found with sys.path in a Python interpreter. In OSX, use site-packages instead of dist-packages.

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
sudo cp dlib.so /usr/local/lib/python2.7/dist-packages

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 $NAME, where $NAME is as listed below.

• dpnn
• nn
• optim
• csvigo
• cunn (only with CUDA)
• fblualib (only for training a DNN)

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

OpenFace

From the root OpenFace directory, run sudo python2 setup.py install.

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.