Face Recognition Method Enroll

Performs a biometric enrollment (or training) of a single class with one or more images containing the face of the person to enroll. With this method a new biometric face template is created and stored. It can be used to create a completely new biometric template, to update an existing template or even to upgrade an existing template to a newer encoder version.

The created template is persisted to a storage, addressed by its Biometric Class ID (BCID). Beside of a compact version of the biometric template (used for face matching purposes), an enhanced version of the template is stored. The enhanced version contains at least all calculated face features (standard template) and optionally also the thumbnails of the enrolled faces (full version), which are needed for upgrades to newer encoder versions. The enhanced template versions are always encrypted, the compact version is encrypted if required by the configuration of the client (slows down search requests).

Service method definition

The Enroll API is defined as a unary RPC:

rpc Enroll (FaceEnrollmentRequest) returns (FaceEnrollmentResponse);

message FaceEnrollmentRequest {
    int64 classId = 1;
    repeated ImageData images = 2;
}

message FaceEnrollmentResponse {
    JobStatus status = 1;
    repeated JobError errors = 2;
    repeated ImageProperties image_properties = 3;
    EnrollmentAction performed_action = 4;
    int32 enrolled_images = 5;
    FaceTemplateStatus template_status = 6;

    enum EnrollmentAction {
        NONE = 0;
        NEW_TEMPLATE_CREATED = 1;
        TEMPLATE_UPDATED = 2;
        TEMPLATE_UPGRADED = 3;
        ENROLLMENT_FAILED = -1;
    }
}

Request

The FaceEnrollmentRequest message has the fields as follows:

classId

The unique class ID of the enrolled person. The class ID is a 64-bit positive number, managed by the client.

This ID, together with a storage name and a partition ID will make up the Biometric Class ID (BCID), which is used to address the created biometric template.

images

A list of one or more ImageData messages containing the images with the faces to enroll. Each image should contain a single face and all faces, of course, should belong to the same person. Images with no face or multiple faces on it will be ignored.

An empty list is allowed. In this case this method simply returns the status of an existing template and, if possible, upgrades an existing template to a newer encoder version.

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 FaceEnrollmentResponse 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. When errors are reported, the performed_action field will typically be set to ENROLLMENT_FAILED.

image_properties

The calculated image properties for each of the provided images in the given order.

performed_action

The actual action performed. This is a value out of the EnrollmentAction enumeration:

NONE

No action was performed. This typically happens, if no input images have been provided and there is no existing template that needs to be upgraded.

NEW_TEMPLATE_CREATED

A new template has been created from the provided input images.

TEMPLATE_UPDATED

An existing template has been updated. The features of the provided images have been added to the existing template to create a new template.

TEMPLATE_UPGRADED

A new template has been created from the provided input images and the enrollment images of an existing old version template, i.e. an existing template has been upgraded to the current encoder version.

ENROLLMENT_FAILED

The enrollment process generated some errors (see the errors field) and no action was performed.

enrolled_images

Number of newly enrolled images. There might be less images enrolled than have been delivered due to problems extracting the needed face features.

template_status

The FaceTemplateStatus of the generated (or existing) face template without any face thumbnails.

Remarks

Please note, that even if a biometric face template has been enrolled successfully, not all images and found faces may have considered, as no face or multiple faces may have been found on an image, or feature extraction failed. Refer to the image_properties (especially the quality_assessments field) to find out more.

BWS Errors

In case that the performed_action field is set to ENROLLMENT_FAILED, at least one of the following errors is reported in the errors field:

NoSuitableFaceImage

We could not find a single suitable face in any of the provided images to perform a face enrollment. All images either show no face or multiple faces. Please refer to the quality check results of the images, which should contain failed results for the performed quality checks:

• FaceFound: Check for at least one found face.
• SingleFaceOnImage: Check for exactly one found face.

NoFeatureVectors

We could not extract at least a single feature vector from the provided images to perform a face enrollment. Please refer to the quality check results of the images, which should contain failed results for the performed quality checks:

• FaceFound: Check for at least one found face.
• SingleFaceOnImage: Check for exactly one found face.
• FaceFeaturesAvailable: Check for extractable face features.

DifferentFeatureVersions

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

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 one of the provided input images, 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.

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 Enroll gRPC API using a classId and a list of images.

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  new FaceEnrollmentRequest { ClassId = options.ClassId };
    foreach (string file in options.Files)
    {
        request.LiveImages.Add(new ImageData { Image = ByteString.CopyFrom(File.ReadAllBytes(file)) });
    }
    using var call = client.EnrollAsync(request);
    FaceEnrollmentResponse response = await call.ResponseAsync.ConfigureAwait(false);
    // ...
    Console.WriteLine($"Performed action   : {response.PerformedAction}");
    Console.WriteLine($"Template Class-ID  : {response.TemplateStatus.ClassId}");
    Console.WriteLine($"Template available : {response.TemplateStatus.Available}");
    Console.WriteLine($"Template enrolled  : {response.TemplateStatus.Enrolled}");
}
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.FaceEnrollmentRequest;
import com.bioid.services.Facerecognition.FaceEnrollmentResponse;

public void faceEnrollAsync(byte[] image1, byte[] image2, long classId){
    ManagedChannel grpcChannel = null;
    try {
        String jwtToken = generateToken(options.clientId, option.secretKey, options.expireMinutes);
        grpcChannel = createAuthenticatedChannel(option.host, jwtToken);
     
        var bwsClient = FaceRecognitionGrpc.newStub(grpcChannel);
        var enrollRequest = FaceEnrollmentRequest.newBuilder()
                 // The unique class ID of the enrolled person
                 // You should set your ClassID
                .setClassId(classId)
                .addImages(ImageData.newBuilder().setImage(ByteString.copyFrom(image1)).build())
                .addImages(ImageData.newBuilder().setImage(ByteString.copyFrom(image2)).build())
                .build();
                
        CompletableFuture <FaceEnrollmentResponse> enrollResult = new CompletableFuture <>();
        bwsClient.enroll(enrollRequest, new StreamObserver <FaceEnrollmentResponse>() {
            @Override
            public void onNext(FaceEnrollmentResponse value) {
                enrollResult.complete(value);
            }

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

            @Override
            public void onCompleted() {
            }
        });
        var enrollResponse = enrollResult.get();
        System.out.println("Performed action   : " + enrollResponse.getPerformedAction().toString());
        System.out.println("Template Class-ID  : " + enrollResponse.getTemplateStatus().getClassId());
        System.out.println("Template available : " + enrollResponse.getTemplateStatus().getAvailable());
    } 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.FaceEnrollmentRequest()
    for img_file in args.images:
        with open(img_file, 'rb') as f:
            request.images.add(image=f.read())
    try:
        # The unique class ID of the enrolled person
        # You should set your ClassID
        request.classId = args.class_id
        response = stub.Enroll(request)
        print(response)
    except grpc.RpcError as rpc_error:
        print("Received error: ", rpc_error)