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

Обработка видеопотока

Интерфейсный объект VideoWorker может быть использован для:

Объект VideoWorker берет на себя всю необходимую синхронизацию и контроль потоков, вам необходимо только подавать кадры видеопотока и реализовать несколько коллбэков.

Пример использования объекта VideoWorker см. в video_recognition_demo.
Узнайте, как детектировать и отслеживать лица на видеопотоке в нашем туториале Детекция и трекинг лиц на видеопотоке.
Узнайте, как распознавать лица на видеопотоке в нашем туториале Распознавание лиц на видеопотоке.

Детекция лиц​

Примечание: Узнайте, как детектировать лица в масках, в нашем туториале.

Объект VideoWorker может быть создан с помощью метода FacerecService.createVideoWorker.

Примеры​

pbio::FacerecService::Config video_worker_config("video_worker_lbf.xml");
video_worker_config.overrideParameter("search_k", 3);
pbio::VideoWorker::Ptr video_worker = service->createVideoWorker(
    pbio::VideoWorker::Params()
        .video_worker_config(video_worker_config)
        .recognizer_ini_file(recognizer_config)
        .streams_count(streams_count)
        .processing_threads_count(processing_threads_count)
        .matching_threads_count(matching_threads_count)
        .age_gender_estimation_threads_count(age_gender_estimation_threads_count)
        .emotions_estimation_threads_count(emotions_estimation_threads_count)
        .short_time_identification_enabled(enable_sti)
        .short_time_identification_distance_threshold(sti_recognition_threshold)
        .short_time_identification_outdate_time_seconds(sti_outdate_time)
    );

Где:

  • video_worker_config – путь до конфигурационного файла для VideoWorker или объект FacerecService.Config.
  • video_worker_params – параметры конструктора VideoWorker.
  • recognizer_config – конфигурационный файл для используемого распознавателя (см. Идентификация лиц).
  • streams_count – количество видеопотоков, для каждого из которых будет создан поток трекинга.
  • processing_threads_count – количество потоков для создания шаблонов. Эти потоки общие для всех видеопотоков и распределяют ресурсы равномерно по все видеопотокам независимо от их загруженности (за исключение видеопотоков без лиц в кадре).
  • matching_threads_count – количество потоков для сравнения шаблонов, созданных из видеопотоков, с базой. Как и потоки обработки, они распределяют работу равномерно по всем видеопотокам.
  • age_gender_estimation_threads_count – количество потоков для определения пола и возраста. Как и потоки обработки, они распределяют работу равномерно по всем видеопотокам.
  • emotions_estimation_threads_count – количество потоков для определения эмоций. Как и потоки обработки, они распределяют работу равномерно по всем видеопотокам.
  • enable_sti – флаг, включающий кратковременную идентификацию.
  • sti_recognition_threshold – порог распознавания для кратковременной идентификации.
  • sti_outdate_time – длина временного интервала для кратковременной идентификации в секундах.

Существует три конфигурационных файла, использующие алгоритм трекинга из common_video_capturer.xml:

  • video_worker.xml с набором точек esr
  • video_worker_lbf.xml с набором точек singlelbf
  • video_worker_fda.xml с набором точек fda

и три конфигурационных файла, использующие алгоритм трекинга из fda_tracker_capturer.xml:

  • video_worker_fdatracker.xml с набором точек fda
  • video_worker_fdatracker_fake_detector.xml с набором точек fda
  • video_worker_fdatracker_blf_fda.xml с набором точек fda

(см. Антропометрические точки, Класс Capturer)

В случае, если VideoWorker используется только для детекции лиц, указываются параметры matching_thread=0 и processing_thread=0, и потребляется обычная лицензия Face Detector. Для создания компонента Face Detector для одного потока необходимо указать параметр streams_count=1.

Для подачи кадров видеопотока используйте метод VideoWorker.addVideoFrame. Этот метод потокобезопасен, поэтому можно подавать кадры из разных потоков, созданных для каждого видеопотока, без дополнительной синхронизации. Метод возвращает целочисленный идентификатор кадра, который будет использоваться в коллбэках для обозначения этого кадра.

