gRPC Method FaceImageQuality

Performs face image quality measurements by calling into the Open Source Face Image Quality (OFIQ) library. With this library we currently perform these 28 quality measures.
Please note that this library is subject of the OFIQ License

Service method definition

The FaceImageQuality API is defined as a unary RPC:

rpc FaceImageQuality (FaceImageQualityRequest) returns (FaceImageQualityResponse);

message FaceImageQualityRequest {
    bytes image = 1;
}
message FaceImageQualityResponse {
    JobStatus status = 1;
    repeated JobError errors = 2;
    repeated QualityMeasurement quality_measurements = 3;
}
message QualityMeasurement {
    QualityMeasure measure = 1;
    double raw_value = 2;
    int32 scalar_score = 3;
}
enum QualityMeasure {
    // ... see faceimagequality.proto
}

Request

The FaceImageQualityRequest message has a single field:

image

The binary input image data.

The maximum API request size is 50 MB.

Request Headers

This API requires a valid JWT in the Authorization request header and accepts an optional reference number.

Authorization	Required Bearer authentication. Please refer to BWS API Authentication for a description of how to provide a valid JWT here.
Reference-Number	Optional, client specific reference number, which will be added to the BWS bookkeeping as well as to the response header. You typically use this reference to link the resulting BWS bookkeeping entries with your logs.

Response

On success the API returns a FaceImageQualityResponse message with the fields as follows:

status

The status of the BWS job that processed the request. Please note that errors may have occurred, even if the job was completed successfully.

errors

A list of errors that might have occurred while the request has been processed.

quality_measurements

The list of performed quality measurements. Each of the measurements contains the fields:

measure

The quality measure performed. One of well known quality assessment algorithm identifiers listed in the QualityMeasure enum, see protobuf.

raw_value

The raw score as computed by the quality measure implementation.

scalar_score

A scalar value from the interval [0, 100] computed from the raw score. Higher values mean better quality. A score of 100 indicates optimal quality, while 0 indicates a severe defect.

BWS Errors

In case none or not all of the quality measurements have benn calculated, this API might report one of the following OFIQ return codes in the errors field:

FaceDetectionError

Unable to detect a face in the image.

FaceLandmarkExtractionError

Unable to extract landmarks from face.

FaceOcclusionSegmentationError

Unable to extract occlusion segments from face.

FaceParsingError

Unable to parse face.

UnknownError

An unknown or unspecified error occurred.

QualityAssessmentError

Failure to generate a quality score on the input image.

gRPC Errors

Beside of the success return status code OK (0), this call might also return one of the following gRPC error status codes to indicate an error:

Cancelled (1)

Client application cancelled the request.

Unknown (2)

Server experienced some unexpected behaviour.

InvalidArgument (3)

Client specified an invalid argument: The service cannot decode the provided input data, e.g. because the format cannot be detected or the image is too big.

DeadlineExceeded (4)

Deadline expired before operation could complete.

Internal (13)

Internal errors indicate that critical system invariants have been violated. If you encounter one of these errors, it means something is severely wrong. These errors can occur due to an invalid service configuration, a misconfigured client, or an unexpected exception.

Unavailable (14)

The service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff.

Unauthenticated (16)

The request does not have valid authentication credentials for the operation.

Response Headers/Trailers

All successful BWS gRPC calls return a response header and a response trailer containing additional information about the request:

Response Header
jobid	The Job-ID (a GUID) that has been assigned to this BWS call.
bws-version	The version of the BWS gRPC service.
reference-number	An optional reference number as provided in the request header.
date	The timestamp when the request has been received at the server.
...	Other headers that might have been added by the server (NGINX, Kestrel, ...) that was handling the request.
Response Trailer
response-time-ms	The timespan im milliseconds the request spent at the BWS service.
...	Other trailers, like exception trailers, which are added by the gRPC framework in case an RPC exception occurred.