VFace ISO Quality Measures | VeridiumId Documentation

VFace supports computation of a subset of face quality measures conforming to ISO standard ISO/IEC 29794-5. Values are computed for the largest face in an image, referred to as the main face. Measures are as follows:

Measure	Index	Description of the raw value	Semantics	Value Range
Unified Quality Score	0	UNSUPPORTED
Background Uniformity	1	Average of background gradients calculated on the background using face parsing segmentation.	Lower-is-better.	[0, 100]
Illumination Uniformity	2	Sum of the overlapping areas of the histograms from the left and right sides of the face.	Higher-is-better.	[0, 100]
Luminance Mean	3	Luminance of the face, or how well it the face is.	Higher-is-better.	[0,100]
Luminance Variance	4	How much luminance varies within the face.	Lower-is-better.	[0,100]
Under Exposure Prevention	5	Proportion of face pixels with low luminance values.	Lower-is-better.	[0,100]
Over Exposure Prevention	6	Proportion of face pixels with high luminance values.	Lower-is-better.	[0,100]
Dynamic Range	7	The spread of spread of luminance values.	Higher-is-better.	[0,100]
Sharpness	8	UNSUPPORTED
Compression Artifacts	9	UNSUPPORTED Presence of compression artifacts in an image.	Lower-is-better.	[0, 100]
Natural Colour	10	White balance based on skin tone, indicating the naturalness of the skin tone.	Lower-is-better.	[0,100]
Single Face Present	11	A value of 0 indicates no faces were detected, 100 if exactly one face is detected. Intermediate values corresponding to 2 or more faces, with higher values indicating a relatively larger main face.	Higher-is-better.	[0,100]
Eyes Open	12	Degree of eye openness, assessing whether the eyes are fully open, pupils are visible or partially closed.	Higher-is-better.	[0,100]
Mouth Closed	13	Degree of mouth openness, assessing whether the mouth is closed or open.	Lower-is-better.	[0,100]
Eyes Visible	14	UNSUPPORTED
Mouth Occlusion Prevention	15	UNSUPPORTED Fraction of the mouth that is covered or obstructed.	Lower-is-better.	[0, 100]
Face Occlusion Prevention	16	UNSUPPORTED Fraction of the face that is covered or obstructed.	Lower-is-better.	[0, 100]
Inter Eye Distance	17	Distance in pixels between the two eyes, but corrected for yaw angle.	Higher-is-better.	[0,100]
Head Size	18	Head size relative to image height. Very low values indicate poor composition, while very high values indicate cropping.	Optimal is 100	[0,200]
Leftward Crop Of The Face Image	19	Higher values indicates it is less likely that the left of the face is cropped.	Higher-is-better.	[0,100]
Rightward Crop Of The FaceImage	20	Higher values indicates it is less likely that the right of the face is cropped.	Higher-is-better.	[0,100]
Downward Crop Of The FaceImage	21	Higher values indicates it is less likely that the bottom of the face is cropped.	Higher-is-better.	[0,100]
Upward Crop Of The FaceImage	22	Higher values indicates it is less likely that the top of the face is cropped.	Higher-is-better.	[0,100]
Head Pose Yaw	23	Degree of side-to-side head rotation relative to the optical axis. Lower values indicate greater rotation of the face in the yaw axis.	Higher-is-better.	[0,100]
Head Pose Pitch	24	Degree of up-and-down head rotation, where the head moves around the side-to-side axis (chin up or down). Lower values indicate greater rotation of the face in the pitch axis.	Higher-is-better.	[0,100]
Head Pose Roll	25	Degree of tilting of the head, where the head rotates around the front-to-back axis (ear to ear). Lower values indicate greater rotation of the face in the roll axis.	Higher-is-better.	[0,100]
Expression Neutrality	26	UNSUPPORTED
No Head Coverings	27	UNSUPPORTED Proportion of pixels of the head that represent headwear or clothing.	Lower-is-better.	[0, 100]

An image can be assessed for face quality on device (Android, iOS), or via the Biomatch C API.

Standalone Biomatch API

C API for computing face quality measures from an image. Exposed alongside the Biomatch API in libvface_biomatch.so. See biomatch_extra_api.h in your code distribution.

Function signature:

