Перейти к основному содержимому
Версия: 3.17.3

API процессинг-блоков

API процессинг-блоков (блоков обработки) является альтернативным масштабируемым интерфейсом, замещающим существующие API, для более легкой интеграции возможностей SDK в ваше приложение.

Основные возможности API процессинг-блоков:

  • Объединение многих компонентов в единую интеграцию
  • Простота и легкость изучения
  • Быстрое внедрение
  • Долгосрочная поддержка и обновления

API процессинг-блоков является частью будущих решений 3DiVi. Для получения более подробной информации обратитесь к торговому представителю 3DiVi.

Набор процессинг-блоков​

примечание

Примеры использования API процессинг-блоков демонстрируются в:

Face Detector​

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

Временные характеристики Face Detector:

  • CPU (Intel Core i5-9400 @ 4.10GHz Turbo, 1 core) ~115мс
  • GPU (GeForce GTX 1080 Ti) ~16мс

Вы можете найти информацию об использовании Face Detector на странице Детекция лиц.

Human Body Detector​

Human Body Detector — это компонент, используемый для обнаружения человеческих тел на изображении. Результатом обнаружения является ограничивающий прямоугольник (рамка) вокруг обнаруженного тела.

Временные характеристики Human Body Detector:

  • CPU (Intel Core i5-9400 @ 4.10GHz Turbo, 1 core) ~170мс
  • GPU (GeForce GTX 1080 Ti) ~16мс

Информацию об использовании Human Body Detector вы можете найти на странице Детекция тел.

Object Detector​

Object Detector — это компонент, используемый для обнаружения объектов разных типов на изображении. Результатом обнаружения является ограничивающий прямоугольник (рамка) вокруг обнаруженного объекта с классификационным именем. Object Detector используется для детекции на изображении объектов следующих классов: "body" - человеческое тело, "bicycle" - велосипед, "car" - автомобиль, "motorcycle" - мотоцикл, "bus" - автобус, "train" - поезд, "truck" - грузовик, "traffic_light" - светофор, "fire_hydrant" - пожарный гидрант, "stop_sign" - сигнал "стоп", "bird" - птица, "cat" - кошка, "dog" - собака, "horse" - лошадь, "sheep" - овца, "cow" - корова, "bear" - медведь, "backpack" - рюкзак, "umbrella" - зонт, "handbag"- сумка, "suitcase" - чемодан, "sports_ball" - спортивный мяч, "baseball_bat" - бейсбольная бита, "skateboard"- скейтборд, "tennis_racket" - теннисная ракетка, "bottle" - бутылка, "wine_glass" - бокал вина, "cup" - чашка, "fork" - вилка, "knife" - нож, "laptop" - ноутбук, "phone" - телефон, "book" - книга, "scissors" - ножницы.

Временные характеристики Object Detector:

  • CPU (Intel Core i5-11400H @ 2.70GHz, 1 core) ~1440мс
  • GPU (GeForce GTX 1080 Ti) ~35,6мс

Информацию об использовании детектора объектов и список объектов для обнаружения вы можете найти на странице Детекция объектов.

Human Pose Estimator​

Human Pose Estimator — это компонент, используемый для вычисления ключевых точек скелета человеческого тела на изображении. Результатом обнаружения является список ключевых точек с их координатами и оценкой достоверности обнаруженного человеческого тела. Human Pose Estimator используется для обнаружения следующих ключевых точек на изображении: "nose" - нос, "left_eye" - левый глаз, "right_eye" - правый глаз, "left_ear" - левое ухо, "right_ear" - правое ухо, "left_shoulder" - левое плечо, "right_shoulder" - правое плечо, "left_elbow" - левый локоть, "right_elbow" - правый локоть, "left_wrist" - левое запястье, "right_wrist" - правое запястье, "left_hip" - левое бедро, "right_hip" - правое бедро, "left_knee" - левое колено, "right_knee" - правое колено, "left_ankle" - левая лодыжка, "right_ankle" - правая лодыжка

Временные характеристики Human Pose Estimator:

  • CPU (Intel Core i5-11400H @ 2.70GHz, 1 core) ~55мс
  • GPU (GeForce GTX 1080 Ti) ~15мс

Вы можете найти информацию об использовании Human Pose Estimator на странице Оценка позы человека.

Emotion Estimator​

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

Временные характеристики Emotion Estimator:

  • CPU (Intel Core i5-9400 @ 4.10GHz Turbo, 1 core) ~18мс
  • GPU (GeForce GTX 1080 Ti) ~8мс

Информацию об использовании Emotion Estimator вы можете найти на странице Оценка эмоций.

Age Estimator​

Age Estimator — компонент, используемый для оценки возраста человека по кадрированному изображению с лицом. Результатом оценки является возраст человека.

