Getting Started

In this tutorial, we shall go through the complete process of using DeepStack to build a Face Recognition system.

Setting Up DeepStack

Install and Setup DeepStack Using the Install Guide . If you have a system with Nvidia GPU, follow instruction on Using DeepStack with NVIDIA GPU to install the GPU Version of DeepStack

Starting DeepStack

Run the command below as it applies to the version you have installed

bash
docker run -e VISION-FACE=True -v localstorage:/datastore -p 80:5000 deepquestai/deepstack
bash
sudo docker run --gpus all -e VISION-FACE=True -v localstorage:/datastore -p 80:5000 deepquestai/deepstack:gpu
bash
deepstack --VISION-FACE True --PORT 80
bash
sudo docker run --runtime nvidia -e VISION-FACE=True -p 80:5000 deepquestai/deepstack:jetpack
bash
sudo deepstack start "VISION-FACE=True"

Basic Parameters

-e VISION-FACE=True This enables the face recognition APIs.

-v localstorage:/datastore This specifies the local volume where deepstack will store all data.

-p 80:5000 This makes deepstack accessible via port 80 of the machine.

Face Recognition

Think of a software that can identify known people by their names. Face Recognition does exactly that. Register a picture of a number of people and the system will be able to recognize them again anytime. Face Recognition is a two step process: The first is to register a known face and second is to recognize these faces in new pictures.

REGISTERING A FACE

Here we are building an application that can tell the names of a number of popular celebrities. First we collect pictures of a number of celebrities and we register them with DeepStack.

../_images/tomcruise.jpg
../_images/adele.jpg
../_images/idriselba.jpg
../_images/perri.jpg

Below we will register the faces with their names

python
import requests

def register_face(img_path,user_id):
   image_data = open(img_path,"rb").read()
   response = requests.post("http://localhost:80/v1/vision/face/register",
   files={"image":image_data}, data={"userid":user_id}).json()
   print(json)

register_face("cruise.jpg","Tom Cruise")
register_face("adele.jpg","Adele")
register_face("elba.jpg","Idris Elba")
register_face("perri.jpg","Christina Perri")
js
const request = require("request")
const fs = require("fs")

run_prediction("cruise.jpg","Tom Cruise")
run_prediction("elba.jpg","Idris Elba")
run_prediction("perri.jpg","Christina Perri")
run_prediction("adele.jpg","Adele")

function run_prediction(image_path,userid){

   image_stream = fs.createReadStream(image_path)

   var form = {"image":image_stream,"userid":userid}

   request.post({url:"http://localhost:80/v1/vision/face/register", formData:form},function(err,res,body){

      response = JSON.parse(body)
      console.log(response)

   })

}
c#
using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;

namespace app
{

class App {

   static HttpClient client = new HttpClient();

   public static async Task registerFace(string userid, string image_path){

      var request = new MultipartFormDataContent();
      var image_data = File.OpenRead(image_path);
      request.Add(new StreamContent(image_data),"image",Path.GetFileName(image_path));
      request.Add(new StringContent(userid),"userid");
      var output = await client.PostAsync("http://localhost:80/v1/vision/face/register",request);
      var jsonString = await output.Content.ReadAsStringAsync();

      Console.WriteLine(jsonString);

   }

   static void Main(string[] args){

      registerFace("Tom Cruise","cruise.jpg").Wait();
      registerFace("Adele","adele.jpg").Wait();
      registerFace("Idris Elba","elba.jpg").Wait();
      registerFace("Christina Perri","perri.jpg").Wait();

   }

}

}

RECOGNITION

../_images/adele2.jpg
python
import requests

test_image = open("test-image.jpg","rb").read()

res = requests.post("http://localhost:80/v1/vision/face/recognize",
files={"image":test_image}).json()

for user in res["predictions"]:
   print(user["userid"])
js
const request = require("request")
const fs = require("fs")

image_stream = fs.createReadStream("test-image.jpg")

var form = {"image":image_stream}

request.post({url:"http://localhost:80/v1/vision/face/recognize", formData:form},function(err,res,body){

   response = JSON.parse(body)
   predictions = response["predictions"]
   for(var i =0; i < predictions.length; i++){

   console.log(predictions[i]["userid"])

   }

})
c#
using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;
using Newtonsoft.Json;


namespace appone
{

class Response {

   public bool success {get;set;}
   public Face[] predictions {get;set;}

}

class Face {

   public string userid {get;set;}
   public float confidence {get;set;}
   public int y_min {get;set;}
   public int x_min {get;set;}
   public int y_max {get;set;}
   public int x_max {get;set;}

}

class App {

   static HttpClient client = new HttpClient();

   public static async Task recognizeFace(string image_path){

      var request = new MultipartFormDataContent();
      var image_data = File.OpenRead(image_path);
      request.Add(new StreamContent(image_data),"image",Path.GetFileName(image_path));
      var output = await client.PostAsync("http://localhost:80/v1/vision/face/recognize",request);
      var jsonString = await output.Content.ReadAsStringAsync();
      Response response = JsonConvert.DeserializeObject<Response>(jsonString);

      foreach (var user in response.predictions){

            Console.WriteLine(user.userid);

      }

   }

   static void Main(string[] args){

      recognizeFace("test-image.jpg").Wait();

   }

}

}

Response

text
Adele

We have just created a face recognition system. You can try with different people and test on different pictures of them.

The next tutorial is dedicated to the full power of the face recognition api as well as best practices to make the best out of it.

Performance

DeepStack offers three modes allowing you to tradeoff speed for performance. During startup, you can specify performance mode to be , High , Medium and Low.

The default mode is Medium

You can specify a different mode during startup as seen below.

CPU Version

bash
sudo docker run -e MODE=High VISION-FACE=True -v localstorage:/datastore \
-p 80:5000 deepquestai/deepstack

GPU Version

bash
sudo docker run --rm --runtime=nvidia -e MODE=High -e VISION-FACE=True \
-v localstorage:/datastore -p 80:5000 deepquestai/deepstack:gpu

Note the -e MODE=High above.