Перейти к основному содержимому
Версия: 3.25.1 (последняя)

Распознавание лиц

Обзор

Face SDK позволяет выполнять следующие операции сравнения биометрических шаблонов лиц:

  • Верификация (1:1) — сравнение двух шаблонов лиц на принадлежность одному и тому же человеку (сравнение двух лиц).
  • Идентификация (1:N) — сравнение одного биометрического шаблона лица с другими шаблонами лиц (поиск лица по базе лиц).

Результатом распознавания является оценка сходства между сравниваемыми шаблонами.

Процессинг-блоки

  • FACE_TEMPLATE_EXTRACTOR — извлекает биометрический шаблон лица из изображения.
  • VERIFICATION_MODULE — сравнивает два шаблона лиц, проверяя их схожесть.
  • MATCHER_MODULE — ищет похожие лица в базе данных.

Классы для работы с модулями распознавания лиц

  • ContextTemplate - хранит биометрический шаблон лица в бинарном формате. Используется для сравнения и поиска в модулях распознавания.
  • DynamicTemplateIndex - хранит коллекцию биометрических шаблонов для быстрого поиска в MATCHER_MODULE. Поддерживает добавление и удаление шаблонов без пересоздания индекса.

Модификации и версии процессинг-блоков распознавания лиц

Модификация процессинг-блока FACE_TEMPLATE_EXTRACTOR определяет скорость генерации шаблона и точность распознавания. Чем выше скорость работы, тем ниже точность.

Серии модификаций:

  • 30-1000 - стандартные модификации, подходят для ПК.
  • 30m-1000m - оптимизированы для мобильных процессоров, работают быстрее, но с меньшей точностью по сравнению со стандартной серией.
МодификацияВерсияРазмер шаблона (байты)Создание шаблона (мс)
PC*
Создание шаблона (мс)
Mobile**
301 280 19 50
501 288 31 92
1001 280 68 212
10001 296 611 2200

* – Intel(R) Xeon(R) CPU E5-2680 v4 @ 2.40GHz.
** – MediaTek Helio G95.

примечание

Модификация по умолчанию - "1000".

Для процессинг-блоков VERIFICATION_MODULE и MATCHER_MODULE модификация и версия определяют тип шаблона, с которым данные модули будут работать.

Описание ContextTemplate и DynamicTemplateIndex

ContextTemplate

Создание ContextTemplate

Экземпляр ContextTemplate можно создать несколькими способами:

  1. Получить после работы модуля FACE_TEMPLATE_EXTRACTOR.
  2. Вызвать метод service.loadContextTemplate. Этот метод позволяет загрузить объект ContextTemplate из бинарного потока данных.

Методы ContextTemplate

// Получение названия модификации шаблона
std::string getMethodName() const;

// Размер шаблона
size_t size() const;

// Сохранение в бинарный поток данных
void save(std::ostream &binary_stream) const;

DynamicTemplateIndex

Создание DynamicTemplateIndex

Для создания экземпляра DynamicTemplateIndex используется метод service.createDynamicTemplateIndex. Метод принимает контейнер-Контекст с следующими параметрами:

  • max_license_count (тип: long) - Максимальное количество шаблонов, которое может содержать индекс. Не может превышать лимит, указанный в лицензии. Значение по умолчанию — 100.
  • capacity (тип: long) - Резервирует место для шаблонов в индексе. Значение по умолчанию — max_license_count.
  • async (тип: bool) - Если указано true, включается асинхронный режим для операций добавления и удаления шаблонов. Это позволяет выполнять эти операции параллельно. Режим находится в бета-версии.
  • model_version (тип: string) - Модификация и версия модели, например, "1000_1". Этот параметр определяет, с шаблонами какой модификации модуля FACE_TEMPLATE_EXTRACTOR будет работать индекс.

Методы DynamicTemplateIndex

// Получение названия метода шаблонов в базе
std::string getMethodName() const;

// Количество шаблонов в базе
size_t size() const;

// Текущая вместимость базы
size_t capacity() const;

// Получение UUID шаблона по индексу в базе
std::string getUUID(size_t index) const;

// Получение шаблона по UUID
pbio::ContextTemplate::Ptr at(const std::string& uuid) const;

// Получение шаблона по индексу в базе
pbio::ContextTemplate::Ptr at(int64_t index) const;

// Добавление шаблона в базу
void add(pbio::Template::Ptr templ, const std::string& uuid);
void add(const std::vector<pbio::Template::Ptr>& templates, const std::vector<std::string>& uuids);

void add(pbio::ContextTemplate::Ptr templ, const std::string& uuid);
void add(const std::vector<pbio::ContextTemplate::Ptr>& templates, const std::vector<std::string>& uuids);

// Удаление шаблона из базы по UUID
void remove(const std::string& uuid);
void remove(const std::vector<std::string>& uuids);

// Слияние баз шаблонов
// otherIndex становится невалидным
void concat(DynamicTemplateIndex::Ptr otherIndex);

