Skip to content

Face Image Quality Assessment

(The feature is coming soon in the next release)

Overview

To enable the portrait quality assessment, add the quality parameter of the detect command and set the required characteristics.

Face image quality assessment comes in handy if you need to check whether a photo portrait meets certain conditions. For example, by your requirements, a person on a picture should not smile and wear glasses and should look directly at the camera, the image width to height should be of certain proportios, etc. The feature is perfect for checking photo validity for visas and offical documents.

You can select the scenario according to which the face image quality assessment will be performed: ICAO or Schengen Visa.

If no scenario is set, the default settings for the facial image quality check are based on the ICAO Standard.

Request

In the config field, you can set the characteristics that should be checked. You are free to define any valid range for each characteristic.

If align is set, Base64 of the aligned and cropped portrait is returned in the crop field. If background is set, it is applied to the cropped image.

If align is not set, the image is not cropped and background (if set) is applied to the original image. In this case, all the checks are performed on the uncropped image with changed background. However, the very image with changed background is not returned.

If the quality field is not set, the facial image quality check is not performed.

Parameters

└── quality
|   └── align
|   |   └── type
|   |   └── pad
|   |   └── cropSize
|   └── background
|   └── scenario
|   └── config
|       └── name
|       └── range
Parameter Description
align If set, Base64 of an aligned and cropped portrait is returned in the crop field. Alignment is performed according to type. If a head on the original image is tilted, for the returned portrait it is aligned in a straight vertical line.

align includes type, pad, and cropSize.
type The aspect ratio according to which alignment is performed. See the FaceImageQualityAlignType enum.
pad When an image is aligned by type, it's original size may be insufficient, and in this case it needs to be supplemented, "padded". pad sets the RGB value for the color that will be used for such a supplement.
cropSize The resize value in case type matches this value. If it doesn't match, no resize is performed.
background The RGB value for the background color: the silhouette of a person is cut out and the background is filled with this color. If align is set, this option is applied to the cropped image; if align is not set, the option is applied to the original image.
scenario The check scenario: ICAO or Schengen Visa. If applied, the settings are set automatically for the face image quality assessment.
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.

If scenario is set and some parameters in the config are added, these separately indicated parameters have a higher priority. So, if needed, you can select a scenario but change a couple of parameters.
name The name of the characteristic.
range The range of applicable values for this characteristic. If the returned in the response value fits the range, the value is identified as compliant with the requirements.

FaceImageQualityAlignType enum

enum FaceImageQualityAlignType
{
    QUALITY_ALIGN_3x4 = 0,
    QUALITY_ALIGN_4x5 = 1,
    QUALITY_ALIGN_2x3 = 2,
    QUALITY_ALIGN_1x1 = 3,
    QUALITY_ALIGN_7x9 = 4   // 3.5 x 4.5 
};
FaceImageQualityAlignType Meaning
QUALITY_ALIGN_3x4 = 0 The aspect ratio of the required pattern is 3x4.
QUALITY_ALIGN_4x5 = 1 The aspect ratio of the required pattern is 4x5.
QUALITY_ALIGN_2x3 = 2 The aspect ratio of the required pattern is 2x3.
QUALITY_ALIGN_1x1 = 3 The aspect ratio of the required pattern is 1x1.
QUALITY_ALIGN_7x9 = 4 The aspect ratio of the required pattern is 3.5x4.5.

Code Samples

  • The assessment is performed by the default settings: no alignment, background preserved, no resize, the configuration includes all the characteristics based on the ICAO standard:
"quality": {}
  • The facial image is aligned and cropped, background preserved; the configuration includes all the characteristics based on the ICAO standard:
"quality": {
    "align": {}
}
  • The facial image is aligned and cropped, background preserved; the dimensions ratio to the height of the required pattern is 3x4; the configuration includes all the characteristics based on the ICAO standard:
"quality": {
    "align": {
        "type": 0, 
    }
}
  • The facial image is aligned and cropped, background preserved; the dimensions ratio to the height of the required pattern is 4x5; the color for padding the image for alignment is gray (RGB: 128, 128, 128); the configuration includes all the characteristics based on the ICAO standard:
"quality": {
    "align": {
        "type": 1, 
        "pad": [128, 128, 128]
    }       
}
  • The facial image is aligned and cropped, the dimensions ratio to the height of the required pattern is 4x5; the color for padding the image for alignment is gray (RGB: 128, 128, 128); background removed and filled in with grey color (RGB: 128, 128, 128); the configuration includes all the characteristics based on the ICAO standard:
"quality": {
    "align": {
        "type": 1,
        "pad": [128, 128, 128]
    },
    "background": [128, 128, 128],
}
  • The facial image is aligned and cropped, the dimensions ratio to the height of the required pattern is 4x5; the color for padding the image for alignment is gray (RGB: 128, 128, 128); background removed and filled in with grey color (RGB: 128, 128, 128); the configuration includes only the indicated characteristics with the indicated ranges:
