Методы для анализа и распознавания биометрических данных

В этом разделе:

Обнаружение лица на изображении

/detect POST

Данный метод обнаруживает лицо на предоставленном изображении и возвращает координаты прямоугольной рамки вокруг лица (т. н. bbox) и ориентацию лица.

Примечание

Обнаружение лица выполняется компонентом findface-extraction-api. Таким образом, компонент findface-sf-api форматирует ваш исходный запрос и перенаправляет его в компонент findface-extraction-api для непосредственной обработки.

Важно

Обязательно передайте в query string метода активированный параметр facen=on, чтобы возвращенный результат был сохранен в memcached. Для извлечения результата распознавания из memcached используйте метод /detect GET.

Совет

Для того чтобы активировать параметр типа Boolean (gender, age и т. д.), подойдет любая из строк 1, yes, true или on, регистр не имеет значения.

Важно

Чтобы включить распознавание атрибутов лица, можно использовать как новые (предпочтительно), так и старые параметры API (подробное описание вы найдете в параметрах query string). Старый API позволяет распознавать пол, возраст, эмоции, в то время как новый API обеспечивает распознавание пола, возраста, эмоций, бороды и очков. Каждый атрибут лица (пол, возраст, эмоции, борода или очки) может быть упомянут только один раз в запросе, в новом или старом формате API.

Параметры query string:

  • "detector": детектор лиц, который будет применен к изображению. Может принимать значение nnd (обычный детектор) или normalized (детектор принимает нормализованное изображение лица, при этом стадия обнаружения лица пропускается).

  • "gender": логический тип, включает распознавание пола (старый API).

  • "age": логический тип, включает распознавание возраста (старый API).

  • "emotions": логический тип, включает распознавание эмоций (старый API).

  • "facen": логический тип, в запросе к findface-extraction-api будут включены параметры need_facen (извлечь вектор признаков) и need_normalized (получить нормализованное изображение лица). При этом полный ответ findface-extraction-api будет сохранен в memcached с временным UUID, который будет записан в поле id ответа.

  • "autorotate": логический тип, автоматически поворачивает исходное изображение в 4-х различных направлениях и возвращает лица, обнаруженные в каждом из них.

  • "return_facen": логический тип, возвращает в ответе вектор признаков лица. Для этого в файле конфигурации findface-sf-api также должна быть включена опция allow-return-facen.

  • "attribute": массив строк в формате ["gender", "age", "emotions", "beard", "glasses3"], включает распознавание атрибутов лица, переданных в массиве (новый API).

Параметры в теле запроса:

Изображение в виде файла с mime-типом image/jpeg, image/png, image/webp или ссылка на интернет-изображение с mime-типом text/x-url.

Возвращает:

  • список координат рамок вокруг обнаруженных лиц;

  • временный UUID результата детекции (id, если был передан активный параметр facen);

    Важно

    При написании кода необходимо предусмотреть проверку данного id на актуальность при обращении к нему впоследствии, поскольку со временем он становится неактуальным. В последнем случае повторите детекцию лица.

  • вектор признаков (если активирован return_facen);

  • пол (если активирован gender): male или female, со значением уверенности алгоритма в результате ("score");

  • возраст (если активирован age): количество лет;

  • эмоции (если активирован``emotions``): 6 базовых эмоций + нейтральная эмоция (angry, disgust, fear, happy, sad, surprise, neutral) со значением уверенности алгоритма в выражении каждой эмоции;

  • атрибуты (если переданы): пол (male или female), возраст (количество лет), эмоции (преобладающая эмоция), борода (beard или none), очки (sun, eye или none), вместе со значением уверенности алгоритма в результате;

  • ориентация.

Примеры

Запрос №1. Одновременное использование старого и нового API

curl -i -X POST 'http://127.0.0.1:18411/v2/detect?facen=on&age=on&gender=on&emotions=on&attribute=glasses3' -H 'Content-Type: image/jpeg' --data-binary @sample.jpg
HTTP/1.1 100 Continue