Спецификация процессинг-блоков распознавания

Перечень настраиваемых параметров процессинг-блоков

Face template extractor

  1. Входной контейнер Context должен содержать бинарное изображение и массив объектов, полученных после работы процессинг-блоков детекции лица и фиттера:
Нажмите, чтобы развернуть спецификацию входного контейнера Context
{
"image" : {
"format": "NDARRAY",
"blob": "data pointer",
"dtype": "uint8_t",
"shape": [height, width, channels]
},
"objects": [{
"id": {"type": "long", "minimum": 0},
"class": "face",
"confidence": {"double", "minimum": 0, "maximum": 1},
"bbox": [x1, y2, x2, y2]
"keypoints": {
"left_eye_brow_left": {"proj" : [x, y]},
"left_eye_brow_up": {"proj" : [x, y]},
"left_eye_brow_right": {"proj" : [x, y]},
"right_eye_brow_left": {"proj" : [x, y]},
"right_eye_brow_up": {"proj" : [x, y]},
"right_eye_brow_right": {"proj" : [x, y]},
"left_eye_left": {"proj" : [x, y]},
"left_eye": {"proj" : [x, y]},
"left_eye_right": {"proj" : [x, y]},
"right_eye_left": {"proj" : [x, y]},
"right_eye": {"proj" : [x, y]},
"right_eye_right": {"proj" : [x, y]},
"left_ear_bottom": {"proj" : [x, y]},
"nose_left": {"proj" : [x, y]},
"nose": {"proj" : [x, y]},
"nose_right": {"proj" : [x, y]},
"right_ear_bottom": {"proj" : [x, y]},
"mouth_left": {"proj" : [x, y]},
"mouth": {"proj" : [x, y]},
"mouth_right": {"proj" : [x, y]},
"chin": {"proj" : [x, y]},
"points": ["proj": [x, y]]
}
}]
}
  1. После выполнения процессинг-блока оценки в каждом объекте массива "objects" поле "face_template" будет содержать биометрический шаблон в поле "template" и уникальный идентификатор в поле "uuid". Шаблон хранится в объекте класса ContextTemplate. Выданный uuid можно использовать для работы с DynamicTemplateIndex или заменить на собственный идентификатор.
Нажмите, чтобы развернуть спецификацию выходного контейнера Context
[{
"keypoints": {},
"face_template": {
"template": {"ContextTemplate"},
"uuid": {"string"}
}
}]

Verification module

  1. Входной контейнер Context должен содержать два биометрических шаблона записанные в поля "template1" и "template2". Тип шаблона должен соответствовать модификации процессинг-блока.
Нажмите, чтобы развернуть спецификацию входного контейнера Context
{
"template1" : {
"template": {"ContextTemplate"}
},
"template2" : {
"template": {"ContextTemplate"}
}
}
  1. После вызова процессинг-блока верификации результат будет помещён в "result".
Нажмите, чтобы развернуть спецификацию выходного контейнера Context
{
"template2": {},
"result": {
"distance": {"double", "minimum": 0},
"score": {"double", "minimum": 0, "maximum": 1},
"far": {"double", "minimum": 0, "maximum": 1},
"frr": {"double", "minimum": 0, "maximum": 1},
}
}

Matcher module

  1. Входной контейнер Context должен содержать объект класса DynamicTemplateIndex в поле "template_index" и набор искомых биометрических шаблонов, помещённых в другой объект класса DynamicTemplateIndex в поле "queries", либо один шаблон в виде объекта класса ContextTemplate.
Нажмите, чтобы развернуть спецификацию входного контейнера Context
{
"queries": {"DynamicTemplateIndex"},
"template_index": {"DynamicTemplateIndex"}
}

ИЛИ

{
"queries": {"ContextTemplate"},
"template_index": {"DynamicTemplateIndex"}
}
  1. После вызова процессинг-блока верификации результат будет помещён в массив "results".
Нажмите, чтобы развернуть спецификацию выходного контейнера Context
{
"template_index": {"DynamicTemplateIndex"}
"result": [{
"index": {"long", "minimum": 0}
"uuid": {"string"}
"distance": {"double", "minimum": 0},
"score": {"double", "minimum": 0, "maximum": 1},
"far": {"double", "minimum": 0, "maximum": 1},
"frr": {"double", "minimum": 0, "maximum": 1},
}]
}

Результаты распознавания

  • distance – расстояние между сравниваемыми векторами шаблонов. Чем меньше значение, тем выше уверенность в корректном распознавании.
  • far – вероятность ошибочных подтверждений, когда система принимает изображения разных людей за изображение одного и того же человека.
  • frr – вероятность ошибочных отказов, когда система принимает два изображения одного и того же человека за изображения разных людей.
  • score – степень схожести лиц от 0 (0%) до 1 (100%). Высокая степень схожести означает, что два биометрических шаблона принадлежат одному и тому же человеку.
  • index - позиция найденого шаблона внутри объекта DynamicTemplateIndex. (только для MATCHER_MODULE)
  • uuid - уникальный идентификатор шаблона, переданный при добавлении в DynamicTemplateIndex. (только для MATCHER_MODULE)

