Facial Template

The functions below provide an alternative method for facial enrollment, allowing the extraction and enrollment of facial templates for facial recognition. These features are exclusive to the facial recognition devices and are available starting with firmware versions V6.25.0 (iDFace), V7.10.0 (iDFace Max), and V8.6.0 (iDFace and iDFace Max).

Extract facial template

Receives an image file and returns the extracted facial template in base64. The Content-Type for this command must be application/octet-stream, and the image must be passed in the Content of the POST method.

POST /face_template_extract.fcgi

Parameters

• Image in binary format

Response

• scores (JSON object) : Positioning and quality metrics for the received image. These are:

  • bounds_width (int) : Face width.
  • horizontal_center_offset (int) : Horizontal distance from the center of the face to the center of the image.
  • vertical_center_offset (int) : Vertical distance from the center of the face to the center of the image.
  • center_pose_quality (int) : Score for centering quality, indicating whether the face is facing the camera or is tilted.
  • sharpness_quality (int) : Image sharpness.

• success (bool) : Indicates whether the registration was successful or not.
• errors (array of JSON objects) : List containing one or more errors explaining why the extraction failed. For each error:

  • code (int) : Code corresponding to the reported error.
  • message (string) : Message describing the error.

• face_template (string) : Base64-encoded face template

Possible errors with the image to be uploaded

As described in the topic Recommendations - Photos and Installation, there are certain photo quality criteria that must be followed for facial recognition to work correctly. If you attempt to upload an image file that does not meet the specified recommendations, error messages will appear explaining why the photo was not accepted. The following lists the error codes and corresponding messages that explain their causes:

• code 1: This corresponds to errors not related to file quality, but rather to an error in the request parameters. There are several types of messages that may appear with errors of this code, for example:

  • message: “Invalid data (image file expected)”

• code 2: Occurs when a face cannot be identified in the uploaded image file.

  • message: “Face not detected”

• code 4: Occurs when the horizontal and vertical distances from the center of the face to the center of the image are too significant. To understand quantitatively how this can be resolved, you must analyze the request response. In the JSON object score, you need to analyze the values of the horizontal_center_offset and vertical_center_offset parameters. The maximum allowed value for both is 1000. Therefore, when this value is exceeded, the following message is displayed:

  • message: “Face not centered”

• code 5: Occurs when the width of the face in the image is too small (face far from the camera). To understand quantitatively how this can be resolved, you must analyze the request response. In the JSON object score, you need to analyze the value of the bounds_width parameter. The minimum allowed value is 60. Therefore, when this value is exceeded, the following message is displayed:

  • message: “Face too distant”

• Code 6: This occurs when the width of the face in the image is too large (the face is too close to the camera). To understand quantitatively how this can be resolved, you must analyze the response to the request. In the JSON object score, you need to analyze the value of the bounds_width parameter. The maximum allowed value is 800. Therefore, when this value is exceeded, the following message is displayed:

  • message: “Face too close”

• code 7: Occurs when the face is not properly centered, indicating that the face is tilted relative to the camera. To understand quantitatively how this can be resolved, you must analyze the request response. In the JSON object score, you need to analyze the value of the center_pose_quality parameter. The maximum allowed value is 400. Therefore, when this value is exceeded, the following message is displayed:

  • message: “Face pose not centered”

• code 8: Occurs when the registered image is not sharp enough to ensure facial recognition. To understand quantitatively how this can be resolved, you must analyze the response to the request. In the JSON object score, you must analyze the value of the sharpness_quality parameter. The minimum allowed value is 450. Therefore, when this value is lower, the following message is displayed:

  • message: "Low sharpness"

• code 9: Occurs when the face is too close to the edges of the image.

  • message: “Face too close to image borders”

• code 11: Occurs when the provided image is black and white and the face_enroll_mode parameter is set to 1.

  • message: “Face image is in grayscale”

• code 12: Occurs when there is more than one face in the image and the face_enroll_mode parameter is set to 1.

  • message: “Multiple faces in image”

Request Example

This request extracts the facial template from an image.

$.ajax({
  url: "/face_template_extract.fcgi?session=" + session,
  type: 'POST',
  contentType: 'application/octet-stream',
  data: [image bytes]
});

Response Example

Result of a successful extraction.

{
    "scores": {
        "bounds_width": 113,
        "horizontal_center_offset": -12,
        "vertical_center_offset": -134,
        "center_pose_quality": 901,
        "sharpness_quality": 865
    },
    "face_template": "vRYFPUe+C76B1RY+azJD...",
    "success": true
}

Extraction of facial template lists

Endpoint for batch extraction of facial templates. It accepts a list of objects containing base64-encoded images and IDs, and returns a list of objects containing the extracted facial templates in base64 format.

