.. _plugin-methods: Classes and Methods -------------------------- .. rubric:: In this section: .. contents:: :local: Basic Classes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. py:module:: facerouter.plugin .. py:class:: Plugin Provides the basic methods for writing a plugin (see :ref:`plugin-basics`). A custom class that wraps a plugin must inherit from the ``Plugin`` class. .. py:method:: preprocess(self, request: FrHTTPRequest, labels: typing.Mapping[str, str]) -> typing.Tuple[str] Returns a tuple that contains one or several strings ``'facen'``, ``'gender'``, ``'age'``, ``'emotions'``. This means that ``findface-facerouter`` must request ``findface-extraction-api`` to extract a biometric sample, recognize gender, age, emotions respectively. :param FrHTTPRequest: a HTTP API request that includes an extra argument ``params`` :type FrHTTPRequest: tornado.httpserver.HTTPRequest :param labels: a custom set of a frame labels from ``request.params`` :type labels: dictionary :return: one or several strings ``'facen'``, ``'gender'``, ``'age'``, ``'emotions'`` :rtype: tuple The ``params`` argument of ``FrHTTPRequest`` includes the following fields: :param photo: JPEG video frame featuring a detected face :type photo: bytes :param face0: normalized face image :type face0: bytes :param bbox: coordinates of the face region in the video frame :type 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 :param cam_id: camera id :type cam_id: string :param timestamp: video frame timestamp :type timestamp: datetime.datetime :param detectorParams: debug information from the video face detector :type detectorParams: dictionary :param bs_type: best face search mode. Available options: overall (the ``findface-video-worker`` posts only one snapshot per track, but of the highest quality.), realtime (the ``findface-video-worker`` posts the best snapshot within each of consecutive time intervals). :type bs_type: string :param labels: (duplicates params.labels) a custom set of a frame labels, which are specified in a job parameters for ``findface-video-worker`` and then assigned to the frame :type labels: dictionary .. py:method:: process(self, request: FrHTTPRequest, photo: bytes, bbox: typing.List[int], event_id: int, detection: DetectFace) Accepts the detected face features. :param request: a HTTP API request from ``findface-video-worker`` :type request: tornado.httpserver.HTTPRequest :param photo: JPEG video frame featuring a detected face, from ``request.params`` :type photo: bytes :param bbox: coordinates of the face region in the video frame, from ``request.params`` :type 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 :param event_id: id of the face automatically set by ``findface -facerouter`` upon receiving it from ``findface-video-worker``. Can be used as a face custom identifier in the biometric database. :type event_id: uint64 :param detection: detection result received from ``findface-sf-api``, that contains requested face features such as faces, gender, age and emotions. :type detection: objects.DetectFace :return: n/a :rtype: n/a .. py:method:: shutdown(self) This method is invoked before the ``findface-facerouter`` shutdown. :parameters: n/a :return: n/a Object Classes ^^^^^^^^^^^^^^^^^^ .. py:module:: objects .. py:class:: BBox Represents coordinates of the rectangle around a face. .. py:class:: objects.DetectFace Represents a detection result with the following fields: :param id: id of the detection result in memcached :type id: string :param bbox: coordinates of the rectangle around a face :type bbox: objects.Bbox :param features: (optional) information about gender, age and emotions :type features: dictionary .. py:class:: objects.DetectResponse Represents a list of ``objects.DetectionFace`` objects with an additional field ``orientation`` featuring information about the face EXIF orientation in the image. :param orientation: orientation of a detected face :type orientation: EXIF orientation .. py:class:: objects.FaceId(namedtuple('FaceId', ('gallery', 'face'))) Represents a custom face identifier object in the gallery. :param gallery: gallery name :type gallery: string :param face: custom face identifier in the gallery :type face: integer .. py:class:: objects.Face Represents a result of database search by biometric sample :param id: FaceId object. :type id: objects.FaceId :param features: information about gender, age and emotions :type features: dictionary :param meta: face meta data :type meta: dictionary :param confidence: similarity between the biometric sample and a face in the search result :type confidence: float .. py:class:: objects.ListResponse Represents a list of ``objects.Face`` objects (i.e. a list of biometric sample search results) with an additional field ``next_page`` featuring the cursor for the next page with search results. :param next_page: cursor for the next page with search results :type next_page: string Face Detection and Gallery Management ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. py:module:: ntech.sfapi_client.client .. py:class:: Client Represents basic methods to detect faces in images and work with galleries. .. py:method:: 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 Detects a face and returns the result of detection. :param url: image URL if you pass an image that is publicly accessible on the internet :type url: URL :param image: PNG/JPG/WEBP image file is you pass an image as a file :type image: bytes :param facen: extract a biometric sample from the detected face. To save the detection result in memcached pass ``facen=True`` :type facen: boolean :param gender: extract and return information about gender :type gender: boolean :param age: extract and return information about age :type age: boolean :param emotions: extract and return information about emotions :type emotions: boolean :param return_facen: return facen in the method result :type return_facen: boolean :param autorotate: automatically rotate the image in 4 different orientations to detect faces in each of them. Overlapping detections with IOU > 0.5 will be merged :type autorotate: boolean :param detector: nnd or normalized. The ``normalized`` detector is used to process normalized images, for example, those which are received from ``fkvideo_worker``. :type detector: boolean :param timeout: FindFace core response timeout, in seconds (if ``none``, the default value is used) :type timeout: number :return: Detection result :rtype: ``DetectorResponse`` object. .. py:method:: gallery(self, name) Returns a gallery object ``sfapi_client.Gallery`` to refer to it later (for example, to list gallery faces). :param name: gallery name :type name: string :return: a gallery object :rtype: sfapi_client.Gallery .. py:method:: list_galleries(self, timeout=None): Returns the list of galleries. :param timeout: FindFace core response timeout, in seconds (if ``none``, the default value is used) :type timeout: number :return: list of galleries with the fields ``name`` (a gallery name, string) and ``number`` (the number of faces in the gallery, number) :rtype: list of GalleryListItem .. py:module:: ntech.sfapi_client.gallery .. py:class:: Gallery Provides methods to work with galleries and faces. .. py:method:: list(self, *, filters: typing.Iterable[filters.Filter] = None, limit: int = 1000, sort: str = '', page=None, ignore_errors=False, timeout=None) -> ListResponse Returns a list-like object with faces from the gallery, that match the given filters. The returned list-like object has an additional property ``next_page`` which can be used as a value for the ``page`` parameter in next requests. :param filters: list of filters :type filters: sfapi_client.filters.Filter :param limit: maximum number of returned faces :type limit: integer :param sort: sorting order. Pass one of the following values: ``id``: increasing order by id, ``-id``: decreasing order by id (sorting by id is used if you have NOT specified a feature vector to search for), ``-confidence``: decreasing order by face similarity (only if you have specified a feature vector to search for). By default, the method uses the ``id`` order (no feature vector specified), or ``-confidence`` (with feature vector). :type sort: string :param page: cursor of the next page with search results. The ``page`` value is returned in the response in the ``next_page`` parameter along with the previous page results. :param ignore_errors: By default, if one or several ``findface-tarantool-server`` shards are out of service during face identification, ``findface-sf-api`` returns an error. Enable this Boolean parameter to use available ``findface-tarantool-server`` shards to obtain face identification results. :type ignore_errors: boolean :param timeout: FindFace core response timeout, in seconds (if ``none``, the default value is used) :type timeout: number :return: list with faces from the gallery, that match the given filters. :rtype: ListResponse object .. py:method:: 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 Creates a face in the gallery. :param new_id: custom face identifier (Face ID) in the database gallery. May be a (async) callable which returns the id. To generate id, you can use the ``ctx.idgen()`` function delivered with the context. :type new_id: integer or callable :param source: face source: create a face using another face in the database or a detection result as a source. :type source: sfapi_client.DetectFace, sfapi_client.Face, sfapi_client.FaceId, or string :param meta: face metadata. Keys must be strings and values must be either ints, strings or lists of strings. Metadata keys and types must be previously specified in the storage (``findface-tarantool-server``) configuration files. :type meta: dictionary :param regenerate_attempts: number of attempts to regenerate a unique Face ID with the ``ctx.idgen()`` function if new_id is callable :type regenerate attempts: number :param timeout: FindFace core response timeout, in seconds (if ``none``, the default value is used) :type timeout: number :return: representation of the newly created face :rtype: Face object .. py:method:: delete(self, face: typing.Union[Face, int], timeout=None) -> None Removes a face from the gallery. :param face: face to be removed :type face: sfapi_client.Face, sfapi_client.FaceId or id in integer :param timeout: FindFace core response timeout, in seconds (if ``none``, the default value is used) :type timeout: number :return: None .. py:method:: get(self, face: typing.Union[Face, int], timeout=None) -> Face Retrieves a face from the gallery. :param face: face to be retrieved :type face: sfapi_client.Face, sfapi_client.FaceId or id in integer :param timeout: FindFace core response timeout, in seconds (if ``none``, the default value is used) :type timeout: number :return: representation of the face :rtype: Face object .. py:method:: create(self, timeout=None) -> None Creates a gallery in ``findface-sf-api`` as a ``sfapi_client.Gallery`` object. Being a proxy object, ``sfapi_client.Gallery`` doesn't require a gallery to be existing on the server. :param timeout: FindFace core response timeout, in seconds (if ``none``, the default value is used) :type timeout: number :return: None .. py:method:: drop(self, timeout=None) -> None: Removes a gallery from ``findface-sf-api``. :param timeout: FindFace core response timeout, in seconds (if ``none``, the default value is used) :type timeout: number :return: None .. py:method:: update(self, face: typing.Union[Face, str], *, meta: typing.Dict[str, typing.Union[int, str, typing.List[str]]] = None, timeout=None) -> Face Update face meta data in the gallery. :param face: face to be updated :type face: sfapi_client.Face, sfapi_client.FaceId or id in integer :param meta: face meta data to be updated. Keys must be strings and values must be either ints, strings or lists of strings. If a meta string is not passed or passed as null, it won't be updated in the database. :type meta: dictionary :param timeout: FindFace core response timeout, in seconds (if ``none``, the default value is used) :type timeout: number :return: representation of the updated face :rtype: Face object Filters for Database Search ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. py:module:: ntech.sfapi_client.filters .. py:class:: Filter Generic class. Represents a list of filters (with assigned values) that have to be applied to the gallery content. .. py:method:: serialize(self) Method that passes the list of filters with assigned values to the ``findface-sf-api`` component. :return: filter names and filter values :rtype: tuple ('filtername', ["value1", "value2"]). .. py:class:: Id Represents methods for filtering gallery content by id. Don't instantiate, use relevant classmethods to call a filter. .. py:classmethod:: lte(cls, value: int) -> Filter LTE filter. Select all faces with ``id`` less or equal to ``value``. :param value: id value :type value: integer :return: filter name (LTE) and its value. :rtype: object of ``Filter`` class. Example: ``Id.lte(1234)`` selects faces with id less or equal to ``1234``. .. py:classmethod:: gte(cls, value: int) -> Filter GTE filter. Select all faces with ``id`` greater or equal to ``value``. :param value: id value :type value: integer :return: filter name (GTE) and its value. :rtype: object of ``Filter`` class. Example: ``Id.lte(1234)`` selects faces with id greater or equal to ``1234``. .. py:classmethod:: oneof(cls, *value: typing.Union[int]) -> Filter IN filter. Select a face(s) with id from a given set. :param value: list of id values :type value: list of integers :return: filter name (IN) and its value. :rtype: object of ``Filter`` class. Example: ``Id.oneof(1234, 5678)`` selects a face(s) with id ``1234`` and/or ``5678``. .. py:class:: Meta Represents methods for filtering gallery content by metadata. Don't instantiate, use relevant classmethods to call a filter. .. py:classmethod:: lte(self, value: typing.Union[str, int]) -> Filter LTE filter. Select all faces with a metastring less or equal to ``value`` :param value: metastring value :type value: string or integer :return: filter name (LTE) and its value. :rtype: object of ``Filter`` class. Example: ``Meta('foo').lte(1234)`` selects faces with a metastring ``foo`` less or equal to ``1234``. .. py:classmethod:: gte(self, value: typing.Union[str, int]) -> Filter GTE filter. Select all faces with a metastring greater or equal to ``value`` :param value: metastring value :type value: string or integer :return: filter name (GTE) and its value. :rtype: object of ``Filter`` class. Example: ``Meta('foo').gte(1234)`` selects faces with a metastring ``foo`` greater or equal to ``1234``. .. py:classmethod:: oneof(self, *value: typing.Union[str, int]) -> Filter IN filter. Select a face(s) with a metastring from a given set. :param value: list of metastring values :type value: list of strings or integers :return: filter name (IN) and its value. :rtype: object of ``Filter`` class. Example: ``Meta.oneof(1234, 5678)`` selects a face(s) with a metastring ``1234`` and/or ``5678``. .. py:classmethod:: subset(self, *value: str) -> Filter SUBSET filter. Select all faces with a metastring featuring all values from a given set. :param value: list of metastring values :type value: list of strings or integers :return: filter name (SUBSET) and its value. :rtype: object of ``Filter`` class. Example: ``Meta('foo').subset("male", "angry")`` selects face with a metastring ``foo`` featuring all values from the set ["male", "angry"]. .. py:class:: Detection(Filter) Represents a method that identifies a detected face (searches the database for similar faces). .. py:method:: __init__(self, id: typing.Union[str, objects.DetectFace], threshold: float) :param id: face (detection result) to be identified :type id: ``objects.DetectFace`` or temporary face id in memcached returned by sfapi_client.Client.detect(), string :param threshold: identification threshold similarity between faces from 0 to 1. :type threshold: float Example: ``Detection(det1, 0.77)`` selects faces similar to the detection result ``det1`` with similarity greater or equal to ``0.77``. .. py:class:: Face (Filter) Represents a method that searches the database for faces similar to a given face from a gallery. .. py:method:: __init__(self, id: typing.Union[str, objects.Face], threshold: float) :param id: face from a gallery to be identified :type id: ``objects.Face``, ``objects.FaceId`` or custom face id in the gallery, string :param threshold: identification threshold similarity between faces from 0 to 1. :type threshold: float Example: Detection(FaceId("gal1", 1234), 0.77) selects faces similar to the face 1234 from the ``gal1`` gallery with similarity greater or equal than 0.77. .. rubric:: Several Filters Usage Example .. code:: filters=[filters.Id.gte(123456), filters.Meta('age').gte(45), filters.Meta('camera').oneof('abc', 'def')] Display Error Messages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. py:class:: sfapi_client.SFApiRemoteError This error message appears if the error occurred for a reason other than a network failure. The error body always includes at least two fields: * ``code`` is a short string in ``CAPS_AND_UNDERSCORES``, usable for automatic decoding. * ``reason`` is a human-readable description of the error and should not be interpreted automatically. .. rubric:: Common Error Codes +------------------------------+--------------------------------------------------------------------------------------------------+ | Error code | Description | +==============================+==================================================================================================+ | ``UNKNOWN_ERROR`` | Error with unknown origin. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``BAD_PARAM`` | The request can be read, however, some method parameters are invalid. This response type | | | contains additional attributes ``param`` and``value`` to indicate which parameters are invalid. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``CONFLICT`` | Conflict. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``EXTRACTION_ERROR`` | Error upon a face feature vector extraction. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``LICENSE_ERROR`` | The system configuration does not match license. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``MALFORMED_REQUEST`` | The request is malformed and cannot be read. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``OVER_CAPACITY`` | The ``findface-extraction-api`` queue length has been exceeded. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``SOURCE_NOT_FOUND`` | The face in the ``from`` parameter does not exist. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``SOURCE_GALLERY_NOT_FOUND`` | The gallery in the ``from`` parameter does not exist. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``STORAGE_ERROR`` | The biometric database not available. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``CACHE_ERROR`` | Memcached not available. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``NOT_FOUND`` | Matching faces not found. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``NOT_IMPLEMENTED`` | This functionality not implemented. | +------------------------------+--------------------------------------------------------------------------------------------------+ | ``GALLERY_NOT_FOUND`` | Matching galleries not found. | +------------------------------+--------------------------------------------------------------------------------------------------+ .. py:class:: sfapi_client.SFApiMalformedResponseError This error message appears if the error occurred due to a network failure, or if Client was unable to read an API response from ``findface-sf-api``.