int vface_assess_image_quality(const void* image_data, size_t image_data_size, int flags,
                               double** out_quality_vector, size_t* out_quality_vector_size,
                               void* (*allocator)(size_t));

Parameters

image_data, image_data_size - pointer to and size of (respectively) a byte array containing a colour image encoded as PNG or JPEG.
flags - Set to 0 for ISO standard quality measures
out_quality_vector, out_quality_vector_size - if the operation is successful, the values pointed to by these parameters are filled in with a pointer to, and the size of, a double array containing the output measures. The array is allocated with the allocator function passed to the allocator parameter, and ownership is passed to the caller.
allocator - an allocation function. Defaults to malloc if a null pointer is passed.

Quality Vector

The output is a flattened double vector containing 3 values for each of the 28 measures:

Raw score - Measurement result prior to normalisation to ISO stated ranges.
Mapped score - Normalised score conforming to ISO 29794-5
Computation result, where 0 = SUCCESS, -1 = FAIL_COMPUTE, -2 = FAIL_NOT_SUPPORTED

Total length is 84, with quality measures ordered as in the table above. For example, to access the mapped score for measure4-Luminance Varianceuse an index of (4 x 3)+1.

Return Value

Return code of 0 = SUCCESS. Non zero values are errors, as described here.

Android

Quality values can be computed from an Android Bitmap using the following public static method:

public static Pair<Integer, VFaceQuality> assessImageQuality(Bitmap image)
, where image is a Bitmap object. Returns a Pair containing a VFaceQuality object that holds quality measures and a face box (a Rect indicating the face location), and a success code.

For example, computing quality on a image resource:

Java

private void qualityFromImage(){
    Bitmap image = BitmapFactory.decodeResource(getResources(), R.drawable.subject_001);
    Pair<Integer, VFaceQuality> result = CustomVFaceActivity.assessImageQuality(image);
    final int result_code = result.first;
    final VFaceQuality quality = result.second;

    if (result_code == 0) {
        // Success, print out the value for mean luminance
        final int luminance = quality.getMeasure(VFaceQuality.QualityMeasure.LuminanceMean);
        ToastHelper.showMessage(MainActivity.this, "Quality, mean luminance: " + luminance);
    } else {
        ToastHelper.showMessage(MainActivity.this, "Failed to assess quality: " + result_code);
    }
}

A VFaceQuality object has the following public access:

`public Rect getFaceBox()`	Access the face location.
`public int[] getAllMeasures()`	Array of all quality measures.
`public int getMeasure(QualityMeasure m)`	Access a measurement using enum `VFaceQuality.QualityMeasure`

Any unsupported quality measure will have a value of VFaceQuality.UNSUPPORTED.

iOS

Quality values can be computed from an CGImage. Fetch the enroler and call the assessQuality() method:

func assessQuality(with image: CGImage, completion: ((VeridiumVFaceImageExtractResult, VeridiumVFaceQuality?) -> Void)?)

, where completion is method receiving a enum VeridiumVFaceImageExtractResult code and a VeridiumVFaceQualityobject that holds quality measures and a face box (a Rect indicating the face location). For example:

Swift

let vface_enroller = VeridiumSDK.shared.enrollerVFace!

vface_enroller.assessQuality(with: image, withCompletion: {qualityResult, quality in
            if quality != nil {
                print(quality!.getMeasure(VeridiumVFaceQualityMeasure.DYNAMIC_RANGE))
                VeridiumUtils.alert("Quality from image success", title: "Success")
            }else{
                switch qualityResult {
                case VeridiumVFaceImageExtractResult.NO_FACE_FOUND:
                    VeridiumUtils.alert("Could not assess quality. Pick another image", title:"No Face");
                    return
                default:
                    VeridiumUtils.alert("Could not assess quality. Pick another image", title: "Failed")
                    return
                }
            }
        })

A VeridiumVFaceQuality object has the following access:

`(CGRect)getFaceBox`	Access the face location.
`(NSArray<NSNumber > )getAllMeasures`	Array of all quality measures.
`(NSInteger) getMeasure:(VeridiumVFaceQualityMeasure) m`	Access a measurement using enum

Any unsupported quality measure will have a value of VeridiumVFaceQualityMeasureUNSUPPORTED.