# Face Detection

## **Content**

* Introduction
* Tested Devices
* Run the REST API Service
* Service REST API Reference

## Introduction

The webcam face detection REST API is a wrapper of Google MediaPipe Face Detection solution. Google MediaPipe Face Detection is an ultrafast face detection solution that comes with multi-face support, and based on BlazeFace, a lightweight and well-performing face detector tailored for mobile GPU inference. Our current solution only support x86 platform and only use CPU computing power without GPU’s. 

The programming language for this solution is python, and we currently only provide a self-contained package for Windows. So it will work on Windows even without the python SDK installed. And we also provide the swagger API yaml file in the package release notes. For more information on the REST API, see the following sections.

## Tested Devices

This service has been tested with the following webcam devices:

* Logitech Webcam C930e
* Logitech C270 HD WEBCAM
* Unison USB 5.0M AF Camera
* USB 5.0M AF Camera in Advantech UTC-510G
* Advantech AIM-65: Front camera 2MP Fixed Focus and Rear 5MP Auto Focus with LED Flash

## Run the REST API Service

1\. The service runs on TCP port number 50011. Before starting the service, in Windows, open a command prompt and enter the below two commands to make sure that no one is using the port numbers.

|                                  |
| -------------------------------- |
| *netstat -na \| findstr "50011"* |

2\. Please use the installed Windows batch scripts ***start\_mp\_face\_detect.bat*** and ***stop\_mp\_face\_detect.bat*** provided in the installation package to start or stop the service.

3\. After the device service is started, you could request to hit ping endpoint for check if REST API service is available. If yes, it returns a string: ***pong***.

|                                       |
| ------------------------------------- |
| *curl http\://{hostip}:50011/v1/ping* |

## Service REST API Reference

#### **URI pattern containing a query string is as follows:**

|                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [*http://{hostip}:50011/v1/{Tag}?{Parameter}={value}&{Parameter}={value}*](http://{hostip}:50011/v1/%7BTag%7D?{Parameter}={value}&{Parameter}={value}) |

#### **Properties**

The collection {Tag} has the following properties:

<table><thead><tr><th width="160"></th><th width="150"></th><th width="150"></th><th></th></tr></thead><tbody><tr><td>Tag</td><td>Type</td><td>Read/Write</td><td>HTTP Method</td></tr><tr><td>ping</td><td>String</td><td>R</td><td>GET</td></tr><tr><td>face-detect</td><td>Integer</td><td>R</td><td>GET</td></tr><tr><td>snapshot</td><td>Binary</td><td>R</td><td>GET</td></tr></tbody></table>

* Tag description:\
  (1)  ping: For testing purposes. If the service is normal, the string “pong” will be returned.\
  (2) face-detect: Number of current detected faces, 0 means no face detected. Only this command has query string.\
  (3) snapshot: Download the face detection action snapshot in png format image file.

#### Query string of face-detect tag

<table><thead><tr><th width="233.28571428571428"></th><th width="184.95137420718817"></th><th width="186"></th><th></th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Required</td><td>Default</td></tr><tr><td>confidence</td><td>number</td><td>False</td><td>0.5</td></tr><tr><td>selfie</td><td>boolean</td><td>False</td><td>True</td></tr><tr><td>short-range</td><td>boolean</td><td>False</td><td>True</td></tr><tr><td>webcam</td><td>integer</td><td>False</td><td>0</td></tr><tr><td>debug</td><td>integer</td><td>False</td><td>0</td></tr></tbody></table>

* Parameter description:\
  (1) confidence: Minimum confidence value (\[0.0, 1.0]) from the face detection model for the detection to be considered successful.\
  (2) selfie: Face detection optimized by Selfie mode or not.\
  (3) short-range: select a short-range model that works best for faces within 2 meters from the camera, and 1 for a full-range model best for faces within 5 meters. For the full-range option, a sparse model is used for its improved inference speed.

  (4) webcam: Which webcam used for face detection.

  (5) debug: debug level, default 0 record any snapshot, 1 record face detected, 2 no record snapshot.

#### **Example**

1. Get the current face detection with default webcam id 0:

<div align="left"><img src="https://1210863923-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Ldahy90A1eekcr5A2U8%2Fuploads%2F5wSRSpUGy60eQDdriTtR%2Fdd.JPG?alt=media&#x26;token=4674205f-bc82-4851-81ba-2615cfa9c7c4" alt=""></div>

This example detects one face.

2\. Get the last face detection snapshot.

<div align="left"><img src="https://1210863923-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Ldahy90A1eekcr5A2U8%2Fuploads%2FKCBt9y0tcJBP6D9LAp8b%2Fddd.JPG?alt=media&#x26;token=4dc465cb-1963-4825-82bf-c0a36ce96e7d" alt=""></div>

The face detection snapshot image file obtained by this command:

<div align="left"><img src="https://1210863923-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Ldahy90A1eekcr5A2U8%2Fuploads%2FVzWLLSAjYmaqHtR2L9Ai%2Fss.JPG?alt=media&#x26;token=f7c8f68a-5200-496e-891a-94945f53475f" alt=""></div>

#### **Limitation**

* The USB Webcam should be plug-in before service start up.
* The webcam in use is always on during service, this is to save webcam initialization time.
* For systems with multiple webcams, it will take time to switch webcams if the current face detection webcam is different from the previous webcam.
* It support Windows only.