Recommendations regarding image format and size, as well as face positioning for extraction, can be found in the topic Recommendations - photos and installation.

POST /face_template_extract_list.fcgi

Parameters

• face_images (array): This parameter must be represented as a JSON object containing the image (the base64-encoded image) and id (referring to the template within the array) members, all of which are required.

Response

• results (array of JSON objects): List of individual results for the extraction of each photo sent in the request. Each result object has the same Response format as the Facial Template Extraction call, plus the respective identifier.

Request Example

The following query retrieves two templates.

$.ajax({
  url: "/face_template_extract_list.fcgi?session=" + session,
  type: 'POST',
  contentType: 'application/json',
  data: {
    "face_images": [
      {
        "id": 1,
        "image": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAY ... QK5JP3FQw2eE1oQf/9k="
      },
      {
        "id": 2,
        "image": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAo ... D1odQIroECBAgQIJ/9k="
      }
    ]
  }
});

Response Example

Results of a successful registration and an unsuccessful one due to the use of an invalid image.

{
    "results": [
        {
            "id": 1,
            "scores": {
                "bounds_width": 113,
                "horizontal_center_offset": -12,
                "vertical_center_offset": -134,
                "center_pose_quality": 901,
                "sharpness_quality": 865
            },
            "face_template": "vRYFPUe+C76B1RY+azJDPYHVFr22bni ... /8z2jH+u9lCSkPVSPbz2B1ZY9p3MxPA==",
            "success": true
        },
        {
            "id": 2,
            "success": false,
            "errors": [
                {
                    "code": 1,
                    "message": "Failed: Image file not recognized. Image should be either JPG or PNG."
                }
            ]
        }
    ]
}

Similar Template Check

This endpoint checks whether there is another user already registered with a template similar to the one provided. It accepts a user ID and a facial template, if there is a user with a different ID and a similar template already registered, it returns the user, the score, and the similarity.

Enroll Templates

This endpoint enroll templates for the respective users.

POST /face_template_enroll.fcgi

Parameters

• match (bool) : Indicates whether to check if there is already a different user with a similar template registered.
• face_templates (array of JSON objects) : Contains the templates to be registered with their respective users.

  • user_id (int) : Identifier of the user to whom the template will be assigned.
  • timestamp (int) : Integer representing the time the operation was performed, in UNIX timestamp format.
  • face_template (string) : Base64-encoded facial template

Response

• results (array of JSON objects) :

  • user_id (int) : User identifier.
  • success (bool) : Indicates whether the operation was successful.
  • errors (array of JSON objects) : List containing one or more errors explaining why the registration failed. For each error:

    • code (int) : Code corresponding to the reported error.
    • message (string) : Message describing the error.
    • info (JSON object) : Object containing similarity information, if a similar image is found.

Request Example

The following request attempts to enroll two facial templates using template matching.

    $.ajax({
        url: "/face_template_enroll.fcgi?session=" + session,
        type: 'POST',
        contentType: 'application/json',
        data: {
        "match": true,
        "face_templates": [
            {
            "user_id": 1,
            "timestamp": 1628727478,
            "face_template": "q/HSO4lkFb2+qwy9JoPkPHMviL2hFHa8vqs ... 8dI75OO8PTk9Hj0O04M9DtMDvQ=="
            },
            {
            "user_id": 2,
            "timestamp": 1628873297,
            "face_template": "q/HSO4lkFb2+qwy9JoPkPHMiLAD/2wBDAAo ... 8dI75OO8PTk9Hj0O04M9DtMDvQ=="
            }
        ]
        }
    });

Response Example

Result of a request that successfully uploads one image but rejects the upload of the second one because a similar image was found in another registered user.

{
    "results": [
        {
            "user_id": 1,
            "success": true
        },
        {
            "user_id": 2,
            "errors": [
                {
                    "code": 3,
                    "message": "Face exists",
                    "info": {
                        "match_user_id": 1,
                        "match_score": 969,
                        "match_similarity": 4000
                    }
                }
            ],
            "success": false
        }
    ]
}

Deleting Templates

This endpoint should be used to delete facial templates. It accepts the IDs of the users whose templates are to be deleted, or the all parameter to delete all templates from the system.

POST /face_template_destroy

Parameter

• all (bool): Specifies whether all templates should be deleted, regardless of user_ids. (Optional)
• user_ids (array of int): Contains the IDs of the users whose templates you want to delete.

Response

Empty response.

Request Example

The following request removes the templates for users with IDs 1 and 2.

$.ajax({
    url: "/face_template_destroy.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: {
        "user_ids": [1,2]
    }
});