Классы и методы

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

Базовые классы

class facerouter.plugin.Plugin

Данный класс предоставляет базовые методы для написания плагина, описанные в разделе Принципы написания плагина. Пользовательский класс, выполняющий роль оболочки для плагина, должен наследовать от класса Plugin.

preprocess(self, request: FrHTTPRequest, labels: typing.Mapping[str, str]) → typing.Tuple[str]

Возвращает кортеж, включающий в себя одну или несколько строк: ‘facen’, ‘gender’, ‘age’, ‘emotions’, что соответственно означает, что компонент findface-facerouter должен запросить у компонента findface-sf-api извлечение вектора признаков, распознать пол, возраст и/или эмоции.

Параметры:

• FrHTTPRequest (tornado.httpserver.HTTPRequest) – HTTP API запрос, который включает в себя дополнительный аргумент params
• labels (dictionary) – пользовательские метки из request.params

Результат:

одна или несколько строк 'facen', 'gender', 'age', 'emotions'

Тип результата:

tuple

Аргумент params FrHTTPRequest содержит следующие поля:

Параметры:

• photo (bytes) – кадр с лицом в формате JPEG
• face0 (bytes) – нормализованное изображение лица
• bbox (list of integers [[x1,y1,x2,y2]], where x1: x coordinate of the top-left corner, y1: y coordinate of the top-left corner, x2: x coordinate of the bottom-right corner, y2: y coordinate of the bottom-right corner) – координаты рамки с лицом в кадре
• cam_id (string) – id камеры
• timestamp (datetime.datetime) – временная метка кадра
• detectorParams (dictionary) – словарь со служебно-отладочной информацией от детектора
• bs_type (string) – режим поиска лучшего кадра. Доступные опции: overall (буферный режим: на сервер отправляется кадр, который был лучшим за весь период нахождения лица в поле зрения видеокамеры), realtime (режим реального времени: на сервер отправляются кадры, считающиеся лучшими в последовательных интервалах).
• labels (dictionary) – (дублирует params.labels) пользовательский набор меток кадра, который задается в параметрах задания для компонента findface-video-worker и затем присваивается кадру

process(self, request: FrHTTPRequest, photo: bytes, bbox: typing.List[int], event_id: int, detection: DetectFace)

Принимает атрибуты обнаруженного лица.

Параметры:

• request (tornado.httpserver.HTTPRequest) – HTTP API-запрос от findface-video-worker
• photo (bytes) – кадр с лицом в формате JPEG из request.params
• bbox (list of integers [[x1,y1,x2,y2]], where x1: x coordinate of the top-left corner, y1: y coordinate of the top-left corner, x2: x coordinate of the bottom-right corner, y2: y coordinate of the bottom-right corner) – координаты рамки с лицом в кадре из request.params
• event_id (uint64) – id обнаруженного на видео лица (автоматически задается компонентом findface-facerouter при получении лица от findface-video-worker). Может использоваться в качестве пользовательского идентификатора лица в базе данных.
• detection (objects.DetectFace) – результат детекции, полученный от компонента findface-sf-api, включающий в себя запрошенные параметры лица, такие как вектор признаков, пол, возраст, эмоции.

Результат:

н/п

Тип результата:

n/a

shutdown(self)

Данный метод вызывается только перед завершением работы компонента findface-facerouter.

Параметры:н/п Результат:н/п

Классы объектов

class objects.BBox

Представляет собой координаты рамки с лицом.

class objects.DetectFace

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

Параметры:

• id (string) – id результата детекции в memcached
• bbox (objects.Bbox) – координаты рамки с лицом
• features (dictionary) – информация о поле (gender), возрасте (age) и эмоциях (emotions) (опционально)

class objects.DetectResponse

Представляет собой список объектов objects.DetectionFace с дополнительным полем orientation, содержащим информацию об ориентации EXIF лица.

Параметры:orientation (EXIF orientation) – ориентация обнаруженного лица

class objects.FaceId(namedtuple('FaceId', ('gallery', 'face')))

Представляет собой объект пользовательского идентификатора лица в галерее.

Параметры:

• gallery (string) – имя галереи
• face (integer) – пользовательский идентификатор лица в галерее

class objects.Face

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

Параметры:

• id (objects.FaceId) – объект Faceid
• features (dictionary) – информация о поле, возрасте и эмоциях
• meta (dictionary) – метаданные лица
• confidence (float) – степень схожести лица с заданным биометрическим образцом

class objects.ListResponse

Представляет собой список объектов objects.Face (т. е. список результатов поиска по биометрическому образцу) с дополнительным полем next_page, содержащим информацию о следующей странице с результатами.

Параметры:next_page (string) – курсор следующей страницы с результатами поиска

Обнаружение лица и работа с галереями

