Plugin Classes and Methods

In this section:

Basic Classes
Object Classes
Face Detection and Gallery Management
Filters for Database Search
Display Error Messages

Basic Classes 

class facerouter.plugin.Plugin

Provides the basic methods for writing a plugin (see Plugin 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.

Plugin Classes and Methods

Basic Classes

Object Classes

Face Detection and Gallery Management

Filters for Database Search

Display Error Messages

Basic Classes 

Object Classes 

Face Detection and Gallery Management 

Filters for Database Search 

Display Error Messages 