Skip to content
A RESTful web service for detecting faces, pose, and fiducial markers from an image
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status

Executive Summary

This is a RESTful API for segmenting human faces from an image. The software is powered by face parts using CImg for image loading. The goal of this project is threefold:

  1. Remove the dependency on Matlab
  2. Make the code more usable by wrapping it in a RESTful API. This makes use of a modified version of QtWebApp
  3. Speed up the code by making use of Threaded Building Blocks

Here is an example of the output

Submitting an image with Postman

Mac Necessary Libraries (Tested on OSX 10.9.4)

  1. Install XCode developer tools and homebrew
  2. brew install libjpeg-turbo
  3. brew install tbb
  4. Install MacPorts from here
  5. sudo port install atlas +clang+nofortran (might take a while)
  6. Download and install Qt 5.2.1 from here

Red Hat Necessary Libraries (Tested on Centos 6.5)

  1. sudo yum install atlas-devel.x86_64
  2. sudo yum install libjpeg-devel
  3. sudo yum install tbb-devel
  4. sudo yum install qt5-qtbase-devel

Ubuntu Necessary Libraries (Tested on Ubuntu 14.04)

  1. sudo apt-get install libatlas-base-dev
  2. sudo apt-get install libjpeg-dev
  3. sudo apt-get install libtbb-dev
  4. sudo apt-get install qt5-default
  5. sudo apt-get install maven

(for running the code, don't install the devel versions, just use the regular versions)

Make Instructions

We are using maven as a build architecture. I have tested this using maven version 3.0.5.

  1. Add qmake to your path
  2. mvn install

Running the Server

In order to start the webserver run target/classes/face-parts-service src/main/resources/configfile.ini. At this point, the server is ready to segment images. In order to submit an image, create a multipart form and submit a JPEG file (right now the server only works with JPEGs) to http://localhost:8084/face-parts/generate with a key named "file". An example of submitting a file using the Chrome web browser extension Postman can be seen below.

Submitting an image with Postman

If the request was successful, a 200 response will be returned along with some JSON described here, where the outer array is a list of all the faces found:

    "face": {
        "x1": <upper left x coordinate of face box>,
        "y1": <upper left y coordinate of face box>,
        "x2": <lower right x coordinate of face box>,
        "y2": <lower right x coordinate of face box>
    "pose": <angle the person is facing from -90 to 90 degrees>,
    "model": <frontal or profile depending on which model was used to find the face>,
    "parts":  {
        <descriptive name of face region>: [
                "x": <x coordinate of face part>,
                "y": <y coordinate of face part>,
                "num": <the part number in the model>

The server is also able to return an image with the information about the face overlayed on it. In order to do that, submit the same request as above to http://localhost:8084/face-parts/generate.jpg

If you want to get just a list of the points instead of the descriptive regions, submit the request to http://localhost:8084/face-parts/generate?points=inline


The webserver can be configured in a variety of ways. An example configuration file is found at src/main/resources/configfile.ini. It is very important that the lines


point to valid files, as these represent the models used for segmentation. These paths are relative to the directory the program was started from.

You can’t perform that action at this time.