"quality": {
    "align": {
        "type": 1,
        "pad": [128, 128, 128]
    },
    "background": [128, 128, 128],
    "config": [
        {
        "name": "Roll",
        "range": [-5.0, 5.0],
        }
    ]
}

Response

The response returns the list of characteristics with a processing status for each, see the FaceImageQualityStatus enum. The list of returned characteristics is defined by the set configuration. If image alignment (align) was set, an aligned and cropped portrait is returned in the crop field.

Parameters

└── detections
|   └── crop
|   └── quality
|       └── compliant
|       └── aligned
|       └── resized
|       └── score
|       └── nonCompliant
|       └── detailsGroups
|       |   └── groupId
|       |   └── name
|       |   └── totalCount
|       |   └── complianCount
|       └── details
|       |   └── name
|       |   └── range
|       |   └── status
|       |   └── value
Parameter Description
crop Base64 of the aligned and cropped portrait. Returned if align is set.
quality Field for checking the portrait quality. If it is not mentioned, no quality check is performed.
compliant Returns the portrait quality assessment result.

True if all the checked characteristics returned values that fit into the range. Otherwise, false.
aligned Returns true if alignment was performed. Otherwise, false.
resized Returns true if the image was resized according to the set dimensions. Otherwise, false.
score Returns the estimated portrait quality assessment result, a number from 0 to 1, where 1 is for absolute compliance.
nonCompliant The array of all the non-compliant assessment characteristics.
detailsGroups The array of the assessment results for each group of characteristics. Includes groupId, name, total, complianCount.
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.
complianCount The number of compliant characteristics in the group.
details The array of the assessment characteristics that were set in the request. Includes name, range, status, value.
name The name of the characteristic.
range The range of set values for this characteristic.
status The assessment status of the characteristic, see FaceImageQualityStatus enum.
value The assessed value for the characteristic.

FaceImageQualityGroups enum

enum FaceImageQualityGroups
{   
   ImageСharacteristics = 1,
   HeadSizeAndPosition = 2,
   FaceQuality = 3,
   EyesCharacteristics = 4,
   ShadowsAndLightning = 5,
   PoseAndExpression = 6,
   HeadOcclusion = 7,
   Background = 8,
};
FaceImageQualityGroups Meaning
ImageСharacteristics = 1 The Image characteristics group includes width, height, width to height proportions, the image RGB channels number, and padding ratio.
HeadSizeAndPosition = 2 The Head size and position group includes the position of the "middle point" relative to the width and height of the image, the head width to the image width and height ratio, inter-eye distance, yaw, pitch, roll.
FaceQuality = 3 The Face image quality group includes blur and noise levels, unnatural skin tone, and face dynamic range checks.
EyesCharacteristics = 4 The Eyes characteristics group checks eyes closure, occlusion, hair coverage, red eye effect, and whether a person is looking directly at the camera.
ShadowsAndLightning = 5 The Shadows and lightning characteristics group checks whether a photo is too dark or overexposed, if there are glares or shadows on the face.
PoseAndExpression = 6 The Pose and expression characteristics group checks the shoulders pose, face expression, whether there is an open mouth or smile.
HeadOcclusion = 7 The Head occlusion group includes checks of glasses, face occlusion, and head coverage.
Background = 8 The Background characteristics group checks the background uniformity, shadows on background, and other faces presence on the picture.

FaceImageQualityStatus enum

enum FaceImageQualityStatus
{   
   QUALITY_STATUS_FALSE = 0,
   QUALITY_STATUS_TRUE = 1,
   QUALITY_STATUS_UNDETERMINED = 2,
};
eFaceQualityStatus Meaning
QUALITY_STATUS_FALSE = 0 The characteristic is defined but is out of the range of set values.
QUALITY_STATUS_TRUE = 1 The characteristic is defined and fits the range of set values.
QUALITY_STATUS_UNDETERMINED = 2 The characteristic is not defined.

Response Example

{
 "code": 0,
 "msg": "FACER_OK",
 "results": {
   "detections": [
     {
      "crop": "base64image",
      "quality":
      {
        "compliant": false,
        "aligned": true,
        "resized": true,
        "score": 0.85,
        "nonCompliant": ["ImageWidthToHeight", "Yaw"]
        "detailsGroups": [
          {
            "groupId": 1,
            "name": "ImageCharacteristics",
            "total": 5,
            "compliant": 4
          }
        ]
        "details": [
        {
         "groupId": 0
         "name": "Yaw",
         "range": [-5.0, 5.0],
         "status": 0,
         "value": 5.9513092041015625
        },
        {...}
     }
  ]
}  

Characteristics

The characteristics are divided into groups, information on each group is returned in the detailsGroups field.

Note

You can define any valid range for each characteristic.

Image characteristics

Name Description ICAO standard
ImageWidth The image width, pixels. 1200 px
ImageHeight The image height, pixels. 1600 px
ImageWidthToHeight The image width to height proportion. 0.74, 0.8
ImageChannelsNumber The image RGB channels number. 3
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.

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 centres) 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 centres) 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 centres 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 coverange 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. 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.

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. 0.8, 1 For some visas, the portrait background must be strictly white.