Face Recognition Method Verify

Performs a one-to-one comparison of the uploaded face image with a stored biometric template in order to verify whether the individual is the person he or she claims to be.

Service method definition

The Verify API is defined as a unary RPC:

rpc Verify (FaceVerificationRequest) returns (FaceVerificationResponse);

message FaceVerificationRequest {
    int64 classId = 1;
    ImageData image = 2;
}

message FaceVerificationResponse {
    JobStatus status = 1;
    repeated JobError errors = 2;
    ImageProperties image_properties = 3;
    bool verified = 4;
    double score = 5;
}

Request

The FaceVerificationRequest message has the fields as follows:

classId

The unique class ID of the person to verify. The class ID is a 64-bit positive number, managed by the client. This ID, together with the configured storage name and a partition ID will make up the Biometric Class ID (BCID), which is used to load the biometric face template to compare the given image with.

image

An ImageData messages containing the facial image to verify.

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.

Response

On success the API returns a FaceVerificationResponse message:

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.

image_properties

The calculated image properties for the provided image.

verified

Verification decision made by BWS. Set to true, when the person specified by the given class ID could have been verified successfully with the given sample; false otherwise, or when errors occurred (see errors for details).

score

The calculated verification score (a value between 0.0 and 1.0) that led to the verified decision. The higher the score, the more likely the face in the image and the template referenced by the class ID belong to the same person.

Although we use a normed score here, this score is based on the model used to create the referenced biometric template. Therefore we advise against using it for decision-making.

BWS Errors

In case that the verified field is set to false, some errors might have been reported:

FaceNotFound

No suitable face was found in the provided image.

MultipleFacesFound

More than one face has been found in the provided image.

ThumbnailExtractionFailed

The found face could not be extracted, typically because it is too close to the edge.

DifferentFeatureVersions

Internal: A mixup of different face feature vector versions was encountered.

gRPC Errors

Besides 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 image, e.g. because the format cannot be detected or the image is too big.
• A positive number is required for the class ID.

DeadlineExceeded (4)

Deadline expired before operation could complete.

NotFound (5)

A biometric face template for specified class ID does not exist.

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:

Example:

Here is a short example of how to call into the Verify gRPC API using a classId and a image.

Please refer to BWS API Authentication for a description of the methods related to authentication.

try
{
    using GrpcChannel channel = CreateAuthenticatedChannel(new Uri(options.Host), GenerateToken(options.ClientId, options.Key));
    var client = new BioIDWebService.BioIDWebServiceClient(channel);
    var request = new FaceVerificationRequest
    {
        Image = new ImageData { Image = ByteString.CopyFrom(File.ReadAllBytes(options.files[0].FullName)) },
        ClassId = options.classId
    };
    using var call = client.VerifyAsync(request);
   FaceVerificationResponse response = await call.ResponseAsync.ConfigureAwait(false);
    // ...
    Console.WriteLine($"Verified: {response.Verified} - Score:{response.Score}");
}
catch (RpcException ex)
{
    Console.Error.WriteLine($"gRPC error from calling service: {ex.Status.StatusCode} - '{ex.Status.Detail}'");
}

import java.util.concurrent.CompletableFuture;
import com.bioid.services.BioIDWebServiceGrpc;
import com.bioid.services.BioIDWebServiceGrpc.BioIDWebServiceStub;
import com.bioid.services.Bws.ImageData;
import com.google.protobuf.ByteString;
import io.grpc.ManagedChannel;
import io.grpc.StatusRuntimeException;
import io.grpc.stub.StreamObserver;
import com.bioid.services.Facerecognition.FaceVerificationRequest;
import com.bioid.services.Facerecognition.FaceVerificationResponse;

public void verifyAsync(byte[] image, long classId){
    ManagedChannel grpcChannel = null;
    try {
        String jwtToken = generateToken(ptions.clientId, option.secretKey, options.expireMinutes);
        grpcChannel = createAuthenticatedChannel(option.host, jwtToken);
        
        var bwsClient = FaceRecognitionGrpc.newStub(grpcChannel);
        var verifyRequest = FaceVerificationRequest.newBuilder()
                // The unique class ID of the enrolled person
                // You should set your ClassID
                .setClassId(classId)
                .setImage(ImageData.newBuilder().setImage(ByteString.copyFrom(image)).build())
                .build();

            CompletableFuture <FaceVerificationResponse> verifyResult = new CompletableFuture <>();
            bwsClient.verify(verifyRequest, new StreamObserver <FaceVerificationResponse>() {
                @Override
                public void onNext(FaceVerificationResponse value) {
                    verifyResult.complete(value);
                }

                @Override
                public void onError(Throwable t) {
                    verifyResult.completeExceptionally(t);
                }

                @Override
                public void onCompleted() {
            }
        });
        var verifyResponse = verifyResult.get();
        System.out.printf("Verified: %s - Score: %f", verifyResponse.getVerified(), verifyResponse.getScore());
    } catch (Exception ex) {
        System.err.printf("Error processing images: " + ex.getMessage());
    }finally {
        if(grpcChannel != null) {
            grpcChannel.shutdown();
        }
    }
}

import grpc
import facerecognition_pb2
import facerecognition_pb2_grpc

token = generate_token(args.clientid, args.key, arg.expireMinutes)
with create_authenticated_channel(args.host,token) as channel:
    stub = facerecognition_pb2_grpc.FaceRecognitionStub(channel)

    request = facerecognition_pb2.FaceVerificationRequest()
    with open(args.image, 'rb') as f:
        request.image.image= f.read()
    try:
        # The unique class ID of the enrolled person
        # You should set your ClassID
        request.classId = args.classs_id
        response = stub.Verify(request)
        print(response)
    except grpc.RpcError as rpc_error:
        print("Received error: ", rpc_error)