Кластеры лиц, силуэтов, автомобилей

FindFace Multi поддерживает автоматическую кластеризацию объектов одного происхождения:

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

Совокупные галереи кластеров лиц, силуэтов и автомобилей доступны на вкладке Кластеры.

Примечание

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

Важно

По умолчанию кластеризация объектов отключена. Включите и настройте ее через файл конфигурации /etc/findface-security/config.py.

В этом разделе:

Алгоритмы кластеризации
Включение и настройка кластеризации
Работа с галереями кластеров
Статическая галерея кластеров
Ручная кластеризация

Алгоритмы кластеризации 

FindFace Multi использует следующие алгоритмы кластеризации объектов:

Кластеризация в реальном времени. Данный алгоритм кластеризации обрабатывает эпизоды с целью выбора подходящих изображений объектов и кластеризует выбранные изображения. Он работает на лету после закрытия эпизода. Результаты кластеризации отображаются динамически на вкладке Кластеры и в соответствующей карточке.

Для кластеризации используются не все эпизоды. Если эпизод соответствует всем требованиям (см. подробности ниже), система формирует кластер следующим образом:
- Выбирает событие наилучшего качества.
- Создает новую сущность cluster event (кластерное событие) в основной базе данных PostgreSQL. Сущность содержит метаданные выбранного события, вектор признаков объекта и миниатюру объекта, а также ссылку на родительский эпизод.
- Ищет похожий центроид объекта в галерее cluster_events базы данных векторов признаков Tarantool. Центроид объекта — это виртуальный вектор признаков, усредненный по всем объектам-близнецам, которые были обнаружены на данный момент (например, центроид лица — это вектор признаков, усредненный по всем изображениям лица одного и того же человека). Система обновляет похожий центроид, используя новое событие, если такой центроид найден. Иначе создается новый центроид.
Кластеризация по расписанию. Данный алгоритм кластеризации перерабатывает и пересматривает кластерные события, созданные во время кластеризации в реальном времени. Использование данного алгоритма улучшает качество кластерного центроида, поскольку в этом случае центроид усредняется по большему массиву накопленных векторов признаков. Результаты кластеризации по расписанию отображаются после каждой запланированной итерации на вкладке Кластеры и в соответствующей карточке.

Расписание задается в формате RRULE в параметре CLUSTERS_CLUSTERIZATION_SCHEDULE файла конфигурации /etc/findface-security/config.py. Предпочтительны ночные часы, так как запланированная кластеризация занимает много времени и ресурсов ЦП.

Важно

Кластеризация по расписанию полностью перезаписывает содержимое галерей кластеров, включая идентификаторы. Вы можете закрепить определенные кластеры, включив настройки CLUSTERS_AUTO_PIN_HEURISTICS и PIN_MATCHED_CLUSTERS (см. ниже).

Включение и настройка кластеризации 

По умолчанию кластеризация отключена. Чтобы включить и настроить ее, выполните следующие действия:

Откройте файл конфигурации /etc/findface-security/config.py. Найдите раздел Clusters configuration.

sudo vi /etc/findface-security/config.py


# -- Clusters configuration --
    'ENABLE_NIGHT_CLUSTERIZATION': True,
    'ENABLE_REALTIME_CLUSTERIZATION': True,
    # rrule (recurrence rule) for scheduling clusters clusterization
    'CLUSTERIZATION_SCHEDULE': 'RRULE:FREQ=DAILY;INTERVAL=1;WKST=MO;BYHOUR=0;BYMINUTE=0',
    # clusterize only selected objects types (for realtime and nightly clusterization)
    # available are: face, body, car
    'CLUSTERIZE_OBJECT_TYPES': ['face','body','car'],
    # skip clusterization if unpinned cluster events count is greater than this value
    'CLUSTERIZATION_MAX_CLUSTER_EVENTS': None,
    # cluster event to cluster matching confidence threshold
    'FACE_CLUSTER_CONFIDENCE_THRESHOLD': 0.723,  # model: [kiwi_320]
    'BODY_CLUSTER_CONFIDENCE_THRESHOLD': 0.65,  # model: [andariel]
    'CAR_CLUSTER_CONFIDENCE_THRESHOLD': 0.65,  # model: [alonso]
    # minimum required event quality for cluster creation
    'FACE_CLUSTER_EVENT_MIN_QUALITY': 0.45,  # model: [quality.v1]
    'BODY_CLUSTER_EVENT_MIN_QUALITY': 0.6,  # model: [pedattr.quality.v0]
    'CAR_CLUSTER_EVENT_MIN_QUALITY': 0.73,  # model: [carattr.quality.v0]
    # minimum required number events in episode for cluster creation
    'FACE_CLUSTER_EVENT_MIN_EPISODE_EVENTS': 1,
    'BODY_CLUSTER_EVENT_MIN_EPISODE_EVENTS': 1,
    'CAR_CLUSTER_EVENT_MIN_EPISODE_EVENTS': 1,
    # coefficient of dependence of the clustering threshold on the person event's quality
    'FACE_CLUSTER_SOFT_CLUSTERIZATION_COEFFICIENT': 0.1,
    'BODY_CLUSTER_SOFT_CLUSTERIZATION_COEFFICIENT': 0.1,
    'CAR_CLUSTER_SOFT_CLUSTERIZATION_COEFFICIENT': 0.1,
    # match with clusters when no card objects matches found
    'MATCH_CLUSTERS': False,
    # create auto cards for unmatched clusters
    'CREATE_AUTO_CARDS': False,
    # pinned clusters keep their id and events after reclusterization
    'CLUSTERS_AUTO_PIN_HEURISTICS': {
        'face': {
            # pin clusters with `value` minimum cluster events
            'min_events': {'enabled': True, 'value': 10},
            # cluster's centroid similarity confidence is less then
            'max_centroid_similarity_threshold': {'enabled': True, 'value': 0.55},
            # minimum average event's quality
            'min_average_events_quality': {'enabled': True, 'value': 0.45},
        },
        'body': {},
        'car': {},
    },
    # always pin clusters with matched events (not affected by heuristics above)
    'PIN_MATCHED_CLUSTERS': False,