class ntech.sfapi_client.client.Client

Предоставляет базовые методы для обнаружения лиц на изображении и работы с галереями.

detect(self, *, url=None, image=None, facen=False, gender=False, age=False, emotions=False, return_facen=False, autorotate=False, detector: str = None, timeout=None) → DetectResponse

Обнаруживает лица на изображении и возвращает обнаруженные лица.

Параметры:

• url (URL) – URL изображения, если вы передаете общедоступное изображение из интернета
• image (bytes) – файл PNG/JPG/WEBP, если вы передаете изображение в виде файла
• facen (boolean) – извлечь вектор признаков из обнаруженного лица. Для сохранения результата детекции в memcached передайте facen=True.
• gender (boolean) – извлечь и вернуть информацию о поле
• age (boolean) – извлечь и вернуть информацию о возрасте
• emotions (boolean) – извлечь и вернуть информацию об эмоциях
• return_facen (boolean) – вернуть вектор признаков в результате работы метода
• autorotate (boolean) – автоматически повернуть изображение в 4-х разных ориентациях для обнаружения лиц в каждой их них. Пересекающиеся направления с IOU > 0.5 будут объединены
• detector (boolean) – может принимать значение nnd или normalized. Детектор normalized используется для обработки нормализованных изображений, например, поступающих от видеодетектора лиц
• timeout (number) – максимальное время ожидания ответа от ядра FindFace в секундах (если none, используется время ожидания ответа, заданное по умолчанию)

Результат:

Результат детекции

Тип результата:

Объект DetectorResponse

gallery(self, name)

Возвращает объект sfapi_client.Gallery для последующей с ним работы (например, получения списка лиц).

Параметры:name (string) – имя галереи Результат:объект типа «галерея» Тип результата:sfapi_client.Gallery

list_galleries(self, timeout=None):

Возвращает список галерей.

Параметры:timeout (number) – максимальное время ожидания ответа от ядра FindFace в секундах (если none, используется время ожидания ответа, заданное по умолчанию) Результат:список галерей со свойствами name (имя галереи, строка) и number (количество лиц в галереи, число) Тип результата:list of GalleryListItem

class ntech.sfapi_client.gallery.Gallery

Предоставляет методы для работы с галереями и лицами в них.

list(self, *, filters: typing.Iterable[filters.Filter] = None, limit: int = 1000, sort: str = '', page=None, ignore_errors=False, timeout=None) → ListResponse

Возвращает объект типа список с лицами из галереи, удовлетворяющими заданным фильтрам. Возвращаемый объект типа список содержит дополнительное свойство next_page, которое может использоваться как значение параметра page в последующих запросах.

Параметры:

• filters (sfapi_client.filters.Filter) – список фильтров
• limit (integer) – максимальное количество лиц в ответе
• sort (string) – метод сортировки лиц. Возможные значения: id (по возрастанию id), -id (по убыванию id), -confidence (по убыванию степени схожести лиц). Сортировка по id возможна только при отключенном фильтре facen, который задает вектор признаков для поиска в базе данных (т.н. идентификация лица). Наоборот, сортировка по степени схожести лиц (confidence) возможна только при включенном фильтре facen. По умолчанию метод использует сортировку по возрастанию id (вектор признаков не задан) и по убыванию степени схожести лиц (вектор признаков задан).
• page – вернуть результаты, начиная с указанной страницы. Номер следующей страницы с результатами возвращается в ответе сервера в виде next_page.
• ignore_errors (boolean) – Игнорировать ошибку обращения к базе данных, если поиск по галерее выполняется, когда некоторые сервера базы данных недоступны. В этом случае поиск будет выполнен с использованием доступных серверов.
• timeout (number) – максимальное время ожидания ответа от ядра FindFace в секундах (если none, используется время ожидания ответа, заданное по умолчанию)

Результат:

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

Тип результата:

ListResponse object

add(self, new_id: typing.Union[int, typing.Callable], source: typing.Union[DetectFace, Face, str], *, meta: typing.Dict[str, typing.Union[int, str, typing.List[str]]] = None, regenerate_attempts=None, timeout=None) → Face

Создает лицо в галерее.

Параметры:

• new_id (integer or callable) – пользовательский идентификатор лица в базе данных. Может быть (async) callable, который возвращает id. Для генерации id может использоваться функция ctx.idgen() из контекста.
• source (sfapi_client.DetectFace, sfapi_client.Face, sfapi_client.FaceId, or string) – источник, из которого лицо добавляется в базу данных, может представлять собой лицо в базе данных или результат детекции.
• meta (dictionary) – метаданные лица. Ключи могут быть строками, а значения – целыми числами, строками или списками строк. Перед добавлением метаданных в базе данных должна быть создана соответствующая структура.
• regenerate_attempts – количество попыток генерации уникального id функцией ctx.idgen(), если new_id callable.
• timeout (number) – максимальное время ожидания ответа от ядра FindFace в секундах (если none, используется время ожидания ответа, заданное по умолчанию)

