1. Конфигурация

После установки SDK и получения софтверной лицензии, вам необходимо настроить файл кофигурации. См. Конфигурация.

Перед созданием основных объектов SDK (например, Diametrix::Detector, Diametrix::Extractor, Diametrix::Matcher, etc.) вам нужно создать объект Diametrix::Config.
Создать объект Diametrix::Config

auto cfg = Diametrix::makeConfig(configFileName);

configFileName - путь, по которому у вас лежит файл конфигурации.

Вы можете найти пример файла конфигурации в пакете SDK - файл config_default.cfg

2. Изображения и их декодирование

SDK поддерживает работу с изображениями в форматах WSQ, jpg, bmp, png. Также вы можете использовать уже декодированные изображения 8bit (см. требования ГОСТ Р ИСО/МЭК 19794-4-2014 - пункт 6.2). См. другие требования к изображениям на странице Требования
Работа с изображениями в SDK ведется через объект Diametrix::Image.
Для декодирования изображений вам прежде всего нужно создать объект Diametrix::Decoder:

auto decoder = Diametrix::createDecoder(cfg);

где cfg - это Diametrix::Config.
После этого вы можете декодировать изображения с жесткого диска:

auto image = decoder->read(imageFileName);

или из памяти:

auto image = decoder->decode(size, data);

Если у вас уже есть декодированные изображения 8raw bit (согласно требованиям ГОСТ Р ИСО/МЭК 19794-4-2014 - пункт 6.2) создайте Diametrix::Image:

auto image = Diametrix::constructImage(width, height, data);

3. Детектирование отпечатков пальцев

Первый шаг в распознавании отпечатков пальцев - это детектирование, а именно поиск и локализация отпечатков на изображении.
Прежде всего вам нужно создать объект Diametrix::Detector:

auto detector = Diametrix::createDetector(cfg);

Для запуска детектирования на изображении:

std::vector<std::shared_ptr<Diametrix::Detection>> detections;

detector->detect(image, 500, 0.333, detections);

где:
500 - это dpi изображения
0.333 - это конфиденс (или степень уверенности) детектора

Diametrix::Detector возвращает объекты Diametrix::Detection. Вы можете работать с изображениями, на которых больше одного отпечатков. В таком случае Diametrix::Detector вернет несколько детекций. Все детекции возвращаются с рамкой детекции (Diametrix::Detection::bbox()) и конфиденсом детекции. На основании этой информации вы можете выбрать нужную детекцию или детекции.

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

Создать объект Diametrix::Detection, с отпечатком пальца в центре кадра:

Diametrix::Point fingerprintCenter;
fingerprintCenter.x = image->width() / 2;
fingerprintCenter.y = image->height() / 2;
auto detection = Diametrix::constructDetection(image, 500, fingerprintCenter, 0);

где:
500 - это dpi
0 - это угол наклона отпечатка относительно вертикальной оси.

Конфиденс детектора

Конфиденс - это значение между 0,0001 и 0,9999, которое отражает степень уверенности детектора в достоверности детекции, где 0,0001 - это скорее всого ложная детекция и 0,9999 - это скорее всего отпечаток.
Рекомендованное значение порога конфиденса: от 0.33 до 0.5, но данное значение может зависеть от вашей задачи и характера изображений, с которыми вы работаете. Мы рекомендуем провести тестирование на вашей базе данных для выбора наилучшего порога детектирования.

4. Построение биометрического шаблона

Для построения биометрического шаблона используется объект Diametrix::Detection. Биометрический шаблон - это компактный проприетарный дескриптор, который используется для последующего сравнения и распознавания.
Размер биометрического шаблона: 512 байт. Размер шаблона всегда одинаков и не зависит от изображения, из которого он был извлечен.

Прежде всего создайте объект Diametrix::Extractor:

auto extractor = Diametrix::createExtractor(cfg);

Создайте объект Diametrix::Template, используя объект Diametrix::Detection:

std::shared_ptr<Diametrix::Template> template0;

extractor->extract(detection, template0);

Вы можете сериализовать шаблон в памяти:

char * buff = new char[template0->serializedSize()];

template0->serialize(buff);

