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
└── outputImageParams
| └── backgroundColor
| └── crop
| └── type
| └── size
| └── padColor
| └── returnOriginalRect
Parameter | Description |
---|---|
images | The array of all images included in the comparison: data , index , detectAll , type for each image. |
data | Base64 image |
index | The image index number. |
detectAll | Whether to detect all faces in the image. If set to false, only one face 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. |
thumbnails | Deprecated, use crop instead. |
outputImageParams | If set, the uploaded image is processed according to the indicated settings. |
background | If set, the background color is replaced. Defines the RGB value for the background color: the silhouette of a person is cut out and the background is filled with this color. |
crop | If set, the Base64 of an aligned and cropped portrait is returned in the crop field. Alignment is performed according to type . If a head on the original image is tilted, for the returned portrait it is aligned in a straight vertical line. If there are more than one face in the photo, all the faces will be detected and processed, and separate portraits for each face will be returned. So, if there were five people in the photo, you'll get five processed portraits. Each portrait can be downloaded. crop includes type , padColor , and size . |
type | The aspect ratio according to which alignment is performed. See the FaceImageQualityAlignType enum. To get a thumbnail of aspect ratio 3:4 , set 0 . |
size | The resize value in case type matches this value. If it doesn't match, no resize is performed. |
padColor | When an image is aligned by type , its original size may be insufficient, and in this case it needs to be supplemented, "padded". padColor sets the RGB value for the color that will be used for such a supplement. |
returnOriginalRect | If set, the coordinates of the rectangle with the face in the original image prepared for the face crop are returned in the originalRect field. Can be used only if the face in the original image is not tilted. |
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 in 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
| └── crop
| └── 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:
|
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 detected face index number. |
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. |
roi | The rectangular area of a detected face that is represented by a set of four elements: the X and Y coordinates of the top-left point, and the width and height dimensions of the rectangle. |
rotationAngle | Angle of rotation of the face from the vertical axis, degrees. |
thumbnail | Deprecated. |
crop | Thumbnail: Base64 of the aligned and cropped portrait. |
imageIndex | The image index number. 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. |
status | Returns the same value as Possible errors:
|
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.