Classes and Methods

In this section:

Basic Classes

class facerouter.plugin.Plugin

Provides the basic methods for writing a plugin (see Basics). A custom class that wraps a plugin must inherit from the Plugin class.

preprocess(self, request: FrHTTPRequest, labels: Mapping[str, str]) 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.

Parameters
  • FrHTTPRequest (tornado.httpserver.HTTPRequest) – a HTTP API request that includes an extra argument params

  • labels (dictionary) – a custom set of a frame labels from request.params

Returns

one or several strings 'facen', 'gender', 'age', 'emotions'

Return type

tuple

The params argument of FrHTTPRequest includes the following fields:

Parameters
  • photo (bytes) – JPEG video frame featuring a detected face

  • face0 (bytes) – normalized face image

  • 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) – coordinates of the face region in the video frame

  • cam_id (string) – camera id

  • timestamp (datetime.datetime) – video frame timestamp

  • detectorParams (dictionary) – debug information from the video face detector

  • bs_type (string) – 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).

  • labels (dictionary) – (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

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

Accepts the detected face features.

Parameters
  • request (tornado.httpserver.HTTPRequest) – a HTTP API request from findface-video-worker

  • photo (bytes) – JPEG video frame featuring a detected face, from 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) – coordinates of the face region in the video frame, from request.params

  • event_id (uint64) – 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.

  • detection (objects.DetectFace) – detection result received from findface-sf-api, that contains requested face features such as faces, gender, age and emotions.

Returns

n/a

Return type

n/a

shutdown(self)

This method is invoked before the findface-facerouter shutdown.

Parameters

n/a

Returns

n/a

Object Classes

class objects.BBox

Represents coordinates of the rectangle around a face.

class objects.DetectFace

Represents a detection result with the following fields:

Parameters
  • id (string) – id of the detection result in memcached

  • bbox (objects.Bbox) – coordinates of the rectangle around a face

  • features (dictionary) – (optional) information about gender, age and emotions

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.

Parameters

orientation (EXIF orientation) – orientation of a detected face

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

Represents a custom face identifier object in the gallery.

Parameters
  • gallery (string) – gallery name

  • face (integer) – custom face identifier in the gallery

class objects.Face

Represents a result of database search by biometric sample

Parameters
  • id (objects.FaceId) – FaceId object.

  • features (dictionary) – information about gender, age and emotions

  • meta (dictionary) – face meta data

  • confidence (float) – similarity between the biometric sample and a face in the search result

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.

Parameters

next_page (string) – cursor for the next page with search results

Face Detection and Gallery Management

class ntech.sfapi_client.client.Client

Represents basic methods to detect faces in images and work with galleries.

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.

Parameters
  • url (URL) – image URL if you pass an image that is publicly accessible on the internet

  • image (bytes) – PNG/JPG/WEBP image file is you pass an image as a file

  • facen (boolean) – extract a biometric sample from the detected face. To save the detection result in memcached pass facen=True

  • gender (boolean) – extract and return information about gender

  • age (boolean) – extract and return information about age

  • emotions (boolean) – extract and return information about emotions

  • return_facen (boolean) – return facen in the method result

  • autorotate (boolean) – automatically rotate the image in 4 different orientations to detect faces in each of them. Overlapping detections with IOU > 0.5 will be merged

  • detector (boolean) – nnd or normalized. The normalized detector is used to process normalized images, for example, those which are received from fkvideo_worker.

  • timeout (number) – FindFace core response timeout, in seconds (if none, the default value is used)

Returns

Detection result

Return type

DetectorResponse object.

gallery(self, name)

Returns a gallery object sfapi_client.Gallery to refer to it later (for example, to list gallery faces).

Parameters

name (string) – gallery name

Returns

a gallery object

Return type

sfapi_client.Gallery

list_galleries(self, timeout=None):

Returns the list of galleries.

Parameters

timeout (number) – FindFace core response timeout, in seconds (if none, the default value is used)

Returns

list of galleries with the fields name (a gallery name, string) and number (the number of faces in the gallery, number)

Return type

list of GalleryListItem

class ntech.sfapi_client.gallery.Gallery

Provides methods to work with galleries and faces.

list(self, *, filters: 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.

Parameters
  • filters (sfapi_client.filters.Filter) – list of filters

  • limit (integer) – maximum number of returned faces

  • sort (string) – 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).

  • 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.

  • ignore_errors (boolean) – 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.

  • timeout (number) – FindFace core response timeout, in seconds (if none, the default value is used)

Returns

list with faces from the gallery, that match the given filters.

Return type

ListResponse object

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

Creates a face in the gallery.