Ответ

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: SF:BpLnfgDs
Date: Thu, 23 May 2019 12:00:22 GMT
Content-Length: 713

{
    "faces": [
        {
            "id": "bjj8mlhjisgjrk6hj1v0",
            "bbox": { "left": 595, "top": 127, "right": 812, "bottom": 344 },
            "features": {
                "gender": { "gender": "FEMALE", "score": 0.9998938 },
                "age": 25,
                "score": -0.000696103,
                "emotions": [
                    { "emotion": "neutral", "score": 0.99958 },
                    { "emotion": "sad", "score": 0.0004020365 },
                    { "emotion": "happy", "score": 8.603454e-06 },
                    { "emotion": "surprise", "score": 8.076766e-06 },
                    { "emotion": "disgust", "score": 6.6535216e-07 },
                    { "emotion": "angry", "score": 6.1434775e-07 },
                    { "emotion": "fear", "score": 7.3372125e-10 }
                ],
                "attributes": {
                    "glasses3": {
                        "attribute": "glasses3",
                        "model": "glasses3.v0",
                        "result": [
                            { "confidence": 0.99958307, "name": "none" },
                            { "confidence": 0.00033243417, "name": "eye" },
                            { "confidence": 8.4465064e-05, "name": "sun" }
                        ]
                    }
                }
            }
        }
    ],
    "orientation": 1
}

Запрос №2. Использование нового API

curl -s -X POST 'http://master:18411/v2/detect?attribute=gender' -H 'Content-Type: image/jpeg' --data-binary @pasha.jpg | jq
{
  "faces": [
    {
      "bbox": {
        "left": 1019,
        "top": 1138,
        "right": 1666,
        "bottom": 2041
      },
      "features": {
        "score": -0.00035252835,
        "attributes": {
          "gender": {
            "extractor": "gender",
            "model": "gender.v2",
            "result": [
              {
                "confidence": 0.9999999,
                "name": "male"
              },
              {
                "confidence": 7.935678e-08,
                "name": "female"
              }
            ]
          },
          "quality": {
            "extractor": "quality",
            "model": "quality.v0",
            "result": 0.00035252835
          }
        }
      }
    }
  ],
  "orientation": 1
}

Извлечение результата детекции из memcached

/detect/:id GET

Данный метод служит для получения параметров обнаруженного лица, включая его вектор признаков, по временному UUID’s в memcached.

Параметры в сегментах пути:

  • :id: временный UUID обнаруженного лица в memcached.

Возвращает:

Представление JSON результата детекции.

Пример

Запрос

curl -i -X GET 'http://127.0.0.1:18411/v2/detect/bg2gu31jisghl6pee09g'

Ответ:

{
    "bbox": { "bottom": 343, "left": 593, "right": 824, "top": 112 },
    "features": {
        "age": 26.096783,
        "emotions": [
            { "emotion": "neutral", "score": 0.9094986 },
            { "emotion": "happy", "score": 0.11464329 },
            { "emotion": "sad", "score": 0.005675929 },
            { "emotion": "surprise", "score": -0.02556022 },
            { "emotion": "fear", "score": -0.14499822 },
            { "emotion": "angry", "score": -0.19491306 },
            { "emotion": "disgust", "score": -0.31617728 }
        ],
        "gender": { "gender": "FEMALE", "score": -2.7309942 },
        "score": -0.000696103
    },
    "id": "bg2gu31jisghl6pee09g"
}

Создание результата детекции из ответа findface-extraction-api

/detect/:id POST

Данный метод создает результат детекции из ответа findface-extraction-api.

Параметры в сегментах пути:

  • :id: задайте UUID, под которым в memcached будет храниться результат детекции.

Возвращает:

Пустой JSON в случае успеха.

Пример

Запрос

$ curl -i -X POST 'http://127.0.0.1:18411/v2/detect/bg2gu31jisghl6peea9g' -H 'Content-Type: application/json' --data-binary '@extapi-face.json'

Ответ:

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: jFSBuSPm
Date: Wed, 05 Dec 2018 08:08:56 GMT
Content-Length: 2

{}

