Performs liveness detection on one or two live images. Depending on the number of live images and the tags provided in the call, different versions of our liveness detection will be executed:
One image: Only passive liveness detection will be performed. Due to the limitation to a single image, only the texture based liveness detection can be used to make a decision.
Two images: Passive and active liveness detection will be performed. Beside of the texture based liveness detection on each of the provided images a motion based 3D detection on each two consecutive images is executed. All decisions must indicate a live person to finally declare the entire call as live.
Two images with tagged second image: Passive and active liveness detection will be performed. Additionally a challenge-response mechanism is applied. As we have a motion direction calculated for the face found in the second image, we can check whether this is the same direction as demanded by the tags, i.e. whether the head moved up, down, left or right as requested. Also refer to the Liveness Detection Modes.
The LivenessDetection API is defined as a unary RPC:
rpc LivenessDetection (LivenessDetectionRequest) returns (LivenessDetectionResponse);
message LivenessDetectionRequest {
repeated ImageData live_images = 1;
}
message LivenessDetectionResponse {
JobStatus status = 1;
repeated JobError errors = 2;
repeated ImageProperties image_properties = 3;
bool live = 4;
double liveness_score = 5;
}
The LivenessDetectionRequest message has a single field:
live_imagesThis 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. |
On success the API returns a LivenessDetectionResponse message with the fields as follows:
statuserrorsimage_propertieslivetrue, the provided images are supposed to be recorded from a live person. No errors are reported in this case.
When this field is set to false, there is at least one error reported that explains, why the provided images are not supposed to be recorded from a live person.
liveness_scoreAn informative liveness score (a value between 0.0 and 1.0) that reflects the confidence level of the live decision. The higher the score, the more likely the person is a live person. If this score is exactly 0.0, it has not been calculated and an error has been be reported.
In case that the live field is set to false, at least one of the following errors is reported in the errors field:
FullyVisibleFace quality check results.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:
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. |
Here is a short example of how to call into the LivenessDetection gRPC API using live images loaded from files.
Please refer to BWS API Authentication for a description of the methods CreateAuthenticatedChannel and GenerateToken.
The tooling package Grpc.Tools can be used to generate the C# assets from the bws.proto file.
Refer to overview for gRPC on .NET to learn more about how to call into a gRPC service with a .NET client.
try
{
using GrpcChannel channel = CreateAuthenticatedChannel(new Uri(options.Host), GenerateToken(options.ClientId, options.Key));
var client = new BioIDWebService.BioIDWebServiceClient(channel);
var request = new LivenessDetectionRequest();
foreach (string file in options.Files)
{
request.LiveImages.Add(new ImageData { Image = ByteString.CopyFrom(File.ReadAllBytes(file)) });
}
var call = client.LivenessDetectionAsync(request);
LivenessDetectionResponse response = await call.ResponseAsync.ConfigureAwait(false);
// ...
Console.WriteLine($"This was live: {response.Live} (confidence: {response.LivenessScore:F2})");
}
catch (RpcException ex)
{
Console.Error.WriteLine($"gRPC error from calling service: {ex.Status.StatusCode} - '{ex.Status.Detail}'");
}
To generate Java classes from a bws.proto file use the Protobuf compiler (protoc) with the command in cmd or in terminal : protoc --java_out=OUTPUT_DIR bws.proto
For gRPC client stubs, add the gRPC plugin and use the command: protoc --java_out=OUTPUT_DIR --grpc-java_out=OUTPUT_DIR --plugin=protoc-gen-grpc-java=PATH_TO_PLUGIN bws.proto
For a detailed step by step guide on protobuf usage with Java, please refer to Java detailed guide
import java.util.concurrent.CompletableFuture;
import com.bioid.services.BioIDWebServiceGrpc;
import com.bioid.services.BioIDWebServiceGrpc.BioIDWebServiceStub;
import com.bioid.services.Bws.ImageData;
import com.bioid.services.Bws.LivenessDetectionRequest;
import com.bioid.services.Bws.LivenessDetectionResponse;
import com.google.protobuf.ByteString;
import io.grpc.ManagedChannel;
import io.grpc.StatusRuntimeException;
import io.grpc.stub.StreamObserver;
public void livenessDetectionAsync(byte[] liveImage1, byte[] liveImage2)
{
try
{
String jwtToken = generateToken(options.clientId, option.secretKey, options.expireMinutes);
ManagedChannel channel = createAuthenticatedChannel(option.host, jwtToken);
BioIDWebServiceStub bwsClientAsync = BioIDWebServiceGrpc.newStub(channel);
LivenessDetectionRequest livenessRequest = LivenessDetectionRequest.newBuilder()
.addLiveImages(ImageData.newBuilder().setImage(ByteString.copyFrom(liveImage1)).build())
.addLiveImages(ImageData.newBuilder().setImage(ByteString.copyFrom(liveImage2)).build())
.build();
CompletableFuture <LivenessDetectionResponse> livenessResult = new CompletableFuture <>();
bwsClientAsync.livenessDetection(livenessRequest, new StreamObserver <LivenessDetectionResponse>() {
@Override
public void onNext(LivenessDetectionResponse value)
{
livenessResult.complete(value);
}
@Override
public void onError(Throwable t)
{
livenessResult.completeExceptionally(t);
}
@Override
public void onCompleted()
{
}
});
LivenessDetectionResponse livenessDetecionResponse = livenessResult.get();
System.out.printf("This was live: %s - Confidence: %f", livenessDetecionResponse.getLive(), livenessDetecionResponse.getLivenessScore());
}
catch (StatusRuntimeException ex)
{
System.err.printf("gRPC error from calling service: %s - '%s'", ex.getStatus(), ex.getStatus().getDescription());
}
catch (Exception ex)
{
System.err.printf("Error processing images: " + ex.getMessage());
}
}
Using the protocol buffer compiler protoc (install: python -m pip install grpcio-tools)
from the Phython gRPC tools
you can create the Phyton client code from the .proto service definition:
python -m grpc_tools.protoc --proto_path=. --python_out=. --grpc_python_out=. bws.proto
import grpc
import bws_pb2_grpc
import bws_pb2
token = GenerateToken(args.clientid, args.key, 10)
with CreateAuthenticatedChannel(args.host, token) as channel:
stub = bws_pb2_grpc.BioIDWebServiceStub(channel)
request = bws_pb2.LivenessDetectionRequest()
for img_file in args.images:
with open(img_file, 'rb') as f:
request.live_images.add(image=f.read())
try:
response = stub.LivenessDetection(request)
except grpc.RpcError as rpc_error:
print("Received error: ", rpc_error)
print response