Face Attributes
Module Description
Face Attributes recognizes emotions, ethnicity, gender or facial characteristics such as "beard", "eyes closed" or "glasses" of all persons appearing in pictures or videos. It can also apply face recognition to get the corresponding identity.
Module ID: face_attributes
Module Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| model | string | celebrities | The name or the ID of the model to use (See Model Resource). |
| max_distance | number | 1.0 | Thresholding the distance, how similar (in terms of euclidean distance) the recognized identity is to the closest sample in the training data (range from 0.0 to 2.0). |
Module Result
Summary
The summary is empty for this module.
Detailed results
The actual attributes of faces can be retrieved by the detailed-results endpoint.
The following attributes are available and are shown with their data types and values:
bounding_box- Face rectangle as two pointsx1:floaty1:floatx2:floaty2:float
age- Estimated age as rangemin:integer- Min valuemax:integer- Max value
gender- Predicted gendervalue:string- Actual gender ("male", "female")confidence:float- Confidence of gender prediction (0.0 - 1.0)
emotion- Predicted emotionvalue:string- Actual emotion class ("Happy", "Sad", "Angry", "Confused", "Disgusted", "Surprised", "Calm" and "Fear")confidence:float- Confidence of emotion prediction (0.0 - 1.0)
sharpness:integer- Sharpness score (a low value means a blurry face)smile- If face is smilingvalue:boolean- true or falseconfidence:float- Confidence of the prediction (0.0 - 1.0)
eyeglasses- If person is wearing glassesvalue:boolean- true or falseconfidence:float- Confidence of the prediction (0.0 - 1.0)
sunglasses- If person is wearing sunglassesvalue:boolean- true or falseconfidence:float- Confidence of the prediction (0.0 - 1.0)
beard- If face has a beardvalue:boolean- true or falseconfidence:float- Confidence of the prediction (0.0 - 1.0)
mustache- If face has a mustachevalue:boolean- true or falseconfidence:float- Confidence of the prediction (0.0 - 1.0)
eyesopen- If eyes are openvalue:boolean- true or falseconfidence:float- Confidence of the prediction (0.0 - 1.0)
mouthopen- If mouth is openvalue:boolean- true or falseconfidence:float- Confidence of the prediction (0.0 - 1.0)
pose- Estimated head pose of the face (rotation in three dimensions)roll:float- roll angle (rotation about an axis running from the nose to the back of the head)yaw:float- yaw angle (nose left or right about an axis running up and down)pitch:float- pitch angle (nose up or down about an axis running from left to right)
In addition, there are face recognition attributes (example for video):
person:string- Name of predicted identityclosest_person:string- If predicted identity is unknown (person="unknown") only then this field is available and contains the nearest predictionmean_distance:string- Distance metric describing how similar (in terms of euclidean distance) the recognized identity is to the closest sample in the training data (0.0 - 2.0)mean_similarity:string- Similarity metric describing how similar the recognized identity is to the closest sample in the training data (0.0 - 1.0)
For more information about the face recognition related detailed objects check out this page.
The prediction of the ethnicity is coming soon!
Example
Send the following JSON as request body via POST to the /jobs/ endpoint:
{
"sources": [
"{url-to-your-image}"
],
"modules": {
"face_attributes": {}
}
}
To get the result about each face you can request the /jobs/{JOB_ID}/detailed-results/ endpoint, the response looks like this:
{
"total": 2,
"offset": 0,
"limit": 10,
"next": "https://api.deepva.com/api/v1/jobs/b6d90182-7b84-42a1-899a-e6d0e7566289/detailed-results/?limit=10&offset=10",
"prev": "https://api.deepva.com/api/v1/jobs/b6d90182-7b84-42a1-899a-e6d0e7566289/detailed-results/?limit=10&offset=0",
"data": [
{
"id": "207e8d88-240d-46e1-ac3a-73632e2d7cb6",
"media_type": "video",
"frame_start": 12,
"frame_end": 48,
"source": "storage://WQM2S9L9O0tDYacfNQN7",
"module": "face_attributes",
"meta": {
"bounding_box": {
"x1": 0.447,
"y1": 0.272,
"x2": 0.536,
"y2": 0.493
},
"age": {
"min": 26.0,
"max": 43.0
},
"gender": {
"value": "female",
"confidence": 0.99
},
"emotion": {
"value": "Happy",
"confidence": 0.96
},
"sharpness": 116.68,
"smile": {
"value": true,
"confidence": 0.95
},
"eyeglasses": {
"value": false,
"confidence": 1.0
},
"sunglasses": {
"value": false,
"confidence": 1.0
},
"beard": {
"value": false,
"confidence": 1.0
},
"mustache": {
"value": false,
"confidence": 1.0
},
"eyesopen": {
"value": true,
"confidence": 0.99
},
"mouthopen": {
"value": true,
"confidence": 0.99
},
"pose": {
"roll": 0.96,
"yaw": 42.97,
"pitch": 3.54
},
"person": "Unknown 0",
"closest_person": "Casey Wilson",
"mean_distance": 1.11,
"mean_similarity": 0.39
},
"thumbnail": null,
"detections": [],
"time_start": 0.48,
"time_end": 1.92,
"tc_start": "00:00:00:12",
"tc_end": "00:00:01:23"
},
{
"id": "e373ad10-4e8a-40e9-8b4c-915adb0c8f86",
"media_type": "video",
"frame_start": 12,
"frame_end": 24,
"source": "storage://WQM2S9L9O0tDYacfNQN7",
"module": "face_attributes",
"meta": {
"bounding_box": {
"x1": 0.828,
"y1": 0.133,
"x2": 0.93,
"y2": 0.369
},
"age": {
"min": 25.0,
"max": 41.0
},
"gender": {
"value": "male",
"confidence": 0.98
},
"emotion": {
"value": "Surprised",
"confidence": 0.61
},
"sharpness": 127.24,
"smile": {
"value": true,
"confidence": 0.63
},
"eyeglasses": {
"value": false,
"confidence": 1.0
},
"sunglasses": {
"value": false,
"confidence": 1.0
},
"beard": {
"value": false,
"confidence": 0.77
},
"mustache": {
"value": false,
"confidence": 1.0
},
"eyesopen": {
"value": true,
"confidence": 1.0
},
"mouthopen": {
"value": true,
"confidence": 0.97
},
"pose": {
"roll": -13.74,
"yaw": 30.4,
"pitch": -4.91
},
"person": "Vincenzo Grifo",
"mean_distance": 0.88,
"mean_similarity": 0.62
},
"thumbnail": null,
"detections": [],
"time_start": 0.48,
"time_end": 0.96,
"tc_start": "00:00:00:12",
"tc_end": "00:00:00:24"
}
]
}