Временные характеристики Age Estimator:

  • CPU (Intel Core i5-9400 @ 4.10GHz Turbo, 1 core) ~5мс
  • GPU (GeForce GTX 1080 Ti) ~1мс

Вы можете найти информацию об использовании Age Estimator на странице Оценка возраста.

Gender Estimator​

Gender Estimator — компонент, используемый для оценки пола человека по кадрированному изображению с лицом. Результат оценки — вердикт о половой идентичности.

Временные характеристики Gender Estimator:

  • CPU (Intel Core i5-9400 @ 4.10GHz Turbo, 1 core) ~5мс
  • GPU (GeForce GTX 1080 Ti) ~1мс

Информацию об использовании Gender Estimator вы можете найти на странице Оценка пола.

Mask Estimator​

Mask Estimator — компонент, используемый для определения наличия или отсутствия медицинской маски на лице человека с изображения. Результат оценки — вердикт о наличии маски.

Информацию об использовании Mask Estimator вы можете найти на странице Детекция маски.

2D RGB Liveness Estimator​

2D RGB Liveness Estimator — компонент, используемый для оценки принадлежности лица на RGB-изображении реальному человеку. Результатом обнаружения является ограничивающий прямоугольник (рамка) вокруг обнаруженного лица, вердикт о принадлежности реальному человеку и числовое значение вероятности.

Информацию об использовании 2D RGB Liveness Estimator вы можете найти на странице Оценка принадлежности лица реальному человеку.

Quality Assessment Estimator​

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

Информацию об использовании Quality Assessment Estimator вы можете найти на странице Блок оценки качества.

Context​

Ключевой концепцией API процессинг-блоков является использование контейнеров Context.

Context - это гетерогенный контейнер, состоящий из набора иерархически организованных данных, представленных как пары ключ-значение. Ближайший аналог Context - объект JSON. Каждый объект Context может содержать: скалярный объект (integer, real, boolean, string), указатель на область памяти, массив объектов Context, ассоциативный контейнер пар <string, Context> с неограниченной вложенностью.

Как создать и использовать Context​

  1. Создайте FacerecService.

  2. Создайте Context-контейнер:

auto array_elem0 = service->createContext();
  1. Общий набор операций с Context:
  • создание ассоциативного контейнера по ключу ["key"] на пустом контейнере Context:
    array_elem0["name"] = "Julius Zeleny";      // передать string
    array_elem0["phone"] = 11111111111l;        // передать integer (long)
    array_elem0["social_score"] = 0.999;        // передать double
    array_elem0["verified"] = true;             // передать bool
  • геттеры:
    ASSERT_EQ( array_elem0["name"].getString(), "Julius Zeleny" );
    ASSERT_EQ( array_elem0["phone"].getLong(), 11111111111l );
    ASSERT_EQ( array_elem0["social_score"].getDouble(),  0.999 );
    ASSERT_EQ( array_elem0["verified"].getBool(), true );
  • создание массива вызовом метода push_back на пустом контейнере Context:
    auto service->createContext();
    array.push_back(array_elem0);
  • итерации по массиву:

    // получить значение по индексу
    ASSERT_EQ( array[0]["phone"].getLong(), 11111111111l );

    // выполнить итерацию с индексом
    size_t array_sz = array.size();    
    for(size_t i = 0; i < array_sz; ++i)
        array[i]["phone"];

    // или с итераторами
    for(auto iter = array.begin(); iter != array.end(); ++iter)
        (*iter)["phone"]; // возвращается вложенный Context

    // или с foreach
    for(auto val : array)
        val["phone"];
  • операции со вложенными ассоциативными контейнерами:
    auto full = service->createContext();
    full["friends"] = std::move(array); // использование семантики перемещения без копирования

    // доступ к вложенному объекту
    ASSERT_EQ( full["friends"][0]["social_score"].getDouble(), 0.999 );
    
    // перебор значений ассоциативного контейнера  
    for(auto iter = full.begin(); iter != full.end(); ++iter) {
        iter.key(); // получить значение ключа из итератора 
        (*iter)[0]["social_score"].getDouble(); // получить значение 
    }
        
    // с foreach 
    for(auto val : full)
        val[0]["social_score"].getDouble();
  • другие удобные методы Context:
    void clear()
    bool contains(const std::string& key)       // для ассоциативного контейнера
    Context operator[](size_t index)            // для последовательного массива, элемент с указанием доступа и проверкой границ 
    Context operator[](const std::string& key)  // для ассоциативного контейнера, доступ или вставка данных
    Context at(const std::string& key)          // для ассоциативного контейнера, с проверкой границ 
    size_t size()                               // возвращается число элементов контейнера 
    bool isNone()                               // проверка на пустоту
    bool isArray()                              // проверка на последовательный массив
    bool isObject()                             // проверка на ассоциативный контейнер
    bool isLong(), isDouble(), isString(), isBool() // проверка на содержание скалярного типа данных

