Facial photo enrollment

The functions described below should be used to enroll, read and delete users' pictures in Control iD access control terminals with facial recognition.

In this type of device, it is not necessary to deal with templates, it is enough to include or modify the user's picture for facial recognition to occur normally.

However, for privacy reasons, it's possible to configure the equipment so that the photo is removed right after user enrollment, being used only to generate the corresponding template. By default, the user's image is kept. If required, you can configure the user photo removal after enrollment as presented at user photo removal after enrollment section.

Get user's photo

Gets the picture of a user specified by the user id. The return can be either the image itself, in image/jpeg format, or a JSON object that contains the image data in base64 format and the registration timestamp in Unix Timestamp standard.

The return format is defined by the parameters passed in the request. Since the HTTP method used is GET, all parameters are sent through a query string.

GET /user_get_image.fcgi

Parameters

  • user_id (int 64): Identifier of the user whose photo will be taken.
  • get_timestamp (int): If positive, it determines a JSON return containing the registration timestamp of the photo.

Response

When get_timestamp = 0:

  • User image in jpg format

When get_timestamp = 1:

  • timestamp (int): Timestamp value of the registered photo in the Unix Timestamp pattern.
  • image (string): Registration image in base64 format

Request Example

This request returns only a picture of the user in jpg format (timestamp=0)

$.ajax({
  url: "/user_get_image.fcgi?user_id=123&get_timestamp=0&session=" + session,
  type: 'GET',
});

Example of response when timestamp=1

{
  "timestamp": 1624997578,
  "image": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAE ... SurHnqq4vn5U3Pf5H//Z"
}

Get the list of users with registered photo

Get the list of ids of users who have face registered in the device

GET /user_list_images

Parameters

  • get_timestamp (int): If positive, it determines a JSON return containing the registration timestamp of the photo.

Response

When get_timestamp = 0:

  • user_ids (array of int 64): List of user ids with a registered photo.

When get_timestamp = 1:

  • image_info (JSON object array): List of users with a registered photo, containing:
  • user_id (int 64): User ID.
  • timestamp (int): Timestamp value of the registered photo in the Unix Timestamp pattern.

Request Example

This request returns the list of users with a registered photo, including identifier and registration timestamp for each one.

$.ajax({
  url: "/user_list_images.fcgi?get_timestamp=1&session=" + session,
  type: 'GET'
});

Response example

{
  "image_info": [
    {
        "user_id": 1,
        "timestamp": 1628203752
    },
    {
        "user_id": 2,
        "timestamp": 1628203752
    },
    {
        "user_id": 3,
        "timestamp": 1628203752
    }
  ]
}

Get user's photo list

Retrieves the list of photos registered in the device, according to the required user ids. This call is limited to returning a maximum of 100 user photos per request.

POST /user_get_image_list.fcgi

Parameters

  • user_ids (array of int 64): List of ids of the users whose pictures are to be returned.

Response

  • user_images (array of JSON objects) : List with the image data of each user.

Each object contains:

  • id (int 64): Identifier of the user whose photo will be taken.
  • timestamp (int): Timestamp in Unix format Timestamp of the returned registration photo.
  • image (string): User image file in base64 format.

When the return fails for the user, the object contains the error information:

  • id (int 64): Identifier of the user whose photo was requested.
  • error (JSON object): Error information object, consisting of:
  • code (int): Error code.
  • message (string): Message explaining the error.

Request Example

This request will return images from a list of users.

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

Example response

{
  "user_images": [
    {
      "id": 1,
      "timestamp": 1626890032,
      "image": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAE ... BrBRkuWacorVep//2Q=="
    },
    {
      "id": 2,
      "error": {
        "code": 1,
        "message": "User does not exist"
      }
    },
    {
      "id": 3,
      "timestamp": 1626889927,
      "image": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAE ... 8kP5Tl+u4uesqtj/2Q=="
    }
  ]
}

Register user's photo

Saves and registers the photo of a user specified by its id. Unlike most commands of this API, the Content-Type of this command must necessarily be application/octet-stream. The image is passed in the Content of the POST method and the registration information is passed in the Query String. The photo file must be smaller than 2MB.

For mass registration of users, it is recommended to use the endpoint /user_set_image_list.fcgi.

Recommendations on image size and format, as well as face positioning for registration, can be found by referring to the topic Recommendations - Photos and Installation.

POST /user_set_image.fcgi

Parameters

  • user_id (int 64): Identifier of the user whose photo will be assigned (required).
  • timestamp (int): Timestamp in Unix format Timestamp to be registered for the registration of the photo (required).
  • match (int): Takes on the values 0 or 1. When its value is 1, the photo registration should be rejected if the face is already registered for another user. For mass enrollments, it is recommended not to check for duplicates (match = 0) to speed up the process.

These parameters are passed in the Query String

