Face Comparison

On this page, find detailed information about faces comparison in Face SDK Web API.

Compare

To perform a comparison of faces in the same image or in two different images, use POST /api/match.

Request

The SDK can compare faces in the same image or in two different images. This is defined by the type parameter.

The request contains the following parameters:

└── images
|   └── data
|   └── index
|   └── detectAll
|   └── type
└── thumbnails

Parameter	Description
images	The array of all images included in the comparison: data, index, detectAll, type for each image.
data	Base64 image
index	The index number of an image. Can be given, if not given, the index numbers are set automatically starting from 0. All index numbers must be whole and unique—not repeated.
detectAll	If set to true, the detection of all faces on the image is enabled. If set to false, only one face on the image is detected: the most central one.
type	The type of the image, defines the way the comparison is performed. Should be set by a user. "type": 1 (ift_DocumentPrinted = 1)—Image with a visual zone “document“. "type": 2 (ift_DocumentRFID = 2)—Image from the RFID document. "type": 3 (ift_Live = 3)—Live picture from a web camera. "type": 4 (ift_LiveWithDoc = 4)—Compares all faces on one image with each other, for example, a photo of a person showing their passport (or any other document) photo. "type": 5 (ift_External = 5)—Any other type or type is not defined.
thumbnails	If set to true, in Response, returns thumbnail—Base64 cropped image that contains the vertically aligned face. If set to false, thumbnail is not returned. Default: false.

Response

Before comparing faces, the Face SDK detects them. The detection result is displayed in the detections field.

Each face is identified by two parameters: faceIndex (the index number of the face) and imageIndex (the index number of the image on which the face is detected).

So, if there are two images each of which has two faces on them and all index numbers start from 0, the parameters will be the following:

First face on the first image:"faceIndex": 0, "imageIndex": 0

Second face in the first image: "faceIndex": 1, "imageIndex": 0

First face of the second image: "faceIndex": 0, "imageIndex": 1

Second face in the second image: "faceIndex": 1, "imageIndex": 1

The response contains the following parameters:

└── ErrorCode
└── code
└── detections
|   └── faces
|   |   └── faceIndex
|   |   └── landmarks
|   |   └── roi
|   |   └── rotationAngle
|   |   └── thumbnail
|   └── imageIndex
|   └── status
└── results
|   └── first
|   └── firstFaceIndex
|   └── firstIndex
|   └── score
|   └── second
|   └── secondFaceIndex
|   └── secondIndex
|   └── similarity

Parameter	Description
ErrorCode	Legacy parameter.
code	The result code the SDK returns. If everything is OK, the result looks as follows: "ErrorCode": 0, "code": 0 See the list of error codes below.
detections	The array of detected faces. Includes faces, imageIndex, status.
faces	The array of detected faces. Includes faceIndex, landmarks, roi, rotationAngle, thumbnail for each of the detected faces.
faceIndex	The index number of each of the detected face. Can be given, if not given, the index numbers are set automatically starting from 0. All index numbers must be whole and unique—not repeated.
landmarks	Returns absolute coordinates (x,y) of five points of each detected face: left eye, right eye, nose, left point of lips, right point of lips.
rotationAngle	Angle of rotation of the face from the vertical axis, degrees.
thumbnail	Base64 cropped image that contains the vertically aligned face.
imageIndex	The same as the index parameter from Request: The index number of the image on which the faces above are detected.
status	Returns the same value as code. If "code": 0 everything is OK. First status is detected, and if something is wrong, it is returned in code as well. Possible errors: "status": 1—image is empty, try again with another image "status": 2—face is not detected "status": 6—data can not be decoded as image
results	The comparison results include first, firstFaceIndex, firstIndex, score, second, secondFaceIndex, secondIndex, similarity for each comparison of two faces.
first	type (see the Request parameters) of the first compared face.
firstFaceIndex	faceIndex of the first compared face.
firstIndex	imageIndex of the image on which the first compared face is detected.
score	A dimensionless number that shows how similar the compared faces are. 0—absolutely identical faces.
second	type (see the Request parameters) of the second compared face.
secondFaceIndex	faceIndex of the second compared face.
secondIndex	imageIndex of the image on which the second compared face is detected.
similarity	The detected faces similarity, %. 100%—absolutely identical faces, 0%—absolutely not identical.

Compare and search

To compare several images from a document and look up a person in the database in one request, use POST /api/match_and_search. In this case, the calculation of the discriptor will be performed only once, as opposed to using two requests for the same operation.

Find comprehensive information in OpenAPI documentation.

Errors

Here is a list of possible errors and their meanings:

Error	Description
FR_FACE_NOT_DETECTED = 2	No faces are detected, most probably, the image does not contain faces.
FACER_NO_LICENSE = 200	There is no license.
FACER_IS_NOT_INITIALIZED = 201	The library is not initialized.
FACER_COMMAND_IS_NOT_SUPPORTED = 202	The command is not supported.
FACER_COMMAND_PARAMS_READ_ERROR = 203	The request is formed incorrectly.
FACER_LESS_THAN_TWO_IMAGES_IN_REQUEST = 224	There are fewer than two images selected.
FACER_OUTPUT_IS_NOT_DEFINED = 229	There is no memory allocated for the response.
FACER_IMAGES_COUNT_LIMIT_EXCEEDED = 238	The number of images of the same type for comparison is exceeded—you can’t compare more than two images of the same type.