Бинарный формат изображений​

Большинство процессинг-блоков выполняют операции с контейнерами Context, содержащими изображения в бинарном формате:

/*
{
 "image" : { "format": "NDARRAY",
             "blob": <data pointer>,
             "dtype": "uint8_t",
             "shape": [height, width, channels] }
}
*/

Ключ "blob" содержит умный указатель на данные. Указатель устанавливается функцией void Context::setDataPtr(void* ptr, int copy_sz), где copy_sz - размер памяти в байтах, который будет скопирован, и затем автоматически освобождается когда заканчивается время жизни объекта Context. Копирование не будет выполнено, если в качестве аргумента copy_sz будет передан 0. В этом случае объект Context не контролирует время жизни объекта, на который он указывает.

Ключ "blob" содержит умный указатель на данные. Указатель устанавливается функцией void Context::setDataPtr(void* ptr, int copy_sz), где copy_sz - это размер памяти в байтах, которая будет скопирована и далее автоматически освобождена. Копирование не выполняется если в качестве аргумента copy_sz передан 0.

Вы также можете аллоцировать "сырую" память, например, чтобы скопировать данные позже, передавая nullptr и размер в качестве аргументов setDataPtr.

Ключ "dtype" может содержать одно из следующих значений: "uint8_t", "int8_t", "uint16_t", "int16_t", "int32_t", "float", "double". Каждому значению соответствует определенный тип OpenCV: CV_8U, CV_8S, CV_16U, CV_16S, CV_32S, CV_32F, CV_64F.

Создание контейнера Context c RGB-изображением​

  1. Создайте FacerecService.

  2. Создайте контейнер Context для изображения используя метод createContext(): 

auto imgCtx = service->createContext();
  1. Прочитайте RGB-изображение из файла:
// read the image from file
std::string input_image_path = "<path_to_image>";
cv::Mat image = cv::imread(input_image_path, cv::IMREAD_COLOR);
cv::Mat input_image;
cv::cvtColor(image, input_image, cv::COLOR_BGR2RGB);
  1. a. Поместите изображение в контейнер ИЛИ
// using pbio::context_utils::putImage(Context& ctx, unsigned char* data, size_t height, size_t width, pbio::IRawImage::Format format, bool copy)
pbio::context_utils::putImage(imgCtx, input_image.data, input_image.rows, input_image.cols, pbio::IRawImage::FORMAT_RGB, true);

  1. b. ИЛИ скопируйте изображение из pbio::RawImage, pbio::CVRawImage, pbio::InternalImageBuffer в бинарный формат и положите его в контейнер Context:
// constructing pbio::RawImage
pbio::RawImage input_rawimg(input_image.cols, input_image.rows, pbio::RawImage::Format::FORMAT_RGB, input_image.data);

// using void putImage(Context& ctx, const RawImage& raw_image)
pbio::context_utils::putImage(imgCtx, input_rawimg);

Создание процессинг-блока​

В этом разделе описаны шаги по созданию любого процессинг блока. Для создания блока необходимо указать соответствующие значения для ключей unit_type и model_path (см. описание выбранного процессинг-блока).

  1. Создайте FacerecService.

  2. Создайте контейнер Context:

auto configCtx = service->createContext();
  1. Определите значения ключей контейнера Context, специфичных для выбранного процессинг-блока:
// обязательно, укажите имя процессинг-блока
configCtx["unit_type"] = "<name_of_processing_block>";

// обязательно, укажите путь до файла модели процессинг-блока 
configCtx["model_path"] = "<path_to_model_file>";

// библиотека onnxruntime по умолчанию расположена в директории дистрибутива Face SDK: "lib" для платформы Linux или "bin" для платформы Windows
// вы можете задать ваш собственный путь до библиотеки onnxruntime
// если путь до библиотеки не указан, то будет использоваться стандартный порядок поиска, используемый в данной ОС
configCtx["ONNXRuntime"]["library_path"] = "../lib"; // для Linux
configCtx["ONNXRuntime"]["library_path"] = "../bin"; // для Windows

// опционально, значение "true" для ускорения процессинг-блоков на GPU (только для блоков с поддержкой CUDA) 
configCtx["use_cuda"] = false;
  1. Создание процессинг-блока:
pbio::ProcessingBlock processing_block = service->createProcessingBlock(configCtx);

Ускорение на GPU​

Процессинг-блоки могут быть использованы с ускорением на GPU. Для этого необходимо определить ключ "use_cuda" со значением true для Context-контейнера блока обработчика (см. Создание процессинг-блока).

Требования​