Response

  • user_id (int 64): Identifier of the user whose picture will be assigned.
  • scores (JSON object): Position and quality measures of the received image. They 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, which indicates whether the face is facing the camera or is angled.
  • sharpness_quality (int): Sharpness of the image.
  • success (bool): Indicates whether the registration was successful or not.
  • errors (array of JSON objects): List containing one or more errors justifying an unsuccessful registration. For each error:
  • code (int): Code corresponding to the error reported.
  • message (string): Message describing the error.

Possible errors in the image to be registered

As described in the topic Recommendations - Photos and Installation, some photo quality criteria must be followed for facial recognition to occur correctly. If there is a remote photo registration attempt, inserting an image file that does not follow the expected recommendations, there will be error messages informing the reasons why the photo was not accepted. Listed below are the error codes and the corresponding messages explaining their causes:

  • code 1: Corresponds to errors not related to the quality of the file, to some error in passing parameters of the request. Several types of messages can arise with errors of this code, some examples are:
  • message: "Image file not recognized. The image should be either JPG or PNG.", "User does not exist", "Invalid user_id".
  • code 2: Occurs when a face cannot be identified in the uploaded image file.
  • message: "Face not detected"
  • code 3: Appears when an attempt is made to register a face that already exists.
  • message: "Face exists"
  • code 4: This 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 solved, the response of the request should be analyzed. In the score JSON object, 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: This occurs when the width of the face in the image is too small (face away from the camera). To understand quantitatively how this can be solved, the response of the request should be analyzed. In the score JSON object, you have to analyze the value of the bounds_width parameter. The minimum value allowed is 60, so when this value is lower 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 (face too close to the camera). To understand quantitatively how this can be solved, the response of the request should be analyzed. In the score JSON object, you have to analyze the value of the bounds_width parameter. The maximum value allowed is 800. Therefore, when this value is exceeded the following message is displayed:
  • message: "Face too close"
  • code 7: This occurs when the centering of the face is not good, indicating that the face is crooked in relation to the camera. To understand quantitatively how this can be solved, the response of the request should be analyzed. In the score JSON object, you have to analyze the value of the center_pose_quality parameter. The maximum value allowed is 400. Therefore, when this value is exceeded the following message is displayed:
  • message: "Face pose not centered"
  • code 8: This occurs when the registered image does not have enough sharpness to guarantee facial recognition. To understand quantitatively how this can be solved, the response of the request should be analyzed. In the score JSON object, you have to analyze the value of the sharpness_quality parameter. The minimum value allowed is 450. Therefore, when this value is lower the following message is displayed:
  • message: "Low sharpness"
  • code 9: It occurs when the face is too close to the edges of the image.
  • message: "Face too close to image borders"

Request Example

This request will register a photo and timestamp for a user

$.ajax({
  url: "/user_set_image.fcgi?user_id=123&timestamp=1624997578&match=0&session=" + session,
  type: 'POST',
  contentType: 'application/octet-stream',
  data: [bytes da imagem enviada]
});

Example of response

This result corresponds to an unsuccessful registration due to poor image sharpness

{
  "user_id": 123,
  "scores": {
    "bounds_width": 397,
    "horizontal_center_offset": 87,
    "vertical_center_offset": -75,
    "center_pose_quality": 698,
    "sharpness_quality": 105
  },
  "success": false,
  "errors": [
    {
      "code": 8,
      "message": "Low sharpness"
    }
  ]
}

Register User's Photo List

This endpoint registers user pictures. It receives an array of ids, timestamps, and images encoded in base 64. The request size limit accepted by the access controller is 2MB.

Recommendations on image format, size and face positioning for registration can be found by referring to the topic Recommendations - Photos and Installation.

POST /user_set_image_list.fcgi

Parameters

  • match (bool): Indicates whether the registration of photos should reject those whose faces are already registered for other users. For mass registration, it is recommended not to check for duplicates (match = 0) to speed up the process.
  • user_images (array): This parameter should be represented as a JSON object containing the members user_id, timestamp and image (the image in base 64), all required.

Response

  • results (array of JSON objects) : List of individual results for the registration of each photo sent in the request. Each result object has the same response format as the User photo registration call plus the respective user identifier.

Request Example

This request will assign photos to two users.

$.ajax({
  url: "/user_set_image_list.fcgi?session=" + session,
  type: 'POST',
  contentType: 'application/json',
  data: {
    "match": false,
    "user_images": [
      {
        "user_id": 20,
        "timestamp": 1628727478,
        "image": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAY ... QK5JP3FQw2eE1oQf/9k="
      },
      {
        "user_id": 23,
        "timestamp": 1628873297,
        "image": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAo ... D1odQIroECBAgQIJ/9k="
      }
    ]
  }
});

Example of response

Considering respectively the situations of:

  1. request error
  2. Image error (Errors)
  3. Face registered successfully
  4. Face rejected by the validation criteria

The result below shows the corresponding return formats.

