5 Face Detection Quickstart Guide

This page provides a comprehensive guide to how you can quickly use the face detection function in Mercury Cloud.

The Face Detection API detects faces in images and returns rectangle coordinates representing the locations of the faces. The API also extracts several face-related attributes, such as face angle, gender, age, emotion, etc. All attributes are predicted by AI algorithms, not actual classification.

The following steps upload a single image and detect faces within the images. When detected successfully, the system returns the detected face information.

5.1 Preparation

To start, make sure you have a Python environment installed.

Download and copy the following Python files to your Python path folder.

1KB

auth_headers.py

API Auth Headers Generator

611B

base64_encode.py

Image File to Base64 Converter

2KB

detect_faces.py

Face Detection

605B

api_parameters.py

API Parameters

Open the api_parameters.py with a text editor and replace the following parameters will your info. Refer to Section 3.2 for more details.

Python

# Common parameters. Used for all API calls.
# Base URL for Mercury Open API.
api_url = "https://mercury.japancv.co.jp/openapi/face/v1"
# Provision App Id for API calls.
app_id = "aabbccdd-eeff-0011-2233-445566778899"
# Provision access key to authentication.
access_key = '00112233-4455-6677-8899-aabbccddeeff'
# Provision secret key to authentication.
secret_key = '13579acegijmoqsuwyACEGIJMOPSUWY'

5.2 Send a face detection request

Try the following command to send an API call of Face Detection to detect faces in that image. Replace the path with your Python library path and target image file path, respectively.

Bash

python {python_path}\detect_faces.py "{image_path}\image.jpg"

The result would be shown as follows. It includes a detection results field that shows whether a face has been detected and detected face details.

Detect image: {image_path}\image.jpg
Http status code: 200
Detect face. rectangle: {'top': 625, 'left': 350, 'width': 793, 'height': 818} angle: {'yaw': -0.42474133, 'pitch': 9.596367, 'roll': 0.07245465}
Predicted attributes:
        Age: 29 ~ 39
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE

Here,HAT_STYLE_TYPE_NONEmeans the face detected is not wearing a hat/cap. TRANSPARENT_GLASSES means the face detected is wearing a pair of normal glasses (not sunglasses). COLOR_TYPE_NONE means that the face detected is not wearing a mask.

For more details on attributes information, refer to the latest version YAML file or online API manual provided in Chapter 2.

Table: Attributes

Item	Description	Meaning of values
age_lower_limit	The estimated lower limit of age	-
age_up_limit	The estimated upper limit of age	-
st_age	The estimated classification of age	ST_CHILD: Child ST_ADULT: Adult ST_OLD: Elderly
gender_code	The estimated classification of gender	MALE: Male FEMALE: Female
mustache_style	The estimated classification of bearded	MUSTACHE_STYLE_TYPE_NONE: No mustache WHISKERS: Has mustache
respirator_color	The estimated status of mask wearing	COLOR_TYPE_NONE: Not wearing a mask COLOR_TYPE_OTHER: Wearing a mask
glass_style	The estimated status of glasses wearing	GLASSES_STYLE_TYPE_NONE: Not wearing glasses TRANSPARENT_GLASSES: Wearing normal glasses SUNGLASSES: Wearing sunglasses
cap_style	The estimated status of hat wearing	HAT_STYLE_TYPE_NONE: Not wearing a cap CAP: Wearing a cap
st_helmet_style	The estimated status of helmet wearing	ST_HELMET_STYLE_TYPE_NONE: Not wearing a helmet ST_HELMET: Wearing a helmet
st_expression	The estimated classification of emotions	ST_CALM: calm ST_HAPPY: happy ST_ANGRY: angry ST_SURPRISED: surprised ST_SORROW: sorrow
st_respirator	Reserved and not used	-