и загрузить сериализованный шаблон:

auto template1 = Diametrix::deserializeTemplate(template0->serializedSize(), buff);

5. Сравнение

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

1:1 (верификация)
1:N (идентификация)
M:N (идентификация в пакетном режиме)

Объект Diametrix::Matcher оперирует объектами Diametrix::Template и Diametrix::TemplateDB. Diametrix::TemplateDB - это галерея шаблонов, которая используется для сравнения 1:N или M:N.

Diametrix::TemplateDB хранится в оперативной памяти (RAM).

Сравнение 1:1 возвращает степень похожести двух шаблонов (matching score)
Сравнение 1:N возвращает ТОП K лучших результатов сравнения из Diametrix::TemplateDB, отсортированных в порядке от большего к меньшему (от высокой степени похожести к низкой). "K" может быть любым числом, не превышающим размер галереи шаблонов Diametrix::TemplateDB.
Пакетный режим сравнения M:N позволяет достичь лучшей производительности по сравнению с режимом 1:N. Консультируйтесь с нашими специалистами для выбора оптимального размера пакета для вашего оборудования и ваших задач.

Прежде всего создайте объект Diametrix::Matcher:

auto matcher = Diametrix::createMatcher(cfg);

Сравнение двух шаблонов друг с другом (1:1)

float similarity = matcher->match(template0, template1);

Создание объекта Diametrix::TemplateDB:

size_t maxSize = 10000;
int batchSize = 1;
auto templateDB = Diametrix::constructTemplateDB(maxSize, batchSize);

Внимание! Указание maxSize требуется для корректного выделения оперативной памяти. Также учитывайте, что максимальный размер вашей галереи шаблонов (TemplateDB) может быть ограничен параметрами лицензии.

Добавить шаблон в Diametrix::TemplateDB:

std::shared_ptr<Diametrix::Template> template0;
long long id;
templateDB->add(template0, id);

Внимание! В SDK нет проверки на повторы ID. Это означает, что у пользователя есть техническая возможность добавить два разных шаблона с одинаковыми ID.
Если вы хотите удалить шаблон из галереи шаблонов, то вам следует удалить и пересоздать галерею шаблонов. Функционал удаления реализован таким образом из-за оптимизации производительности (операции удаления и создания заново быстрее, чем удаление конкретного шаблона из памяти, что особенно заметно при работе с большими галереями).

Получить все ID шаблонов из объекта Diametrix::TemplateDB:

std::vector<long long> ids;

templateDB->getLoadedIDs(ids);

ID будут возвращены с копиями, если копии существуют

Проверить, есть ли конкретный ID в объекте Diametrix::TemplateDB:

const long long id;

bool result = templateDB->isLoaded(id);

Сравнение шаблона с галереей шаблонов Diametrix::TemplateDB (1:N) с выдачей ТОП-10 лучших результатов сравнения:

std::vector<std::shared_ptr<Diametrix::Template>> batch;
batch.push_back(template0);
 
std::vector<std::vector<std::pair<long long, float>>> results;
matcher->matchK(batch, templateDB, 10, 0.1, results);

Степень совпадения (matching score)

Matching score - это нативное значение, которое измеряет степень похожести двух биометрических шаблонов. Score в SDK распознавания отпечатков пальцев Diametrix напрямую привязан к FAR (false acceptance rate) и его значения соответствуют -logFAR, что означает:

Score 4: вероятность того, что данные отпечатки разные - 1 на 10 000.
Score 5: вероятность того, что данные отпечатки разные - 1 на 100 000.
Score 6: вероятность того, что данные отпечатки разные - 1 на 1 000 000, и так далее.

Для того, чтобы задать порог сравнения, укажите score: совпадения со score, выше указанного, вы увидите в результатах сравнения. Например, порог 6 означает, что SDK вернет все результаты сравнения со степенью похожести (matching score) от 6 и выше. Выбор порога зависит от вашей задачи и допустимого уровня ложноположительных сравнений (FAR).
Подробнее об ошибках первого и второго рода (false acceptance rate и false rejection rate), которые характеризуют качество работы любого биометрического алгоритма, можно прочитать здесь.