API процессинг-блоков
API процессинг-блоков (блоков обработки) является альтернативным масштабируемым интерфейсом, замещающим существующие API, для более легкой интеграции возможностей SDK в ваше приложение.
Основные возможности API процессинг-блоков:
- Объединение многих компонентов в единую интеграцию
- Простота и легкость изучения
- Быстрое внедрение
- Долгосрочная поддержка и обновления
API процессинг-блоков является частью будущих решений 3DiVi. Для получения более подробной информации обратитесь к торговому представителю 3DiVi.
Набор процессинг-блоков
Сэмпл processing_block_demo демонстрирует использование API процессинг-блоков.
Human Body Detector
Human Body Detector — это компонент, используемый для обнаружения человеческих тел на изображении. Результатом обнаружения является ограничивающий прямоугольник (рамка) вокруг обнаруженного тела.
Временные характеристики Human Body Detector:
- CPU (Intel Core i5-9400 @ 4.10GHz Turbo, 1 core) ~170ms
- GPU (GeForce GTX 1080 Ti) ~16ms
Информацию об использовании 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) ~55ms
- GPU (GeForce GTX 1080 Ti) ~15ms
Информацию об использовании Object Detector вы можете найти на странице Детекция объектов.
Emotion Estimator
Emotion Estimator — компонент, используемый для оценки эмоций человека по кадрированному изображению лица. Результатом оценки является числовое значения степени проявления для каждой оцениваемой эмоции.
Временные характеристики Emotion Estimator:
- CPU (Intel Core i5-9400 @ 4.10GHz Turbo, 1 core) ~18ms
- GPU (GeForce GTX 1080 Ti) ~8ms
Информацию об использовании Emotion Estimator вы можете найти на странице Оценка эмоций.
Gender Estimator
Gender Estimator — это компонент, используемый для оценки пола человека по кадрированному изображению с лицом. Результат оценки — вердикт о половой идентичности.
Временные характеристики Gender Estimator:
- CPU (Intel Core i5-9400 @ 4.10GHz Turbo, 1 core) ~5ms
- GPU (GeForce GTX 1080 Ti) ~1ms
Информацию об использовании Gender Estimator вы можете найти на странице Оценка пола.
2D RGB Liveness Estimator
2D RGB Liveness Estimator - компонент, используемый для оценки принадлежности лица на RGB-изображении реальному человеку. Результатом обнаружения является ограничивающий прямоугольник (рамка) вокруг обнаруженного лица, вердикт о принадлежности реальному человеку и числовое значение вероятности. Информацию об использовании 2D RGB Liveness Estimator вы можете найти на странице Оценка принадлежности лица реальному человеку.
Context
Ключевой концепцией API процессинг-блоков является использование контейнеров Context.
Context - это гетерогенный контейнер, состоящий из набора иерархически организованных данных, представленных как пары ключ-значение. Ближайший аналог Context - объект JSON. Каждый объект Context может содержать: скалярный объект (integer, real, boolean, string), указатель на область памяти, массив объектов Context, ассоциативный контейнер пар <string, Context> с неограниченной вложенностью.
Как создать и использовать Context
Создайте Context-контейнер:
auto array_elem0 = service->createContext();
- Общий набор операций с Context:
- создание ассоциативного контейнера по ключу
["key"]
на пустом контейнере Context:
array_elem0["name"] = "Julius Zeleny"; // put string
array_elem0["phone"] = 11111111111l; // put integer (long)
array_elem0["social_score"] = 0.999; // put double
array_elem0["verified"] = true; // put bool
- getters:
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);
- итерации по массиву:
// get by index
ASSERT_EQ( array[0]["phone"].getLong(), 11111111111l );
// iterate with index
size_t array_sz = array.size();
for(size_t i = 0; i < array_sz; ++i)
array[i]["phone"];
// or with iterators
for(auto iter = array.begin(); iter != array.end(); ++iter)
(*iter)["phone"]; // deference returns nested Context
// with foreach
for(auto val : array)
val["phone"];
- операции со вложенными ассоциативными контейнерами:
auto full = service->createContext();
full["friends"] = std::move(array); // move assignment without copying
// access nested object
ASSERT_EQ( full["friends"][0]["social_score"].getDouble(), 0.999 );
// iterate over associative containers values
for(auto iter = full.begin(); iter != full.end(); ++iter) {
iter.key(); // get key value from iterator
(*iter)[0]["social_score"].getDouble(); // get value
}
// with foreach
for(auto val : full)
val[0]["social_score"].getDouble();
- другие удобные методы Context:
void clear()
bool contains(const std::string& key) // for an assosiative container
Context operator[](size_t index) // for a sequence array, access specified element with bounds checking
Context operator[](const std::string& key) // for an assosiative container, access or insert
Context at(const std::string& key) // for an assosiative container, with bounds checking
size_t size() // return elements count for a container
bool isNone() // is empty
bool isArray() // is a sequence array
bool isObject() // is an assosiative container
bool isLong(), isDouble(), isString(), isBool() // check if contains a certain scalar type
Бинарный формат изображений
Большинство процессинг-блоков выполняют операции с контейнерами 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-изображением
Создайте контейнер Context для изображения используя метод
createContext()
:
auto imgCtx = service->createContext();
- Прочитайте 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);
- 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);
- 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
(см. описание выбранного процессинг-блока).
Создайте контейнер Context:
auto configCtx = service->createContext();
- Определите значения ключей контейнера 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";
// опционально, значение "true" для ускорения процессинг-блоков на GPU (только для блоков с поддержкой CUDA)
configCtx["use_cuda"] = false;
- Создание процессинг-блока:
pbio::ProcessingBlock processing_block = service->createProcessingBlock(configCtx);
Ускорение на GPU
Процессинг-блоки могут быть использованы с ускорением на GPU. Для этого необходимо определить ключ "use_cuda"
со значением true
для Context-контейнера блока обработчика
(см. Создание процессинг-блока).
- Системные требования:
- Nvidia GPU Driver >= 410.48
- CUDA Toolkit 10.1
- cuDNN 7
- (Для Windows) Microsoft Visual C++ Redistributable for Visual Studio 2019
- Требования к оборудованию:
- графический процессор (GPU) с поддержкой CUDA (NVIDIA GTX 1050 Ti и выше)