{
  "results": [
    {
      "user_id": 1,
      "success": false,
      "errors": [
        {
          "code": 1,
          "message": "Failed: Invalid member 'timestamp' (int expected, got string)"
        }
      ]
    },
    {
      "user_id": 2,
      "success": false,
      "errors": [
        {
          "code": 2,
          "message": "Face not detected"
        }
      ]
    },
    {
      "user_id": 3,
      "scores": {
        "bounds_width": 104,
        "horizontal_center_offset": 16,
        "vertical_center_offset": -150,
        "center_pose_quality": 768,
        "sharpness_quality": 1000
      },
      "success": true
    },
    {
      "user_id": 4,
      "scores": {
        "bounds_width": 151,
        "horizontal_center_offset": -16,
        "vertical_center_offset": -24,
        "center_pose_quality": 502,
        "sharpness_quality": 789
      },
      "success": false,
      "errors": [
        {
          "code": 7,
          "message": "Face pose not centered"
        }
      ]
    }
  ]
}

Custom thresholds for facial recognition of similar faces

When a new face is being enrolled, it might be rejected if it is considered too similar to a previously registered image. In this case, the parameter match_confidence will be reported to the user, coupled with the user id corresponding to the owner of the pre-existing photo. With this information, it is possible to modify the thresholds used in the facial recognition process for that specific face, until the new image is no longer compatible. It should be noted that this procedure will make the identiifcation more rigorous for the already existing user, possibly interfering with the equipment's behavior, besides being a completely empirical process. For these reasons, it is recommended that changes to this parameter are made with help from Control iD's Support.

POST /create_objects.fcgi

Parameters

  • object (string) : Type of the object to create. Value "custom_thresholds".
  • values (array of JSON objects) : Each element must be a JSON object representing the object to be created.
    • thresholds (int) : Threshold value desired to create a stricter identification.
    • user_id (int) : id of the user to whom the custom threshold will be linked

Response

  • ids (array of 64-bit integers) : ids of the objects created.

Example request

This request will create a custom threshold for a user.

$.ajax({
  url: "/create_objects.fcgi?session=" + session,
  type: 'POST',
  contentType: 'application/json',
  data: JSON.stringify({
    object: "custom_thresholds",
    values: [{threshold: 1200, user_id: 3}]
  })
});

Testing a User's Photo

Since photo registration in the terminal must meet a series of criteria, it is possible to perform a prior test with the image that will be registered in the system to identify whether it is suitable for storage. This testing process follows similar premises to a common registration, however, tested images are never stored in the device.

POST /user_test_image.fcgi

Parameters

  • Image that will be tested in binary format.

Response

  • scores (JSON object) : Measures the positioning and quality of the received image. They 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): Note for centering quality, which indicates whether the face is facing the camera or is angled.
  • sharpness_quality (int): Sharpness of the image.
  • success (bool): Indicates whether the registration with the tested image would be successful.
  • errors (array of JSON objects): List containing one or more errors justifying why the tested photo was rejected. For each error:
  • code (int): Code corresponding to the error reported.
  • message (string): Message describing the error.

More detailed descriptions of the possible errors can be found here.

Request Example

This request will test an image.

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

Delete user photo

Deletes pictures of users specified by id. It can contain a single id, an array of ids, or an "all" flag to remove all. Deleting the photo necessarily implies deleting the user's facial record for recognition.

POST /user_destroy_image.fcgi

Parameters

  • user_id (int 64): Identifier of the user whose photo will be destroyed.
  • user_ids (array int 64): Array of user id's whose pictures will be removed.
  • dangling (bool): If sent as 'true' remove the photos not linked to users.
  • all (bool): If sent as 'true' all users will have their photos deleted.

Response

  • This request has no response.

Request Example

Removes the photo of the user with id 123.

$.ajax({
  url: "/user_destroy_image.fcgi?session=" + session,
  type: 'POST',
  contentType: 'application/json',
  data: JSON.stringify({
    user_id: "123"
  })
});

User photo removal after enrollment

It's possible to configure the equipment so that the photo is removed right after user enrollment, using it only to generate the facial recognition template. By default, user photos are kept after enrollment.

The change can be made by changing the value of the keep_user_image parameter, where the possible values ​​are '1' (user photos are kept after enrollment) or '0' (user photos are removed).

Example request

Configures the device to remove the user's photo after enrollment.

$.ajax({
  url: "/set_configuration.fcgi?session=" + session,
  type: 'POST',
  contentType: 'application/json',
  data: JSON.stringify({
    general: {
      "keep_user_image": '0'
    }
  })
});

User photo synchronization

The Face Enrollment API can also be used in situations where you want to synchronize a device's user photos with an external database. For these cases, it is interesting to make use of the photo timestamp parameter to identify which users need updating.

The following set of steps presents a synchronization method using the API functions.

  1. Get users and registration timestamps with user_list_images.
  2. For each user, evaluate whether the timestamp is higher in the external system or device's database.
  3. Separate the users whose photo needs to be updated.
  4. Send the set of photos to update per user with user_set_image_list.