Templates faciais

As funções abaixo fornecem uma forma alternativa de cadastro facial, permitindo a extração e cadastro de templates faciais para o reconhecimento facial. Essas funções são exclusivas dos equipamentos faciais e estão disponíveis a partir das versões de firmware V6.25.0 (iDFace), V7.10.0 (iDFace Max) e V8.6.0 (iDFace e iDFace Max).

Extração de templates faciais

Recebe o arquivo de uma imagem e retorna o template facial extraido em base 64. O Content-Type deste comando deve ser necessariamente application/octet-stream e a imagem deve ser passada no Content do método POST.

POST /face_template_extract.fcgi

Parâmetros

Imagem, em formato binário.

Resposta

scores (objeto JSON) : Medidas de posicionamento e qualidade da imagem recebida. São elas:
- bounds_width (int) : Largura do rosto.
- horizontal_center_offset (int) : Distância horizontal do centro do rosto ao centro da imagem.
- vertical_center_offset (int) : Distância vertical do centro do rosto ao centro da imagem.
- center_pose_quality (int) : Nota para qualidade de centralização, que indica se rosto está virado para a câmera ou se está torto.
- sharpness_quality (int) : Nitidez da imagem.
success (bool) : Indica se o cadastro foi bem-sucedido ou não.
errors (array de objetos JSON) : Lista contendo um ou mais erros justificando uma extração mal-sucedida. Para cada erro:
- code (int) : Código correspondente ao erro informado.
- message (string) : Mensagem descrevendo o erro.
face_template (string) : Template facial em base 64

Erros possíveis da imagem a ser cadastrada

Conforme descrito no tópico Recomendações - fotos e instalação, existem alguns critérios de qualidade da foto que devem ser seguidos para que o reconhecimento facial ocorra da maneira correta. Caso exista uma tentativa de extração, inserindo um arquivo de imagem que não siga as recomendações previstas, haverá mensagens de erros informando os motivos pelos quais a foto não foi aceita. A seguir estão listados os códigos de erros e as mensagens correspondentes que explicam suas causas:

code 1: Corresponde a erros não relacionados com a qualidade do arquivo, mas sim com algum erro na passagem de parâmetros da requisição. Existem vários tipos de mensagens que podem surgir com erros desse código, por exemplo:
- message: "Invalid data (image file expected)"
code 2: Ocorre quando não é possível identificar uma face no arquivo de imagem enviado.
- message: "Face not detected"
code 4: Ocorre quando as distâncias horizontais e verticais do centro do rosto ao centro da imagem estão muito significativas. Para entender quantitativamente como isso pode ser resolvido, deve-se analisar a reposta da requisição. No objeto JSON score, é preciso analisar os valores dos parâmetros horizontal_center_offset e vertical_center_offset. O valor máximo permitido para ambos é 1000. Portanto, quando esse valor é ultrapassado a seguinte mensagem é exibida:
- message: "Face not centered"
code 5: Ocorre quando a largura do rosto na imagem é muito pequena (face distante da câmera). Para entender quantitativamente como isso pode ser resolvido, deve-se analisar a reposta da requisição. No objeto JSON score, é preciso analisar o valor do parâmetro bounds_width. O valor mínimo permitido é 60. Portanto, quando esse valor é ultrapassado a seguinte mensagem é exibida:
- message: "Face too distant"
code 6: Ocorre quando a largura do rosto na imagem é muito grande (face muito perto da câmera). Para entender quantitativamente como isso pode ser resolvido, deve-se analisar a reposta da requisição. No objeto JSON score, é preciso analisar o valor do parâmetro bounds_width. O valor máximo permitido é 800. Portanto, quando esse valor é ultrapassado a seguinte mensagem é exibida:
- message: "Face too close"
code 7: Ocorre quando a centralização do rosto não está boa, indicando que o rosto está torto em relação à câmera. Para entender quantitativamente como isso pode ser resolvido, deve-se analisar a reposta da requisição. No objeto JSON score, é preciso analisar o valor do parâmetro center_pose_quality. O valor máximo permitido é 400. Portanto, quando esse valor é ultrapassado a seguinte mensagem é exibida:
- message: "Face pose not centered"
code 8: Ocorre quando a imagem cadastrada não possui nitidez suficiente para garantir o reconhecimento facial. Para entender quantitativamente como isso pode ser resolvido, deve-se analisar a reposta da requisição. No objeto JSON score, é preciso analisar o valor do parâmetro sharpness_quality. O valor mínimo permitido é 450. Portanto, quando esse valor é inferior a seguinte mensagem é exibida:
- message: "Low sharpness"
code 9: Ocorre quando o rosto está muito próximo das bordas da imagem.
- message: "Face too close to image borders"
code 11: Ocorre quando a imagem fornecida é preta e branca e o parâmetro face_enroll_mode é definido como 1.
- message: "Face image is in grayscale"
code 12: Ocorre quando há mais de uma face na imagem e o parâmetro face_enroll_mode é definido como 1.
- message: "Multiple faces in image"

