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

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

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

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 ¶