Включите кластеризацию в реальном времени, установив ENABLE_REALTIME_CLUSTERIZATION: True .
При необходимости включите кластеризацию по расписанию, установив ENABLE_NIGHT_CLUSTERIZATION: True.

Важно

Включать кластеризацию по расписанию имеет смысл только в том случае, если включена кластеризация в реальном времени. В противном случае система не сформирует ни одного нового кластера, поскольку только кластеризация в реальном времени является поставщиком уникальных кластерных событий.
```
...
# -- Clusters configuration --
    'ENABLE_NIGHT_CLUSTERIZATION': True,
    'ENABLE_REALTIME_CLUSTERIZATION': True,
...
```
При необходимости задайте рекуррентное правило (RRULE), задающее расписание плановой кластеризации. Если правило не задано, кластеризация автоматически начинается в 00:00 GMT.

Совет

См. калькулятор RRULE.
```
# rrule (recurrence rule) for scheduling clusters clusterization
'CLUSTERIZATION_SCHEDULE': 'RRULE:FREQ=DAILY;INTERVAL=1;WKST=MO;BYHOUR=0;BYMINUTE=0',
```
По умолчанию система формирует только кластеры лиц. Для того чтобы включить формирование кластеров силуэтов и автомобилей, добавьте соответствующие типы объектов в следующую строку:
```
# available are: face, body, car
'CLUSTERIZE_OBJECT_TYPES': ['face','body','car'],
```
При необходимости измените минимальное количество событий в используемых для кластеризации эпизодах. По умолчанию данное количество равно 1. Сделайте это отдельно для каждого типа объекта.
```
# minimum required number events in episode for cluster creation
'FACE_CLUSTER_EVENT_MIN_EPISODE_EVENTS': 3,
'BODY_CLUSTER_EVENT_MIN_EPISODE_EVENTS': 3,
'CAR_CLUSTER_EVENT_MIN_EPISODE_EVENTS': 2,
```
При необходимости измените минимальное качество используемых для кластеризации изображений объектов. Сделайте это отдельно для каждого типа объекта.

Примечание

Поскольку данная настройка требует наличия высокого уровня знаний и опыта, мы настоятельно рекомендуем предварительно проконсультироваться с нашими техническими специалистами.
```
# minimum required event quality for cluster creation
'FACE_CLUSTER_EVENT_MIN_QUALITY': 0.45,  # model: [quality.v1]
'BODY_CLUSTER_EVENT_MIN_QUALITY': 0.6,  # model: [pedattr.quality.v0]
'CAR_CLUSTER_EVENT_MIN_QUALITY': 0.73,  # model: [carattr.quality.v0]
```
При необходимости измените порог уверенности алгоритма в совпадении объектов при сопоставлении кластерного события и кластера.

Предупреждение

