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

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: typing.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.

Param: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: 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.

Parameters:
  • filters (sfapi_client.filters.Filter) – list of filters
  • limit (integer) – maximum number of returned faces
  • 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).
  • sort – string
  • 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: 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.

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 (findface-tarantool-server) configuration files.
  • 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: typing.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: typing.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: 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.

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: typing.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: typing.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: typing.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: 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.

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: typing.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: typing.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 and status.

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