Exemplo de requisição

Essa requisição extrai o template facial de uma imagem.

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

Exemplo de resposta

Resultado de uma extração bem sucedida.

{
    "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
}

Extração de lista de templates faciais

Endpoint para extração em massa de templates faciais. Recebe um lista objetos com imagens em base 64 e IDs e retorna um lista de objetos com os templates faciais extraidos em base 64.

Recomendações sobre formato e tamanho das imagens, além de posicionamento de rosto para extração podem ser encontradas consultando o tópico Recomendações - fotos e instalação.

POST /face_template_extract_list.fcgi

Parâmetros

face_images (array): Este parâmetro deverá ser representado como um objeto JSON contendo os membros image (a imagem em base 64) e um id referente ao template dentro do array, todos obrigatórios.

Resposta

results (array de objetos JSON) : Lista dos resultados individuais para a extração de cada foto enviada na requisição. Cada objeto de resultado possui o mesmo formato de resposta que o da chamada Extração de templates faciais acrescido do respectivo identificador.

Exemplo de requisição

A requisição a seguir faz a extração de dois 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="
      }
    ]
  }
});

Exemplo de resposta

Resultado de um cadastro bem-sucedido e um mal-sucedido devido ao uso de uma imagem inválida.

{
    "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."
                }
            ]
        }
    ]
}

Cadastro de templates

Esse endpoint faz o cadastro dos templates para os respectivos usuários.

POST /face_template_enroll.fcgi

Parâmetros

match (bool) : Indica se deve ser feita a verificação se existe um usuário diferente com um template similar já registrado.
face_tempaltes (array de objetos JSON) : Contém os templates a serem cadastrados com os respectivos usuários.
- user_id (int) : Identificador do usuário ao qual será atribuido o template.
- timestamp (int) : Inteiro representando o horário em foi feita a operação, em formato UNIX timestamp.
- face_template (string) : Template facial em base 64

Resposta

results (array de objetos JSON) :
- user_id (int) : Identificador de usuário.
- success (bool) : Indica o sucesso da operação.
- errors (array de objetos JSON) : Lista contendo um ou mais erros justificando um cadastro mal-sucedido. Para cada erro:
  - code (int) : Código correspondente ao erro informado.
  - message (string) : Mensagem descrevendo o erro.
  - info (objeto JSON) : Objeto contendo as informações de similaridade, caso seja encontrada uma imagem similar.

Exemplo de requisição

A requisição a seguir tenta cadastrar dois templates faciais com a verificação de templates similares ativa.

$.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=="
      }
    ]
  }
});

Exemplo de resposta

Resultado de uma requisição que cadastra com sucesso uma imagem e nega o cadastro da segunda devido a encontrar uma imagem similar em outro usuário cadastrado.

{
    "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
        }
    ]
}

Remoção de templates

Esse endpoint deve ser usado para excluir templates faciais, recebendo os IDs dos usuários cujos templates serão excluídos ou o parâmetro all para remover todos os templates do sistema.

POST /face_template_destroy

Parâmetro

all (bool): Indica se todos os templates devem ser excluídos, independente de user_ids. (Opicional)
user_ids (array de int): Contém os IDs dos usuários, cujos templates deseja-se excluir.

Resposta

Resposta vazia.

Exemplo de requisição

A requisição a seguir remove os templates dos usuários de ID 1 e 2.

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