Перед изменением данного параметра проконсультируйтесь с нашими специалистами по адресу support@ntechlab.com.
```
# cluster event to cluster matching confidence threshold
'FACE_CLUSTER_CONFIDENCE_THRESHOLD': 0.723,  # model: [kiwi_320]
'BODY_CLUSTER_CONFIDENCE_THRESHOLD': 0.65,  # model: [andariel]
'CAR_CLUSTER_CONFIDENCE_THRESHOLD': 0.65,  # model: [alonso]
```
После обнаружения объекта на видеоизображении система ищет в картотеке совпадающие с ним объекты. Установите ’MATCH_CLUSTERS’: True, чтобы система могла искать совпадения в галерее кластеров, если она не нашла подходящей карточки в картотеке. В этом случае система будет уведомлять вас всякий раз, когда объект совпадает с ранее созданным кластером.
```
# match with clusters when no card objects matches found
'MATCH_CLUSTERS': True,
```
Установите ’CREATE_AUTO_CARDS’: True, чтобы автоматически создавать новые карточки для кластеров, у которых отсутствуют совпадения в картотеке. Подробнее см. Автокарточки и заполненные карточки.
```
# create auto cards for unmatched clusters
'CREATE_AUTO_CARDS': True,
```
Кластеризация по расписанию полностью перезаписывает все созданные кластеры. Вы можете «закрепить» определенные кластеры, т. е. сохранить их и связанные кластерные события, включая идентификаторы, нетронутыми. Для этого используйте следующие настройки:

Примечание

Данные настройки являются независимыми. При необходимости используйте обе.

Примечание

Данные настройки не влияют на кластеризацию в реальном времени. Она продолжит создавать новые кластерные события для закрепленных кластеров.
- CLUSTERS_AUTO_PIN_HEURISTICS: установите True или False для следующих параметров и укажите соответствующие значения:
  
  Примечание
  
  При необходимости сделайте это для каждого типа объекта.
  - min_events: закрепить кластер, когда количество связанных с ним кластерных событий превысит заданное минимальное значение.
  - max_centroid_similarity_threshold: закрепить кластер, если сходство между его центроидом и центроидами других кластеров меньше заданного порога. Если кластер похож на некоторые другие кластеры, существует вероятность того, что данные кластеры принадлежат одному человеку/автомобилю. В этом случае система не закрепит такой кластер, чтобы иметь возможность провести повторную кластеризацию. Напротив, непохожие кластеры будут закреплены.
  - min_average_events_quality: закрепить кластер, если среднее качество ассоциированных кластерных событий больше заданного минимального значения.
```
 # pinned clusters keep their id and events after reclusterization
 'CLUSTERS_AUTO_PIN_HEURISTICS': {
     'face': {
         # pin clusters with `value` minimum cluster events
         'min_events': {'enabled': True, 'value': 10},
         # cluster's centroid similarity confidence is less then
         'max_centroid_similarity_threshold': {'enabled': True, 'value': 0.55},
         # minimum average event's quality
         'min_average_events_quality': {'enabled': True, 'value': 0.45},
     },
     'body': {},
     'car': {},
},
```
- Включите параметр PIN_MATCHED_CLUSTERS, чтобы закрепить кластеры и связанные с ними кластерные события, для которых есть совпадения в картотеке.
```
 # always pin clusters with matched events (not affected by heuristics above)
'PIN_MATCHED_CLUSTERS': True,
```
При необходимости укажите максимальное количество кластерных событий в кластерах, которые являются «незакрепленными». По достижении данного количества кластеризация по расписанию будет автоматически отключена.
```
# skip clusterization if unpinned cluster events count is greater than this value
'CLUSTERIZATION_MAX_CLUSTER_EVENTS': None,
```
Перезапустите сервис findface-security. В веб-интерфейсе FindFace Multi появится вкладка Кластеры.
```
sudo systemctl restart findface-security.service
```

Работа с галереями кластеров 

Просмотр кластеров. Фильтры 

Для того чтобы просмотреть галереи кластеров, перейдите на вкладку Кластеры.

При работе с галереями кластеров используйте следующие фильтры:

Примечание

Некоторые фильтры из приведенного ниже списка могут быть скрыты, в зависимости от активированного функционала распознавания.

Карточка: отобразить только кластеры по определенной карточке.
Камеры: отобразить только кластеры по определенной камере.
Группы камер: отобразить только кластеры по определенной группе камер.
Списки наблюдения: отобразить только кластеры по определенному списку наблюдения.
Старт, Конец: отобразить только кластеры, сформированные в определенный период времени.
ID: отобразить кластер с определенным ID.
Досье: отобразить кластеры в зависимости от того, имеют ли они связанную карточку, автоматически сгенерированную или заполненную (подробное объяснение см. в разделе Автокарточки и заполненные карточки).

Специальные фильтры для кластеров лиц

Возраст: отобразить кластеры с людьми определенного возраста.
Пол: отобразить кластеры с людьми заданного пола.
Эмоции: отобразить кластеры с заданными эмоциями.
Очки: фильтровать кластеры по наличию очков на лице.
Борода: фильтровать кластеры по наличию бороды.
Liveness: фильтровать кластеры по liveness лица.
Медицинская маска: фильтровать кластеры по наличию медицинской маски.