Детекция лиц осуществляется посредством использования двух коллбэков:

  • VideoWorker.TrackingCallbackU возвращает результаты трекинга. Этот коллбэк вызывается каждый раз, когда кадр был обработан конвейером трекинга. Tracking-коллбэк будет вызван с frame_id равным X не раньше, чем VideoWorker.addVideoFrame вернет значение X + N – 1, где N – значение, которое вернул VideoWorker.getTrackingConveyorSize. Tracking-коллбэки с одинаковым идентификатором stream_id вызываются в порядке возрастания frame_id. Поэтому если был получен коллбэк с stream_id=2 и frame_id=102 сразу после коллбэка с stream_id=2 и frame_id=100, значит, кадр с frame_id=101 был пропущен для видеопотока 2. Большинство сэмплов созданы с кадра frame_id, но некоторые могут быть получены с предыдущих кадров. Используйте метод RawSample.getFrameID для того, чтобы определить, какому кадру сэмпл принадлежит на самом деле. Чтобы подписаться на этот коллбэк, используйте метод VideoWorker.addTrackingCallbackU, чтобы отписаться – метод VideoWorker.removeTrackingCallback, подав callback_id, который вы получили от VideoWorker.addTrackingCallbackU.

  • VideoWorker.TrackingLostCallbackU возвращает лучший сэмпл и шаблон лица, когда трекинг потерян (например, когда человек вышел из кадра). Лучший сэмпл может быть пустым, если включен конфигурационный параметр weak_tracks_in_tracking_callback. Гарантируется, что этот коллбэк будет последним для пары <stream_id, track_id> (track_id равен sample.getID() для сэмпла в любом VideoWorker-коллбэке). Т.е. после него ни один Tracking-, MatchFound- или TrackingLost-коллбэк для видеопотока stream_id не может содержать сэмпла с этим же идентификатором track_id. Также гарантируется, что для каждой пары <stream_id, track_id>, которая была упомянута в Tracking-коллбэке, существует ровно один TrackingLost-коллбэк, за исключением треков, удаленных в процессе VideoWorker.resetStream – для них TrackingLost-коллбэк не будет вызван. Используйте возвращаемое значение VideoWorker.resetStream для освобождения памяти, выделенной для этих треков. Чтобы подписаться на этот коллбэк, используйте метод VideoWorker.addTrackingLostCallbackU. Чтобы отписаться от коллбэка, используйте метод VideoWorker.removeTrackingLostCallback, предоставив callback_id, который вы получили от метода VideoWorker.addTrackingLostCallbackU.

Примечание: Исключения, возникшие в коллбэках, будут перехвачены и сгенерированы заново в методе VideoWorker.checkExceptions, поэтому не забывайте регулярно вызывать метод VideoWorker.checkExceptions для контроля ошибок.

Предупреждение: Не вызывайте методы, которые изменяют состояние VideoWorker внутри коллбэков, во избежание взаимной блокировки. Т.е. безопасными для вызова в коллбэках являются только методы VideoWorker.getMethodName и VideoWorker.getStreamsCount.

Создание шаблонов​

Если помимо детекции требуется создание шаблонов, указываются параметры matching_thread=0 и processing_thread>0, и потребляется лицензия Video Engine Standard. Для создания компонента Video Engine Standard для одного потока необходимо указать параметры streams_count=1, processing_threads_count=1, matching_threads_count=0.

Вы можете отключить / включить создание шаблонов для конкретного видеопотока с помощью методов VideoWorker.disableProcessingOnStream и VideoWorker.enableProcessingOnStream. При старте создание шаблонов включено для всех видеопотоков.

Коллбэк VideoWorker.TemplateCreatedCallbackU возвращает результаты генерации шаблонов. Этот коллбэк вызывается каждый раз, когда внутри VideoWorker создается шаблон. Гарантируется, что этот коллбэк будет вызван после как минимум одного Tracking-коллбэка и перед TrackingLost-коллбэком с теми же stream_id и track_id (track_id = sample->getID()). Чтобы подписаться на этот коллбэк, используйте метод VideoWorker.addTemplateCreatedCallbackU. Чтобы отписаться от коллбэка, используйте метод VideoWorker.removeTemplateCreatedCallback, предоставив callback_id, который вы получили от метода VideoWorker.addTemplateCreatedCallbackU.

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