Результат:

представление созданного лица

Тип результата:

Face object

delete(self, face: typing.Union[Face, int], timeout=None) → None

Удаляет лицо из галереи.

Параметры:

• face (sfapi_client.Face, sfapi_client.FaceId or id in integer) – лицо, которое нужно удалить из базы данных
• timeout (number) – максимальное время ожидания ответа от ядра FindFace в секундах (если none, используется время ожидания ответа, заданное по умолчанию)

Результат:

None

get(self, face: typing.Union[Face, int], timeout=None) → Face

Возвращает лицо из галереи.

Параметры:

• face (sfapi_client.Face, sfapi_client.FaceId or id in integer) – лицо, которое нужно извлечь из базы данных
• timeout (number) – максимальное время ожидания ответа от ядра FindFace в секундах (если none, используется время ожидания ответа, заданное по умолчанию)

Результат:

представление лица

Тип результата:

Face object

create(self, timeout=None) → None

Создает галерею в findface-sf-api в виде объекта sfapi_client.Gallery. Объект sfapi_client.Gallery представляет собой промежуточный объект, и для работы с ним не требуется наличии галереи на сервере.

Параметры:timeout (number) – максимальное время ожидания ответа от ядра FindFace в секундах (если none, используется время ожидания ответа, заданное по умолчанию) Результат:None

drop(self, timeout=None) → None:

Удаляет галерею из findface-sf-api.

Параметры:timeout (number) – максимальное время ожидания ответа от ядра FindFace в секундах (если none, используется время ожидания ответа, заданное по умолчанию) Результат:None

update(self, face: typing.Union[Face, str], *, meta: typing.Dict[str, typing.Union[int, str, typing.List[str]]] = None, timeout=None) → Face

Редактирует метаданные лица в галерее.

Параметры:

• face (sfapi_client.Face, sfapi_client.FaceId or id in integer) – лицо, метаданные которого нужно заменить в базе данных
• meta (dictionary) – метаданные лица, которые нужно заменить. Ключи могут быть строками, а значения – целыми числами, строками или списками строк. Если поля meta не передаются или null, они не изменяются в базе данных.
• timeout (number) – максимальное время ожидания ответа от ядра FindFace в секундах (если none, используется время ожидания ответа, заданное по умолчанию)

Результат:

представление измененного лица

Тип результата:

Face object

Фильтры для поиска по базе данных

class ntech.sfapi_client.filters.Filter

Общий класс. Представляет собой сводный список фильтров (со значениями), которые должны быть применены к содержимому галереи.

serialize(self)

Метод для передачи списка фильтров со значениями в компонент findface-sf-api.

Результат:имена и значения заданных фильтров Тип результата:tuple („filtername“, [«value1», «value2»])

class ntech.sfapi_client.filters.Id

Предоставляет методы для фильтрации содержимого галереи по id. Для использования фильтра нужно напрямую вызвать соответствующий classmethod, не создавая экземпляр класса.

classmethod lte(cls, value: int) → Filter

Фильтр LTE. Выбрать все лица с id, меньшим или равным указанному.

Параметры:value (integer) – значение id Результат:имя фильтра (LTE) и его значение. Тип результата:объект класса Filter.

Пример: Id.lte(1234) выбирает лица с id, меньшим или равным 1234.

classmethod gte(cls, value: int) → Filter

Фильтр GTE. Выбрать все лица с id, большим или равным указанному.

Параметры:value (integer) – значение id Результат:имя фильтра (GTE) и его значение. Тип результата:объект класса Filter.

Пример: Id.gte(1234) выбирает лица с id, большим или равным 1234.

classmethod oneof(cls, *value: typing.Union[int]) → Filter

Фильтр IN. Выбрать лица с id из заданной последовательности.

Параметры:value (list of integers) – список значений id Результат:имя фильтра (IN) и его значение. Тип результата:объект класса Filter.

Пример: Id.oneof(1234, 5678) выбирает лицо с id 1234 и/или 5678.

class ntech.sfapi_client.filters.Meta

Предоставляет методы для фильтрации содержимого галереи по метаданным. Для использования фильтра нужно напрямую вызвать соответствующий метод, не создавая экземпляр класса.

classmethod lte(self, value: typing.Union[str, int]) → Filter

Фильтр LTE. Выбрать все лица, у которых определенная строка в метаданных меньше или равна указанному значению.

Параметры:value (string or integer) – значение строки с метаданными Результат:имя фильтра (LTE) и его значение. Тип результата:объект класса Filter.