Специальные фильтры для кластеров силуэтов

Головной убор: отобразить только кластеры с людьми в головном уборе заданного типа: шапка/шляпа/кепка, капюшон/платок, без головного убора.
Верх одежды: отобразить только те кластеры, в которых человек носит одежду верха заданной обобщенной категории: с длинными рукавами, с короткими рукавами, без рукавов.
Тип верха одежды: отобразить только те кластеры, в которых человек носит одежду верха заданного типа: куртка, пальто, жилет, толстовка, футболка, рубашка, платье.
Цвет верха одежды: отобразить только кластеры с людьми, одетыми в одежду заданного цвета (верх).
Низ одежды: отобразить только те кластеры, в которых человек носит одежду низа заданного типа: брюки, юбка, шорты, неопределенный.
Цвет низа одежды: отобразить только кластеры с людьми, одетыми в одежду заданного цвета (низ).

Специальные фильтры для кластеров автомобилей

Тип кузова: отобразить кластеры с автомобилями заданного типа кузова.
Цвет автомобиля: отобразить кластеры с автомобилями заданного цвета.
Марка: фильтровать кластеры по марке автомобиля.
Модель: фильтровать кластеры по модели автомобиля.
Спецтранспорт: отобразить только кластеры с транспортными средствами, принадлежащими заданному типу: полиция, скорая помощь, спасательные службы, такси, прочие.

Объединение и удаление кластеров 

Для того чтобы вручную объединить несколько кластеров, выберите их один за другим и нажмите Объединить.

Для того чтобы удалить кластер, выберите его и нажмите Удалить.

Просмотр связанных кластерных событий. Фильтры 

Щелкните по нужному кластеру, чтобы просмотреть связанные с ним кластерные события. Вы будете перенаправлены на страницу События кластера с соответствующим значением в фильтре ID кластера.

Набор фильтров для работы с кластерными событиями аналогичен набору фильтров для кластеров.

Статическая галерея кластеров 

Иногда бывает необходимо завершить кластеризацию объектов в определенный момент времени, а затем оперировать статической галереей сформированных кластеров.

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

Откройте файл конфигурации /etc/findface-security/config.py.
```
sudo vi /etc/findface-security/config.py
```
В раздел SERVICES вручную добавьте строку ”clusters: True, как показано в примере ниже:
```
...
SERVICES = {
    "ffsecurity": {
        ...
        "clusters": True,
    }
...
```
Отключите процессы кластеризации в реальном времени и по расписанию.
```
...
'ENABLE_NIGHT_CLUSTERIZATION': False,
'ENABLE_REALTIME_CLUSTERIZATION': False,
```
Перезапустите сервис findface-security.
```
sudo systemctl restart findface-security.service
```

Ручная кластеризация 

Для того чтобы вручную запустить процесс кластеризации, используйте утилиту run_clusterization.

Вы можете вызвать справку по опциям run_clusterization, выполнив следующую команду:

sudo findface-security run_clusterization --help
usage: findface-security run_clusterization [-h]
                                            [--object-types OBJECT_TYPES [OBJECT_TYPES ...]]
                                            [--force]
                                            [--configuration CONFIGURATION]
                                            [--version] [-v {0,1,2,3}]
                                            [--settings SETTINGS]
                                            [--pythonpath PYTHONPATH]
                                            [--traceback] [--no-color]
                                            [--force-color] [--skip-checks]

optional arguments:
  -h, --help            show this help message and exit
  --object-types OBJECT_TYPES [OBJECT_TYPES ...]
                        Clusterize selected object types. Uses
                        CLUSTERIZE_OBJECT_TYPES from config if not provided.
                        Allowed types: face, body, car
  --force               Force clusterization even if
                        CLUSTERIZATION_MAX_CLUSTER_EVENTS condition is met
  --configuration CONFIGURATION
                        The name of the configuration class to load, e.g.
                        "Development". If this isn't provided, the
                        DJANGO_CONFIGURATION environment variable will be
                        used.
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.
  --skip-checks         Skip system checks.

Данная утилита позволяет по отдельности запускать кластеризацию лиц, силуэтов и автомобилей, а также выполнять принудительную кластеризацию, если максимальное количество событий кластера превышает значение параметра CLUSTERIZATION_MAX_CLUSTER_EVENTS (см. Включение и настройка кластеризации ). Например, чтобы принудительно запустить кластеризацию лиц, выполните следующую команду:

sudo findface-security run_clusterization --object-types face --force

См.также