В случае, если требуется детекция лиц, создание шаблонов и сравнение их с базой (распознавание), указываются параметры matching_thread>0 и processing_thread>0, и потребляется лицензия Video Engine Extended. Для создания компонента Video Engine Extended для одного потока необходимо указать параметры streams_count=1, processing_threads_count=1, matching_threads_count=1.

Для задания или изменения базы используйте метод VideoWorker.setDatabase. Он может быть вызван в любое время.

Коллбэк VideoWorker.MatchFoundCallbackU возвращает результат сравнения с базой. Когда для трекаемого лица создается шаблон, он сравнивается с каждым шаблоном из базы, и если расстояние до ближайшего элемента оказывается меньше порога distance_threshold, указанного в этом элементе, то фиксируется совпадение. Этот коллбэк вызывается после N последовательных совпадений с элементами, относящимися к одному и тому же человеку.

Также выставив значение тэга <not_found_match_found_callback> равным 1 можно включить вызов этого коллбэка после N последовательных несовпадений (т.е. когда ближайший элемент оказывается дальше его порога distance_threshold). В этом случае идентификатор match_result первого элемента в MatchFoundCallbackData.search_result будет с нулевым расстоянием, а идентификаторы person_id и element_id будут равны VideoWorker.MATCH_NOT_FOUND_ID. Число N может быть задано в конфигурационном файле в тэге <consecutive_match_count_for_match_found_callback>.

Гарантируется, что этот коллбэк будет вызван после как минимум одного Tracking-коллбэка и перед TrackingLost-коллбэком с тем же stream_id и track_id (track_id = sample->getID()). Чтобы подписаться на этот коллбэк, используйте метод VideoWorker.addMatchFoundCallbackU. Чтобы отписаться от коллбэка, используйте метод VideoWorker.removeMatchFoundCallback, предоставив callback_id, который вы получили от метода VideoWorker.addMatchFoundCallbackU. Максимальное количество элементов, возвращаемое в MatchFoundCallbackData.search_result, устанавливается в конфигурационном файле под тэгом search_k и может быть изменено с помощью объекта FacerecService.Config.overrideParameter, например: video_worker_config.overrideParameter(search_k, 3);

Определение пола, возраста и эмоций​

Для определения пола и возраста указывается параметр age_gender_estimation_threads_count > 0. Для определения эмоций указывается параметр emotions_estimation_threads_count > 0. Данные о поле, возрасте и эмоциях приходят в коллбэк VideoWorker.TrackingCallbackU. Данные об эмоциях обновляются постоянно. Данные о поле и возрасте пересчитываются только в том случае, если найден сэмпл с лучшим качеством. Сразу после создания VideoWorker определение пола, возраста и эмоций включено.

Отключить определение пола, возраста и эмоций на конкретном потоке можно при помощи методов:

  • VideoWorker.disableAgeGenderEstimationOnStream (пол и возраст)
  • VideoWorker.disableEmotionsEstimationOnStream (эмоции)

Снова включить определение пола, возраста и эмоций на конкретном потоке можно при помощи методов:

  • VideoWorker.enableAgeGenderEstimationOnStream (пол и возраст)
  • VideoWorker.enableEmotionsEstimationOnStream (эмоции)

Оценка принадлежности лица реальному человеку​

Активная (сценарная) проверка​

Для включения данной проверки необходимо выставить параметр enable_active_liveness конфигурационного файла объекта VideoWorker в 1. После этого все лица для идентификации будут проходить несколько проверок. Доступны следующие проверки (определены в структуре LivenessChecks):

  • SMILE: улыбка
  • BLINK: моргание
  • TURN_UP: поворот головы вверх
  • TURN_DOWN: поворот головы вниз
  • TURN_RIGHT: поворот головы вправо
  • TURN_LEFT: поворот головы влево
  • PERSPECTIVE: проверка изменения положения лица (необходимо приблизить лицо к камере)

