Face Image Quality Assessment
Face image quality assessment comes in handy if you need to check whether a photo portrait meets certain standards. For example, a person in the picture should not smile and wear glasses and should look directly at the camera, the image width to height should be of certain proportions, etc. The feature is perfect for checking photo validity for visas and other official documents.
To enable the portrait quality assessment, add the specified request parameters of the detect command and set the required characteristics.
Scenarios
The assessment may be performed in two ways:
- By the selected characteristics when you add them manually in the request. In this case, the configuration is not saved and can not be automatically repeated.
- By a processing scenario that already includes certain characteristics. You can either use predefined scenarios or add custom ones.
The following ready-made scenarios are available for face image qualtiy check:
QualityFullchecks all the available quality characteristics.QualityICAOchecks the quality characteristics based on the ICAO standard.QualityVisaSchengenchecks the quality characteristics based on the Schengen visa standard.QualityVisaUSAchecks the quality characteristics based on the USA visa standard.
The settings for each scenario are listed in the Scenarios file.
Request
└── quality
└── backgroundMatchColor
└── config
└── name
└── range
| Parameter | Description |
|---|---|
| quality | If set, face image quality assessment is performed. |
| backgroundMatchColor | The RGB value for the required background color. To check whether the photo background matches this color, use the BackgroundColorMatch parameter in the Background group. |
| config | The configuration that defines the list of returned quality check characteristics. For each characteristic, includes name and range. See the Сharacteristics section for details. |
| name | The name of the characteristic. |
| range | The range of applicable values for this characteristic. If the returned value in the response fits the range, the value is identified as compliant with the standard. You can define any valid range for each characteristic. |
Response
The response returns the list of characteristics with a processing status for each, see the FaceImageQualityStatus enum. The list of returned parameters is defined by the set configuration.
└── quality
└── details
| └── groupId
| └── name
| └── range
| └── status
| └── value
└── detailsGroups
| └── compliantCount
| └── groupId
| └── name
| └── totalCount
└── nonCompliant
└── score
└── timer
| Parameter | Description |
|---|---|
| quality | The array for the face image quality assessment. |
| details | Quality assessment details. |
| groupId | The ID of the characteristics group, see the FaceImageQualityGroups enum. |
| name | The name of the characteristic. |
| range | The range of set values for this characteristic. |
| status | The assessment status of the characteristic, see the FaceImageQualityStatus enum. |
| value | The assessed value for the characteristic. |
| detailsGroups | The array of the assessment results for each group of characteristics. Includes complianCount, groupId, name, totalCount. |
| compliantCount | The number of compliant characteristics in the group. |
| groupId | The ID of the characteristics group, see the FaceImageQualityGroups enum. |
| name | The name of the characteristics group. |
| totalCount | The total number of characteristics in the group. |
| nonCompliant | The names of the characteristics that are not compliant. |
| score | The total value for the quality assessment, not used yet. |
| timer | The total time the quality assessment has taken. |
Response example
Click here to see a non-compliant response sample with the QualityVisaSchengen scenario.
{
"code": 0,
"msg": "FACER_OK",
"results": {
"detections": [
{
"quality": {
"details": [
{
"groupId": 1,
"name": "ImageWidth",
"range": [
420,
10000
],
"status": 1,
"value": 420
},
{
"groupId": 1,
"name": "ImageHeight",
"range": [
540,
10000
],
"status": 1,
"value": 540
},
{
"groupId": 1,
"name": "ImageWidthToHeight",
"range": [
0.7400000095367432,
0.800000011920929
],
"status": 1,
"value": 0.7777777910232544
},
{
"groupId": 1,
"name": "ImageChannelsNumber",
"range": [
3,
3
],
"status": 1,
"value": 3
},
{
"groupId": 2,
"name": "FaceMidPointHorizontalPosition",
"range": [
0.44999998807907104,
0.550000011920929
],
"status": 1,
"value": 0.5
},
{
"groupId": 2,
"name": "FaceMidPointVerticalPosition",
"range": [
0.30000001192092896,
0.5
],
"status": 1,
"value": 0.4203703701496124
},
{
"groupId": 2,
"name": "HeadWidthRatio",
"range": [
0.5,
0.75
],
"status": 1,
"value": 0.6150566339492798
},
{
"groupId": 2,
"name": "HeadHeightRatio",
"range": [
0.6000000238418579,
0.8999999761581421
],
"status": 1,
"value": 0.7359653115272522
},
{
"groupId": 2,
"name": "EyesDistance",
"range": [
90,
10000
],
"status": 1,
"value": 114
},
{
"groupId": 2,
"name": "Yaw",
"range": [
-5,
5
],
"status": 1,
"value": 3.1271400451660156
},
{
"groupId": 2,
"name": "Pitch",
"range": [
-5,
5
],
"status": 0,
"value": -8.97469711303711
},
{
"groupId": 2,
"name": "Roll",
"range": [
-5,
5
],
"status": 1,
"value": 0.05881465971469879
},
{
"groupId": 3,
"name": "BlurLevel",
"range": [
0,
0.15000000596046448
],
"status": 1,
"value": 0.095797598361969
},
{
"groupId": 3,
"name": "NoiseLevel",
"range": [
0,
0.20000000298023224
],
"status": 1,
"value": 0.007410287857055664
},
{
"groupId": 4,
"name": "EyeRightClosed",
"range": [
0,
0.5
],
"status": 1,
"value": 0
},
{
"groupId": 4,
"name": "EyeLeftClosed",
"range": [
0,
0.5
],
"status": 1,
"value": 0
},
{
"groupId": 4,
"name": "EyeRightOccluded",
"range": [
0,
0.5
],
"status": 1,
"value": 0
},
{
"groupId": 4,
"name": "EyeLeftOccluded",
"range": [
0,
0.5
],
"status": 1,
"value": 0
},
{
"groupId": 4,
"name": "EyesRed",
"range": [
0,
0.5
],
"status": 1,
"value": 0
},
{
"groupId": 4,
"name": "EyeRightCoveredWithHair",
"range": [
0,
0.05000000074505806
],
"status": 1,
"value": 0
},
{
"groupId": 4,
"name": "EyeLeftCoveredWithHair",
"range": [
0,
0.05000000074505806
],
"status": 1,
"value": 0
},
{
"groupId": 4,
"name": "OffGaze",
"range": [
0,
0.4000000059604645
],
"status": 1,
"value": 0.06515510380268097
},
{
"groupId": 3,
"name": "FaceDynamicRange",
"range": [
7,
8
],
"status": 1,
"value": 7.839203834533691
},
{
"groupId": 3,
"name": "UnnaturalSkinTone",
"range": [
0,
0.5
],
"status": 1,
"value": 0.07226277887821198
},
{
"groupId": 5,
"name": "TooDark",
"range": [
0,
0.3799999952316284
],
"status": 1,
"value": 0.07556390762329102
},
{
"groupId": 5,
"name": "TooLight",
"range": [
0,
0.5
],
"status": 1,
"value": 0.007647450547665358
},
{
"groupId": 5,
"name": "FaceGlare",
"range": [
0,
0.5
],
"status": 1,
"value": 0.11332553625106812
},
{
"groupId": 5,
"name": "ShadowsOnFace",
"range": [
0,
0.5
],
"status": 1,
"value": 0.028832528740167618
},
{
"groupId": 7,
"name": "DarkGlasses",
"range": [
0,
0.5
],
"status": 1,
"value": 0
},
{
"groupId": 7,
"name": "ReflectionOnGlasses",
"range": [
0,
0.5
],
"status": 1,
"value": 0.25
},
{
"groupId": 7,
"name": "FramesTooHeavy",
"range": [
0,
6
],
"status": 1,
"value": 0
},
{
"groupId": 7,
"name": "FaceOccluded",
"range": [
0,
0.05999999865889549
],
"status": 1,
"value": 0.00022019965399522334
},
{
"groupId": 7,
"name": "HeadCovering",
"range": [
0,
0.5
],
"status": 1,
"value": 0.00013961024524178356
},
{
"groupId": 8,
"name": "BackgroundUniformity",
"range": [
0.8999999761581421,
1
],
"status": 0,
"value": 0.6794372797012329
},
{
"groupId": 8,
"name": "ShadowsOnBackground",
"range": [
0.8999999761581421,
1
],
"status": 0,
"value": 0.6794372797012329
},
{
"groupId": 8,
"name": "OtherFaces",
"range": [
1,
1
],
"status": 1,
"value": 1
},
{
"groupId": 6,
"name": "ShouldersPose",
"range": [
0.6000000238418579,
1
],
"status": 1,
"value": 0.8677659034729004
},
{
"groupId": 6,
"name": "ExpressionLevel",
"range": [
0,
0.8399999737739563
],
"status": 1,
"value": 0.05799868702888489
},
{
"groupId": 6,
"name": "MouthOpen",
"range": [
0,
0.5
],
"status": 1,
"value": 0
},
{
"groupId": 7,
"name": "ForeheadCovering",
"range": [
0,
0.5
],
"status": 1,
"value": 0.009752925485372543
},
{
"groupId": 6,
"name": "Smile",
"range": [
0,
0.5
],
"status": 1,
"value": 0.0000024437904357910156
},
{
"groupId": 7,
"name": "StrongMakeup",
"range": [
0,
0.5
],
"status": 0,
"value": 0.5918601155281067
},
{
"groupId": 7,
"name": "Headphones",
"range": [
0,
0.5
],
"status": 0,
"value": 0.9487101435661316
}
],
"detailsGroups": [
{
"compliantCount": 4,
"groupId": 1,
"name": "ImageCharacteristics",
"totalCount": 4
},
{
"compliantCount": 7,
"groupId": 2,
"name": "HeadSizeAndPosition",
"totalCount": 8
},
{
"compliantCount": 4,
"groupId": 3,
"name": "FaceQuality",
"totalCount": 4
},
{
"compliantCount": 8,
"groupId": 4,
"name": "EyesCharacteristics",
"totalCount": 8
},
{
"compliantCount": 4,
"groupId": 5,
"name": "ShadowsAndLightning",
"totalCount": 4
},
{
"compliantCount": 4,
"groupId": 6,
"name": "PoseAndExpression",
"totalCount": 4
},
{
"compliantCount": 6,
"groupId": 7,
"name": "HeadOcclusion",
"totalCount": 8
},
{
"compliantCount": 1,
"groupId": 8,
"name": "Background",
"totalCount": 3
}
],
"nonCompliant": [
"Pitch",
"BackgroundUniformity",
"ShadowsOnBackground",
"StrongMakeup",
"Headphones"
],
"score": -1,
"timer": 0.490784615278244
},
"roi": [
775,
174,
462,
649
]
}
],
"detectorType": 4,
"landmarksType": 2,
"scenario": "QualityVisaSchengen",
"timer": 0.857108576
}
}
Characteristics
The characteristics are divided into groups, and information on each group is returned in the detailsGroups field.
Image characteristics
| Name | Description | Recommended range | ICAO standard |
|---|---|---|---|
| ImageWidth | The image width, pixels. | Not defined | 1200 px |
| ImageHeight | The image height, pixels. | Not defined | 1600 px |
| ImageWidthToHeight | The image width to height proportion. | Not defined | 0.74, 0.8 |
| ImageChannelsNumber | The image RGB channels number. | Not defined | 3 |
| ArtFace | Whether the face in the image is a photo, not a drawing, sculpture, cartoon, etc. If the returned value is out of the recommended range, the image is not a photo. | 0, 0.5 | Not regulated by the standard |
| PaddingRatio | The percentage of the area of the image that was "padded" during alignment. The characteristic is needed to determine if the head goes beyond the image. If no alignment performed, returns 0. |
Not defined | Not regulated by the standard |
Head size and position
| Name | Description | Recommended range | ICAO standard |
|---|---|---|---|
| FaceMidPointHorizontalPosition | The position of the "middle point" (the middle of the line connecting the eye centers) relative to the width of the image. | 0.45, 0.55 | Should be in a certain place so that alignment could be performed and the face placed correctly. |
| FaceMidPointVerticalPosition | The position of the "middle point" (the middle of the line connecting the eye centers) relative to the height of the image. | 0.45, 0.55 | Should be in a certain place so that alignment could be performed and the face placed correctly. |
| HeadWidthRatio | The head width to the image width ratio. | 0.5, 0.75 | 0.5, 0.75 |
| HeadHeightRatio | The head height to the image height ratio. | 0.6, 0.9 | 0.6, 0.9 |
| EyesDistance | Inter-eye distance — the length of the line connecting the eye centers of the left and right eye, pixels. | 240 | 240 |
| Yaw | The yaw of the head, degrees. | -5,5 | -5,5 |
| Pitch | The pitch of the head, degrees. | -5,5 | -5,5 |
| Roll | The roll of the head, degrees. | -5,5 | -5,5 |
Face image quality
| Name | Description | Recommended range | ICAO standard |
|---|---|---|---|
| BlurLevel | The blur level. | 0, 0.5 | The image should not be blurry. |
| NoiseLevel | The noise level. | 0, 0.5 | The image should not contain noise. |
| UnnaturalSkinTone | The true-colour representation of the skin colour. | 0, 0.5 | All images should be captured in colour. Newly designed enrolment should capture colour images only. The captured portrait should be a true-colour representation of the holder in a typical colour space. |
| FaceDynamicRange | The range of tonal difference between the lightest light and darkest dark of an image, bits. | 7,8 | The dynamic range should have at least 50% of intensity variation in the facial region of the image. |
Eyes characteristics
| Name | Description | Recommended range | ICAO standard |
|---|---|---|---|
| EyeRightClosed | Whether the right eye is closed. | 0, 0.5 | Eyes should be open. |
| EyeLeftClosed | Whether the left eye is closed. | 0, 0.5 | Eyes should be open. |
| EyeRightOccluded | Whether the right eye is occluded. | 0, 0.5 | Eyes should not be occluded. |
| EyeLeftOccluded | Whether the left eye is occluded. | 0, 0.5 | Eyes should not be occluded. |
| EyesRed | Whether there is the red-eye effect. | 0, 0.5 | There should be no red-eye effect. |
| EyeRightCoveredWithHair | Whether the right eye is covered with hair. | 0, 0.5 | Covering eyes with hair is prohibited. |
| EyeLeftCoveredWithHair | Whether the left eye is covered with hair. | 0, 0.5 | Covering eyes with hair is prohibited. |
| OffGaze | Whether the person is not looking directly at the camera. | 0, 0.5 | The person should be looking directly at the camera. |
Shadows and lightning
| Name | Description | Recommended range | ICAO standard |
|---|---|---|---|
| TooDark | Whether the photo is too dark. | 0, 0.38 | Low-light photos are prohibited. |
| TooLight | Whether the photo is overexposed. | 0, 0.5 | Overexposed photos are prohibited. |
| FaceGlare | Whether there is glare on the face. | 0, 0.01 | Glare on the face is not allowed. |
| ShadowsOnFace | Whether there are shadows on the face. | 0, 0.5 | The face should be evenly lit. |
Pose and expression
| Name | Description | Recommended range | ICAO standard |
|---|---|---|---|
| ShouldersPose | Checks the symmetry of the shoulders, returns 1 for absolutely symmetrical shoulders. | 0.6, 1 | Shoulders should be symmetrical. |
| ExpressionLevel | Checks the presence of any emotional facial expression. | 0, 0.84 | Any facial expressions are prohibited, raised eyebrows are prohibited. |
| MouthOpen | Whether the mouth is open. | 0, 0.5 | The mouth should be closed. |
| Smile | Whether the person smiles. | 0, 0.5 | A person should not smile. |
Head occlusion
| Name | Description | Recommended range | ICAO standard |
|---|---|---|---|
| DarkGlasses | Whether the person wears dark glasses. | 0, 0.5 | No dark glasses are allowed. |
| ReflectionOnGlasses | Whether there are reflections on glasses. In the current release, always returns true. Will be developed in the coming releases. |
0, 0.5 | Reflections of objects and glare on glasses are prohibited. |
| FramesTooHeavy | Whether the glasses frames do not obscure eye details and the irises of both eyes are visible. | 0, 6 | Frames should not be thicker than 5% of the IED (typically 3-4 mm). |
| FaceOccluded | Whether the face is visible and not occluded. | 0, 0.5 | The face should be totally visible and not occluded or covered. |
| HeadCovering | Whether there is any head coverage other than religious headwear. | 0, 0.5 | Hats other than religious headwear are not allowed. |
| ForeheadCovering | Whether the forehead is covered. | 0, 0.5 | If the forehead is covered by the hairstyle, it can’t be evaluated. |
| StrongMakeup | Whether the makeup is too strong. In the current release, always returns true. Will be developed in the coming releases. |
0, 0.5 | Only typical everyday makeup is allowed. |
| Headphones | Whether the person is wearing headphones. | 0, 0.5 | Headphones are not allowed for passport photos. |
| MedicalMask | Whether the person is wearing a medical mask. | 0, 0.5 | Medical mask is not allowed for passport photos. |
Background
| Name | Description | Recommended range | ICAO standard |
|---|---|---|---|
| BackgroundUniformity | Checks uniformity of the portrait background. | 0.9, 1 | A typical background for the scene is grey with a plain, dull flat surface. Plain light coloured backgrounds such as light blue or white may be used as long as there is sufficient distinction between the face/hair area and the background. |
| ShadowsOnBackground | Whether there are shadows on the portrait background. | 0.9, 1 | Photos with shadows on the background are invalid. |
| OtherFaces | The number of faces on the photo. | 1 | No more than one face on the photo is allowed. |
| BackgroundColorMatch | Whether the background color matches the required hue (that is set in backgroundMatchColor). |
0.8, 1 | For some visas, the portrait background must be strictly white. |