Получение списка галерей

/galleries GET

Данный метод возвращает список всех существующих галерей в биометрической базе данных.

Параметры:

Отсутствуют.

Возвращает:

Словарь JSON со списком имен (name) галерей.

Пример

Запрос

GET /v2/galleries HTTP/1.1
Host: 172.17.47.19:18411

Ответ

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 02 Feb 2018 10:11:43 GMT
Content-Length: 35

{"galleries":[{"name":"sandbox"}]}

Добавление лица в галерею

/galleries/:gallery/faces/:id POST

Данный метод берет обнаруженное лицо из memcached или лицо из галереи, чтобы затем добавить его вместе с вектором признаков в указанную в параметрах query string галерею базы биометрических данных с присвоением указанного пользовательского id. Вместе с лицом вы также можете добавить метаданные, которые являются уникальными для его обладателя, например, идентификатор или имя.

Параметры в сегментах пути:

  • :gallery: имя галереи, в которую добавляется лицо.

  • :id: постоянный идентификатор лица в галерее, uint64.

Параметры в теле запроса:

  • "from": временный UUID обнаруженного лица в memcached ("from": "detection:<id>") или id лица в галерее ("from: "face:<gallery>/<id>").

  • "meta" [опционально]: метаданные, такие как имя обладателя лица, сведения об исходном изображении, дата и время детекции и т. д., словарь.

Возвращает:

  • Представление JSON добавленного лица в случае успеха.

  • Ошибка в случае неудачной попытки.

Пример

Запрос

curl -i -X POST http://127.0.0.1:18411/v2/galleries/hello/faces/123/ -H 'Content-Type: application/json' --data-binary '@-' <<EOF
{
    "from": "detection:bg2gu31jisghl6pee09g",
    "meta": {
        "camera": "openspace",
        "labels": ["foo", "bar"],
        "timestamp": "1543837276"
    }
}
EOF

Ответ

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: SF:OSSKbJg3
Date: Wed, 05 Dec 2018 08:27:59 GMT
Content-Length: 555

{
    "features": {
        "age": 26.096783,
        "emotions": [
            { "emotion": "neutral", "score": 0.9094986 },
            { "emotion": "happy", "score": 0.11464329 },
            { "emotion": "sad", "score": 0.005675929 },
            { "emotion": "surprise", "score": -0.02556022 },
            { "emotion": "fear", "score": -0.14499822 },
            { "emotion": "angry", "score": -0.19491306 },
            { "emotion": "disgust", "score": -0.31617728 }
        ],
        "gender": { "gender": "FEMALE", "score": -2.7309942 },
        "score": -0.000696103
    },
    "id": { "face": 123, "gallery": "hello" },
    "meta": {
        "camera": "openspace",
        "labels": ["foo", "bar"],
        "timestamp": "1543837276"
    },
    "normalized_id": "123_bg2hcupjisghl6pee0ag.png"
}

Сравнение лиц

/verify POST

Данный метод сравнивает два лица, проверяя, принадлежит ли изображенное на них лицо одному и тому же человеку, и возвращает степень уверенности алгоритма в совпадении лиц (степень схожести).

Параметры query string:

  • "face1": первое лицо, результат работы /detect POST (хранится в memcached) или сохраненное в базе данных.

  • "face2": второе лицо, результат работы /detect POST (хранится в memcached) или сохраненное в базе данных.

Возвращает:

Степень уверенности алгоритма в совпадении лиц.

Пример

Запрос №1. Сравнение 2-х результатов детекции

curl -s 'http://172.17.47.19:18411/v2/verify?face1=detection:bd3hv4tt8f66ph0eag1g&face2=detection:bd3hv8dt8f66ph0eag2g' | jq

Ответ

{
  "confidence": 0.92764723
}

Запрос №2. Сравнение результата детекции с лицом из галереи

curl -s 'http://172.17.47.19:18411/v2/verify?face1=detection:bd3hv4tt8f66ph0eag1g&face2=face:galleryname/2' | jq

Ответ

{
  "confidence": 0.999996
}