Skip to content

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:

  • QualityFull checks all the available quality characteristics.
  • QualityICAO checks the quality characteristics based on the ICAO standard.
  • QualityVisaSchengen checks the quality characteristics based on the Schengen visa standard.
  • QualityVisaUSA checks 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 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 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.