Пример: Meta(‘foo’).lte(1234) выбирает лица с мета-строкой foo, имеющей значение меньшее или равное 1234.

classmethod gte(self, value: typing.Union[str, int]) → Filter

Фильтр GTE. Выбрать все лица, у которых определенная строка в метаданных больше или равна указанному значению.

Параметры:value (string or integer) – значение строки с метаданными Результат:имя фильтра (GTE) и его значение. Тип результата:объект класса Filter.

Пример: Meta(‘foo’).gte(1234) выбирает лица с мета-строкой foo, имеющей значение большее или равное 1234.

classmethod oneof(self, *value: typing.Union[str, int]) → Filter

Фильтр IN. Выбрать все лица, у которых определенная строка в метаданных совпадает с одним из значений из заданной последовательности.

Параметры:value (list of strings or integers) – список строк с метаданными Результат:имя фильтра (IN) и его значение. Тип результата:объект класса Filter.

Пример: Meta.oneof(1234, 5678) выбирает лица с мета-строкой, имеющей значение 1234 и/или 5678.

classmethod subset(self, *value: str) → Filter

Фильтр SUBSET. Выбрать все лица, у которых определенная строка содержит все значения из указанной последовательности.

Параметры:value (list of strings or integers) – список строк с метаданными Результат:имя фильтра (SUBSET) и его значение. Тип результата:объект класса Filter.

Пример: Meta(‘foo’).subset(“male”, “angry”) выбирает лица с мета-строкой foo, содержащей все значения из последовательности [“male”, “angry”].

class ntech.sfapi_client.filters.Detection(Filter)

Предоставляет метод для идентификации (поиска похожих лиц в базе данных) обнаруженного лица.

__init__(self, id: typing.Union[str, objects.DetectFace], threshold: float)

Параметры:

• id (objects.DetectFace or temporary face id in memcached returned by sfapi_client.Client.detect(), string) – лицо (результат детекции), которое нужно найти в базе данных
• threshold (float) – минимальная степень схожести лиц от 0 до 1

Пример: Detection(det1, 0.77) выбирает лица, похожие на результат детекции det1 со степенью схожести, большей или равной 0.77.

class ntech.sfapi_client.filters.Face(Filter)

Предоставляет метод для поиска лиц в базе данных, похожих на лицо из галереи.

__init__(self, id: typing.Union[str, objects.Face], threshold: float)

Параметры:

• id (objects.Face, objects.FaceId or custom face id in the gallery, string) – лицо из базы данных, которое нужно найти
• threshold (float) – минимальная степень схожести лиц от 0 до 1

Пример: Detection(FaceId(“gal1”, 1234), 0.77) выбирает лица, похожие на лицо с пользовательским идентификатором face 1234 из галереи gal1 со степенью схожести, большей или равной 0.77.

Пример использования нескольких фильтров

filters=[filters.Id.gte(123456), filters.Meta('age').gte(45), filters.Meta('camera').oneof('abc', 'def')]

Отображение сообщений об ошибках

class sfapi_client.SFApiRemoteError

Данное сообщение об ошибке появляется, если ошибка произошла по причине, отличной от сетевого сбоя.

Сообщение об ошибке содержит как минимум два поля:

• code — это код ошибки в виде CAPS_AND_UNDERSCORES, который может быть использован для автоматического преобразования.
• reason — это описание ошибки, предназначенное для прочтения человеком.

Полный список ошибок

Код ошибки	Описание
UNKNOWN_ERROR	Ошибка неизвестного происхождения.
BAD_PARAM	Запрос может быть прочитан, однако некоторые параметры метода недействительны. Данный тип ответа содержит дополнительные атрибуты param и value для описания ошибочных параметров.
CONFLICT	Конфликт.
EXTRACTION_ERROR	Ошибка при извлечении из лица вектора признаков.
LICENSE_ERROR	Конфигурация системы не соответствует лицензии.
MALFORMED_REQUEST	Запрос неправильно сформирован и не может быть прочитан.
OVER_CAPACITY	Превышен размер очередей в компоненте findface-extraction-api.
SOURCE_NOT_FOUND	В параметре from задано несуществующее лицо.
SOURCE_GALLERY_NOT_FOUND	В параметре from задана несуществующая галерея.
STORAGE_ERROR	Биометрическая база данных недоступна.
CACHE_ERROR	Хранилище memcached недоступно.
NOT_FOUND	Подходящие лица не найдены.
NOT_IMPLEMENTED	Функционал не реализован.
GALLERY_NOT_FOUND	Подходящие галереи не найдены.

class sfapi_client.SFApiMalformedResponseError

Это сообщение об ошибке появляется, если ошибка произошла из-за сбоя в сети, или если Клиент не смог прочитать API-ответ от findface-sf-api.