Примеры работы с процессинг-блоками распознавания лиц

Извлечение шаблонов лица

Для получения шаблона лица на изображении выполните следующие действия:

  1. Создайте конфигурационный Context-контейнер и укажите значения "unit_type" для "FACE_TEMPLATE_EXTRACTOR" и "modification" и "version" интересующей вас модификации.

    Пример создания процессинг-блока можно найти здесь

    Перечень настраиваемых параметров процессинг-блоков

  2. Передайте Context-контейнер, полученный после работы процессинг-блоков детекции лица и фиттера.

  3. Вызовите процессинг-блок извлечения шаблонов лица.

auto configCtx = service->createContext();
configCtx["unit_type"] = "FACE_TEMPLATE_EXTRACTOR";
configCtx["modification"] = "{modification}";
pbio::ProcessingBlock blockFaceExtractor = service->createProcessingBlock(configCtx);

//------------------
// создание процессинг-блока и Context-контейнера с бинарным изображением
//------------------

faceDetector(ioData)
faceFitter(ioData)
blockFaceExtractor(ioData);

Сохранение шаблона лица

Для сохранения шаблона лица в файле выполните следующие действия:

  1. Получите объект ContextTemplate из данных.

  2. Откройте бинарный файл для записи.

  3. Сохраните шаблон в файл с помощью метода save().

pbio::ContextTemplate::Ptr face_template = ioData["objects"][0]["face_template"]["template"].getContextTemplate();

std::ofstream out("template.bin", std::ios::binary);

face_template->save(out);

Загрузка шаблона лица

Для загрузки шаблона лица из файла выполните следующие действия:

  1. Откройте файл для чтения бинарных данных.

  2. Загрузите шаблон с помощью loadContextTemplate().

std::ifstream input("template.bin", std::ios::binary);

pbio::ContextTemplate::Ptr face_template = service->loadContextTemplate(input);

Верификация лиц

  1. Создайте конфигурационный Context-контейнер и укажите значения "unit_type" для "VERIFICATION_MODULE" и "modification" и "version" интересующей вас модификации.

  2. Сформируйте Context-контейнер и добавьте биометрические шаблоны в поля "template1" и "template2":.

    • Вы можете добавить содержимое поля "face_template", полученного при вызове модуля "FACE_TEMPLATE_EXTRACTOR", в поля "template1" и "template2"
    • Либо создать новый Context-контейнер и добавить в него объект класса ContextTemplate.
  3. Вызовите процессинг-блок верификации.

pbio::Context verificationConfig = service->createContext();
verificationConfig["unit_type"] = "VERIFICATION_MODULE";
verificationConfig["modification"] = "{modification}";

pbio::ProcessingBlock verificationModule = service->createProcessingBlock(verificationConfig);

pbio::Context verificationData = service->createContext();
verificationData["template1"] = ioData["objects"][0]["face_template"];
verificationData["template2"]["template"] = face_template;

verificationModule(verificationData);

Формирование DynamicTemplateIndex

Для формирование DynamicTemplateIndex выполните следующие действия:

  1. Сформируйте контейнер-Context и укажите поля "model_version" и "max_license_count" и передайте этот контейнер в метод createDynamicTemplateIndex

  2. Добавьте шаблоны в индекс с помощью метода add(), передав ContextTemplate и uuid

pbio::Context indexConfig = service->createContext();

indexConfig["model_version"] = "{modification}_1";
indexConfig["max_license_count"] = 1000;

pbio::DynamicTemplateIndex::Ptr template_index = service->createDynamicTemplateIndex(indexConfig);

for (const pbio::Context& object : ioData["objects"])
{
template_index->add(object["face_template"]["template"].getContextTemplate(), "<uuid>");
}

примечание

Передаваемый uuid должен быть уникальным

Поиск лиц по базе

  1. Создайте конфигурационный Context-контейнер и укажите значения "unit_type" для "MATCHER_MODULE" и "modification" и "version" интересующей вас модификации.

  2. Сформируйте входной Context-контейнер согласно спецификации для "MATCHER_MODULE".

  3. Вызовите процессинг-блок для поиска по базе.

pbio::Context matcherConfig = service->createContext();
matcherConfig["unit_type"] = "MATCHER_MODULE";
matcherConfig["modification"] = "{modification}";

pbio::ProcessingBlock matcherModule = service->createProcessingBlock(matcherConfig);

// Forming the input Context container for matcherModule
pbio::Context matcherData = service->createContext();
matcherData["template_index"] = template_index;
matcherData["queries"] = ioData["objects"][0]["face_template"]["template"];

matcherModule(matcherData);