Facial Recognition

Content

• Introduction

• Facial Recognition Revision History

• System Requirement

• Tested Compatible Webcam

• Set up and execute the REST API Service

• Startup Arguments

• Service REST API Reference

• Limitation

• Reference

Introduction

Age and gender estimation RESTful API service based on Intel® OpenVINO™ toolkit and Open Model Zoo pre-trained models:

• face-detection-0204

• age-gender-recognition-retail-0013

Model detection and recognition accuracies can be found on the docs.openvino.ai website.

When the service is invoked via the HTTP protocol GET method on port 9035, it grabs image frames from a USB webcam or IP Cam video feed for inference. Within the arrival of the parameter "duration" whose default value is 1 second, the recognized multiple faces and estimated results will be responded in a JSON-type string format.

The OpenVINO™ runtime environment and service programming language is Python, so Python needs to be installed first. Compatible Python versions for this service are 3.7, 3.8 or 3.9. The inference device can select CPU or Intel iGPU through command parameters. The latest SDK version 0.1.0 supports both Windows 10 and Ubuntu on x86 platforms.

Facial Recognition Revision History

Release Date	Version	Modify	New Add	Fix
Dec. 21st, 2022	0.1.0		Initial release

System Requirement

• OS: Windows 10 LTSC/ Ubuntu 20.04 LTS ,64bit

• DRAM: 4GB at least

• Python version: 3.7-3.9

Tested Compatible Webcam

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

• Camera Sensor Unicam hm2051 in Advantech AIM-65

Set up and execute the REST API Service

1. Before installation, make sure python version 3.7, 3.8 or 3.9 installed in system.

2. Just double click setup.bat file icon, or execute setup.sh in terminal shell. Follow up the prompts to setup the runtime python virtual environment. It will create Python virtual environment in venv/ folder and those installed Python packages can be found in requirements.txt file.

3. The service listens on TCP port number 9035. Before starting the service, open a command prompt and enter the below command to make sure that no one is using the port number.

- netstat -na | findstr "9035" ……….…. On Windows

- sudo netstat -tulpn | grep 9035 ……. On Ubuntu

4. Please use the shell scripts to start or stop the service.

- start.bat or stop.bat ……….…. On Windows

- start.sh or stop.sh …….…….…. On Ubuntu

5. 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: version {SDK_ver} pong, where {SDK_ver} is the SDK working version.

curl http://{hostip}:9035/v1/ping

Startup Arguments

You can also refer to the online help, invoked with "-h" or "--help", for an explanation of the following startup optional parameters. Please update the start.bat script file to apply the required changes.

• -B, --backup-snapshot-all

no matter face recognized, backup the raw snapshot

• -b, --backup-snapshot

Back up the raw snapshot image files for face recognition to the snapshot_bak/ directory (if present)

• -c CAMID, --camid CAMID

webcam ID, minus integer means to skip initialization during start-up

• -d DEVICE, --device DEVICE

inference device: CPU (default), GPU

• -f LOG_FILE, --log-file LOG_FILE

log file name, the default value is openvino_age_gender_api.log

• -g THRES_GENDER, --thres-gender THRES_GENDER

threshold of gender decision

• -l LOG_LEVEL, --log-level LOG_LEVEL

log level:50-CRITICAL,40-ERROR,30-WARNING,20-INFO (default),10-DEBUG,0-NOTSET

• -m IMAGE, --image IMAGE

image file path or directory URL

• -n SNAPSHOT_FACE, --snapshot-face SNAPSHOT_FACE

snapshot face flag: 0-off, 1-on

• -p, --patch-disable

gender estimate patch

• -q, --quiet

quiet mode without any log

• -r RTSP, --rtsp RTSP

IP Cam RTSP URL. When it is provided, the webcam will be ignored for use

• -s SNAPSHOT, --snapshot SNAPSHOT

snapshot flag: 0-off, 1-on, 2-timestamp

• -t THRES_FACE, --thres-face THRES_FACE

threshold of face detection

• -v, --version

show sdk version then exit

• -w, --window

Windows console window is off by default

Service REST API Reference

URI pattern containing a query string is as follows:

http://{hostip}:9035/v1/{Tag}?{Parameter}={value}&{Parameter}={value}&...

Properties

The collection {Tag} has the following properties:

Tag	Type	Read/Write	HTTP Method
ping	string	R	GET
age-gender	JSON string	R	GET
snapshot	binary	R	GET

Tag description:

• ping: For testing purpose. If the service is normal, the string "version 0.1.0-win pong" or "version 0.1.0-lnx pong" will be returned for example.

• age-gender: The returned string is the age and gender of the detected face expressed in JSON format, for example [{"gender":"M", "age": 36}, {"gender":"F", "age ": 28}]. Returns [] if no face is detected.

• snapshot: Download the face detection action snapshot in PNG format image file.

Query string of age-gender tag

For formal expressions, please see

swagger_server/swagger/swagger.yaml.

Parameter	Type	Required	Default
confidence	number	False	0.5
webcam	integer	False	0
ipcam	string	False	(No default value)
duration	integer	False	1
debug	integer	False	0

Parameter description:

• confidence: Minimum confidence value ([0.0, 1.0]) from the face detection model for the detection to be considered successful.

• webcam: Which webcam used for face detection.

• ipcam: RTSP URL, for example rtsp://172.22.24.101/live1s1.sdp.

• duration: webcam/ipcam source capture period for inference.

• debug: debug level, default 0 record any snapshot, 1 record face detected, 2 no record snapshot.

Example

1. Get the age and gender of face detection:

This example detects no face.

This example detects one face.

2. Get the last camera snapshot:

Limitation

• The USB webcam should be plugged in before the service starts.

• For Windows platform, the active webcam is always occupied during service, this is to save webcam initialization time. And switching webcams requires initialization time for systems with multiple webcams.

• The 0.1.0 version is verified on Microsoft® Windows™ 10 and Ubuntu 20.04.

• If the host OpenVINO™ GPU plugin is set correctly, the inference device supports CPU or GPU.

• The age/gender estimation network is able to recognize the age of people in the range of [18, 75] years, it is not suitable for children because their faces are not in the training set, and the estimation accuracy is affected by the masked face.

• Not support Camera Sensor OV5693 in Advantech AIM-65.

Reference

• Intel® Distribution of OpenVINO™ Toolkitn

https://www.intel.com/content/www/us/en/developer/tools/openvino-toolkit/overview.html

• Swagger Editor

https://swagger.io/tools/swagger-editor/

• Github OpenVINO Python sample program

https://github.com/yas-sim/openvino-people-detection-sample