Parameters
  • new_id (integer or callable) – 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.

  • source (sfapi_client.DetectFace, sfapi_client.Face, sfapi_client.FaceId, or string) – face source: create a face using another face in the database or a detection result as a source.

  • meta (dictionary) – 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 configuration files (/etc/tarantool/instances.available/*.lua).

  • regenerate_attempts – number of attempts to regenerate a unique Face ID with the ctx.idgen() function if new_id is callable

  • timeout (number) – FindFace core response timeout, in seconds (if none, the default value is used)

Returns

representation of the newly created face

Return type

Face object

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

Removes a face from the gallery.

Parameters
  • face (sfapi_client.Face, sfapi_client.FaceId or id in integer) – face to be removed

  • timeout (number) – FindFace core response timeout, in seconds (if none, the default value is used)

Returns

None

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

Retrieves a face from the gallery.

Parameters
  • face (sfapi_client.Face, sfapi_client.FaceId or id in integer) – face to be retrieved

  • timeout (number) – FindFace core response timeout, in seconds (if none, the default value is used)

Returns

representation of the face

Return type

Face object

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.

Parameters

timeout (number) – FindFace core response timeout, in seconds (if none, the default value is used)

Returns

None

drop(self, timeout=None) None:

Removes a gallery from findface-sf-api.

Parameters

timeout (number) – FindFace core response timeout, in seconds (if none, the default value is used)

Returns

None

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

Update face meta data in the gallery.

Parameters
  • face (sfapi_client.Face, sfapi_client.FaceId or id in integer) – face to be updated

  • meta (dictionary) – 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.

  • timeout (number) – FindFace core response timeout, in seconds (if none, the default value is used)

Returns

representation of the updated face

Return type

Face object

Filters for Database Search

class ntech.sfapi_client.filters.Filter

Generic class. Represents a list of filters (with assigned values) that have to be applied to the gallery content.

serialize(self)

Method that passes the list of filters with assigned values to the findface-sf-api component.

Returns

filter names and filter values

Return type

tuple (‘filtername’, [“value1”, “value2”]).

class ntech.sfapi_client.filters.Id

Represents methods for filtering gallery content by id. Don’t instantiate, use relevant classmethods to call a filter.

classmethod lte(cls, value: int) Filter

LTE filter. Select all faces with id less or equal to value.

Parameters

value (integer) – id value

Returns

filter name (LTE) and its value.

Return type

object of Filter class.

Example: Id.lte(1234) selects faces with id less or equal to 1234.

classmethod gte(cls, value: int) Filter

GTE filter. Select all faces with id greater or equal to value.

Parameters

value (integer) – id value

Returns

filter name (GTE) and its value.

Return type

object of Filter class.

Example: Id.lte(1234) selects faces with id greater or equal to 1234.

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

IN filter. Select a face(s) with id from a given set.

Parameters

value (list of integers) – list of id values

Returns

filter name (IN) and its value.

Return type

object of Filter class.

Example: Id.oneof(1234, 5678) selects a face(s) with id 1234 and/or 5678.

class ntech.sfapi_client.filters.Meta

Represents methods for filtering gallery content by metadata. Don’t instantiate, use relevant classmethods to call a filter.

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

LTE filter. Select all faces with a metastring less or equal to value

Parameters

value (string or integer) – metastring value

Returns

filter name (LTE) and its value.

Return type

object of Filter class.

Example: Meta('foo').lte(1234) selects faces with a metastring foo less or equal to 1234.

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

GTE filter. Select all faces with a metastring greater or equal to value

Parameters

value (string or integer) – metastring value

Returns

filter name (GTE) and its value.

Return type

object of Filter class.

Example: Meta('foo').gte(1234) selects faces with a metastring foo greater or equal to 1234.

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

IN filter. Select a face(s) with a metastring from a given set.

Parameters

value (list of strings or integers) – list of metastring values

Returns

filter name (IN) and its value.

Return type

object of Filter class.

Example: Meta.oneof(1234, 5678) selects a face(s) with a metastring 1234 and/or 5678.

classmethod subset(self, *value: str) Filter

SUBSET filter. Select all faces with a metastring featuring all values from a given set.

Parameters

value (list of strings or integers) – list of metastring values

Returns

filter name (SUBSET) and its value.

Return type

object of Filter class.

Example: Meta('foo').subset("male", "angry") selects face with a metastring foo featuring all values from the set [“male”, “angry”].

class ntech.sfapi_client.filters.Detection(Filter)

Represents a method that identifies a detected face (searches the database for similar faces).

__init__(self, id: Union[str, objects.DetectFace], threshold: float)
Parameters
  • id (objects.DetectFace or temporary face id in memcached returned by sfapi_client.Client.detect(), string) – face (detection result) to be identified

  • threshold (float) – identification threshold similarity between faces from 0 to 1.

Example: Detection(det1, 0.77) selects faces similar to the detection result det1 with similarity greater or equal to 0.77.

class ntech.sfapi_client.filters.Face(Filter)

Represents a method that searches the database for faces similar to a given face from a gallery.

__init__(self, id: Union[str, objects.Face], threshold: float)
Parameters
  • id (objects.Face, objects.FaceId or custom face id in the gallery, string) – face from a gallery to be identified

  • threshold (float) – identification threshold similarity between faces from 0 to 1.

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.

Several Filters Usage Example

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

Display Error Messages

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.

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.

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.