Примечание: для использования проверки SMILE необходимо указать количество потоков в параметре emotions_estimation_threads_count объекта VideoWorker.

Между проверками необходимо расположить лицо нейтральном положении (фронтально по направлению к камере). При этом порядок проверок может быть случайным (данный режим выбран по умолчанию), либо задан при инициализации (путем создания списка из неповторяющихся проверок). Пример задания списка проверок представлен в демонстрационной программе video_recognition_demo (C++/C#/Java/Python).

Статус проверки приходит в свойство active_liveness_result коллбэка TrackingCallback. Данное свойство содержит в себе следующие поля:

  • verdict: статус текущей проверки (объект ActiveLiveness.Verdict)
  • type: тип проверки (объект ActiveLiveness.LivenessChecks, см. описание выше)
  • progress_level: степень уверенности прохождения проверки – число в диапазоне [0,1]

Объект ActiveLiveness.Verdict содержит в себе следующие поля:

  • ALL_CHECKS_PASSED: все проверки пройдены
  • CURRENT_CHECK_PASSED: текущая проверка пройдена
  • CHECK_FAIL: проверка не пройдена
  • WAITING_FACE_ALIGN: ожидание нейтрального положения лица
  • NOT_COMPUTED: оценка принадлежности лица реальному человеку не производится
  • IN_PROGRESS: выполняется проверка

Кратковременная идентификация​

Кратковременная идентификация (short time identification, STI) позволяет узнать трек человека, проходившего перед камерой некоторое время назад, даже если этот человек отсутвует в базе и даже если распознавание отключено. Таким образом, один и тот же человек, который в течение, например, одной минуты несколько раз выходил из кадра и снова заходил в кадр, будет идентифицироваться как одно и то же лицо.

Если кратковременная идентификация включена, VideoWorker сравнивает треки, на которых лицо было потеряно, с другими треками, на которых лицо было потеряно не более чем sti_outdate_time секунд назад. Совпавшие треки объединяются в группу sti_person. ID группы sti_person (sti_person_id) возвращается в коллбэке VideoWorker.TrackingLostCallbackU. Значение sti_person_id совпадает со значением track_id первого элемента, сформировавшего группу sti_person. Когда определенная группа sti_person превышает временной промежуток sti_outdate_time, вызывается коллбэк VideoWorker.StiPersonOutdatedCallbackU. Если лицо, находящееся в STI группе, в данный момент отслеживается, тогда VideoWorker.StiPersonOutdatedCallbackU не вызывается, а таймер для этой группы сбрасывается.

Кратковременная идентификация не влияет на использование лицензии. Для использования этой функции требуется по крайней мере один поток для создания шаблонов (processing_thread>0).

Подробная информация о параметрах объекта VideoWorker​

Нажмите, чтобы отобразить список параметров из конфигурационного файла, которые могут быть изменены с помощью метода FacerecService.Config.overrideParameter
  • max_processed_width и max_processed_height – ограничить размер изображения, подаваемого во внутренний детектор новых лиц.
  • min_size и max_size – минимальный и максимальные размер лица для детекции (размер определен для изображения, уже уменьшенного под ограничения max_processed_width и max_processed_height). Для детектора REFA возможно указание относительных значений, тогда абсолютные значения будут величины относительно ширины изображения.
  • min_neighbors – целочисленный параметр детектора. Обратите внимание на то, что большие значения требуют более высокой степени подтверждения детекции. Вы можете изменить этот параметр, исходя из ситуации, к примеру, увеличить значение, если наблюдается большое количество ложных детекций, и уменьшить значение, если большое количество лиц не детектируется. Не меняйте этот параметр, если вы не уверены.
  • min_detection_period – вещественное число, означает минимальное время (в секундах) между двумя запусками внутреннего детектора. Используется для уменьшения нагрузки на процессор. Нулевое значение отключает ограничение. Большие значения увеличивают задержку обнаружения новых лиц.
  • max_detection_period – целое число, означает максимальное время (в кадрах) между двумя запусками внутреннего детектора. Нулевое значение отключает ограничение. К примеру, если вы обрабатываете видео оффлайн, вы можете выставить значение 1, чтобы не пропустить ни одного лица.
  • consecutive_match_count_for_match_found_callback – целое число, означает количество последовательных совпадений трека с одним и тем же человеком из базы, которое будет расцениваться как верное совпадение. (см. также VideoWorker.MatchFoundCallbackU)
  • recognition_yaw_min_threshold, recognition_yaw_max_threshold, recognition_pitch_min_threshold и recognition_pitch_max_threshold – вещественные числа, означают ограничения ориентации лиц для сравнения с базой.
  • min_tracking_face_size – вещественное число, означает минимальный размер отслеживаемого лица.
  • max_tracking_face_size – вещественное число, означает максимальный размер отслеживаемого лица. Неположительное значение отключает это ограничение.
  • min_template_generation_face_size – вещественное число, означает минимальный размер лица для генерации шаблона. Лица меньшего размера будут отмечены флагом weak = true.
  • single_match_mode – целое число, 1 означает, что режим однократного распознавания включен, 0 – выключен. Если режим включен, то трек, однажды распознанный как человек из базы, больше не будет генерировать шаблоны и сравниваться с базой.
  • delayed_samples_in_tracking_callback – целое число, 1 – включен, 0 – выключен. Внутренний детектор, который обнаруживает новые лица, не успевает отрабатывать все кадры, соответственно, некоторые сэмплы могут быть получены с задержкой. В случае, если выбрано значение параметра 1, все задержанные сэмплы будут передаваться в VideoWorker.TrackingCallbackU, иначе задержанные сэмплы будут появляться, только если в противном случае будет нарушен порядок вызова коллбэков (т.е. сэмпл трека должен появиться хотя бы один раз в TrackingCallback перед вызовом TrackingLostCallback для этого трека). Используйте метод RawSample.getFrameID, чтобы определить, к какому кадру фактически относится сэмпл.
  • weak_tracks_in_tracking_callback – целое число, 1 – включен, 0 – выключен. По умолчанию этот флаг выключен, и сэмплы с флагом weak = true не передаются в Tracking-коллбэк, если на момент их создания не существовало сэмплов с таким же track_id (track_id = sample.getID()) с флагом weak = false. Если флаг weak_tracks_in_tracking_callback включен, то в Tracking-коллбэк передаются все сэмплы, поэтому TrackingLost-коллбэк может быть вызван с best_quality_sample = NULL.
  • search_k – целое число, означает максимальное количество элементов, возвращаемых в коллбэке VideoWorker.MatchFoundCallbackU, т.е. это параметр k, передаваемый внутри в Recognizer.search.
  • processing_queue_size_limit – целое число, означает максимальный размер очереди сэмплов на создание шаблонов. Служит для ограничения потребления памяти в случаях, когда новые лица появляются быстрее, чем создаются шаблоны.
  • matching_queue_size_limit – целое число, означает максимальный размер очереди шаблонов на сравнение с базой. Служит для ограничения потребления памяти в случаях когда новые шаблоны появляются быстрее, чем сравниваются с базой (это может происходить при очень большой базе).
  • recognizer_processing_less_memory_consumption – целое число, которое будет передано в качества значения флага processing_less_memory_consumption в методе FacerecService.createRecognizer для создания распознавателя.
  • not_found_match_found_callback – целое число, 1 – включен, 0 – выключен вызов VideoWorker.MatchFoundCallbackU после N последовательных несовпадений.
  • depth_data_flag – целое число, 1 – включен режим работы с кадрами глубины для подтверждения liveness (принадлежности лица реальному человеку) при распознавании, 0 – выключен. Все переопределенные параметры с префиксом depth_liveness. в имени пробрасываются в конфигурационный файл для DepthLivenessEstimator, префикс удаляется из имени. Если необходимо переопределить параметр paramname для DepthLivenessEstimator, требуется переопределить параметр depth_liveness.paramname для VideoWorker. См. FacerecService.Config.overrideParameter.
  • timestamp_distance_threshold_in_microsecs – максимальная допустимая разница между временными метками цветного изображения и соответствующего кадра глубины в микросекундах. Используется, если включен параметр depth_data_flag.
  • max_frames_number_to_synch_depth – максимальный размер очереди при синхронизации данных глубины. Используется, если включен параметр depth_data_flag.
  • max_frames_queue_size – максимальный размер очереди кадров, используемых трекером. При включенном параметре depth_data_flag рекомендуемое значение: max(3, rgbFPS / depthFPS).
  • offline_work_i_e_dont_use_time – целое число, 1 – включен, 0 – выключен. По умолчанию этот флаг выключен. При включении проверка по max_detector_confirm_wait_time не производится. Также вместо max_occlusion_time_wait используется max_occlusion_count_wait.
  • max_occlusion_time_wait – вещественное число в секундах. Когда трекер обнаруживает перекрытие лица, он удерживает позицию лица и пытается отследить его на новых кадрах в течение этого времени.
  • max_occlusion_count_wait – целое число. Означает то же, что и max_occlusion_time_wait, но в этом случае время измеряется в количестве кадров, а не в секундах. Используется, только когда установлен флаг offline_work_i_e_dont_use_time.
  • fda_max_bad_count_wait – целое число. Когда fda_tracker обнаруживает снижение качества лица, он пытается отследить это лицо с помощью трекера общего назначения (вместо алгоритма fda, разработатнного для лиц) в течение не более fda_max_bad_count_wait кадров.
  • base_angle – целое число: 0, 1, 2 или 3. Ориентация камеры: 0 – стандартная, 1 означает +90 градусов, 2 означает -90 градусов, 3 означает 180 градусов.
  • fake_detections_cnt – целое число. Количество стартовых позиций для поиска лиц при конфигурации video_worker_fdatracker_fake_detector.xml.
  • fake_detections_period – целое число. Каждая стартовая позиция будет использоваться раз в fake_detections_period кадров.
  • fake_rect_center_xN, fake_rect_center_yN, fake_rect_angleN, fake_rect_sizeN – вещественные числа. Параметры стартовых позиций. N от 0 до fake_detections_cnt – 1 включительно. fake_rect_center_xN – x координата центра относительно ширины изображения. fake_rect_center_yN – y координата центра относительно высоты изображения. fake_rect_angleN – угол roll в градусах. fake_rect_sizeN – размер относительно max(ширина изображения, высота изображения).
  • downscale_rawsamples_to_preferred_size – целое число, 1 – включен, 0 – выключен. По умолчанию этот флаг включен. Когда флаг включен, Capturer уменьшает все образцы до предпочтительного размера (см. RawSample.downscaleToPreferredSize) в целях уменьшения потребления памяти, что приводит к снижению производительности. Рекомендуется отключать downscale_rawsamples_to_preferred_size и использовать RawSample.downscaleToPreferredSize вручную для образцов, которые вам нужно сохранить или в течение длительного времени удерживать в оперативной памяти.
  • squeeze_match_found_callback_groups – целое число, 1 – включен, 0 – выключен. По умолчанию этот флаг выключен. Когда трек в первый раз получает N последовательных совпадений с одним и тем же человеком из базы, все N совпадений будут отправлены (N = значение consecutive_match_count_for_match_found_callback). т.е. будет произведено N последовательных вызовов MatchFoundCallback. Но если squeeze_match_found_callback_groups включен, то будет отправлено только одно совпадение с минимальным расстоянием до базы.
  • debug_log_enabled – целое число, 1 – включен, 0 – выключен. По умолчанию этот флаг выключен. Также этот флаг можно включить, установив значение 1 в переменную окружения FACE_SDK_VIDEOWORKER_DEBUG_LOG_ENABLED. Если этот флаг включен, то VideoWorker логирует результаты работы в std::clog.
  • need_stable_results – целое число, 1 – включен, 0 – выключен. По умолчанию этот флаг выключен. Используется для генерирации одинаковых разультатов при работе с одинаковыми данными. Отключает несколько оптимизаций, которые могут давать несколько отличающиеся результаты из-за нестабильного порядка многопоточного выполнения операций. Также включается флаг offline_work_i_e_dont_use_time и значение max_detection_period устанавливается в 1, отключается пропуск кадров (отключает ограничение от max_frames_queue_size).