FaceRTMAPI


 
Definitions
AFS"Animetrics Face Signature". A biometric template/unique numerical representation of a human face.
ImageA picture containing one or more human faces.
FaceAn individual human face. Used to build an AFS.
SubjectA collection of faces representing one unique individual as defined by an alphanumeric Subject ID.
GalleryA list of Subjects. Used to limit Face Recognition searches.
Feature/LandmarkA point in an image representing a facial marker, such as an eye center, nose tip, ear tragus, lip corner, etc. There are 24 Features available through the API.
DetectFind human faces and associated Features in an Image.
PoseThe orientation of a Face. Includes Pitch (degrees rotated around X axis), Yaw (degrees rotated around Y axis), and Roll (degrees rotated around Z axis).
SetPoseA zero-corrected "mugshot" representation of a Face. The Face has been rotated around the X, Y, and Z axes for zero Pitch, Yaw, and Roll.
EnrollBuild an AFS from a Face and add it to a Gallery.
RecognizeFind matching known Subjects belonging to a Gallery from an unknown Face.
CandidateOne of one or more Subjects that a recognize operation finds for a Face. Each Subject has an associated similarity to the unknown Face.
Overview

Basic Workflow

  1. Detect one or more known faces in an image.
  2. Enroll one or more faces from that same image into a gallery.
  3. Detect one or more unknown faces in an image.
  4. Recognize one face at a time from that same image against previously enrolled faces.

Detect

The Animetrics Face Recognition API can be used to detect human faces in pictures. Information on facial features or "landmarks" is returned as coordinates on the image. Animetrics Face Recognition will also detect and return the gender and orientation, or "pose" of faces along 3 axes.

Developers may request information on faces in a picture, which will include at minimum face boundaries. Eye coordinates and full features including ears, nose, eyebrows, lips, chin, pose orientation, and attributes such as gender can also be requested.

A special capability called "SetPose" is also available. SetPose images are frontal view mugshots of a face which have been zero-corrected for pitch (x axis), yaw (y axis), and roll (z axis). As long as within the input facial image both eyes are visible, then SetPose will pose correct that facial image to x=y=z=0, a perfect frontal.

Current attribute recognition includes gender detection. If selecting eyes, full or setpose with a detect call, the gender and confidence level will be returned for all faces found in the image.

Facial features detected may be corrected or modified. Modified landmarks may be fed back into more detailed requests to help improve the detection algorithm. For instance, an eye in the picture may be hidden or obscured; requesting just eye landmarks, manually correcting their locations, and feeding this data into a more detailed request will help improve the accuracy of additional landmarks and pose.

Recognize

The Animetrics Face Recognition API can also be used to recognize human faces in pictures. Known faces are "enrolled" in a private gallery, generating a unique biometric identifier for each. An unknown face can be compared against these known subjects to find the closest match. Galleries may also be viewed and edited through the API.

Enrolling a subject into a gallery involves issuing an Enroll command with a specified unique gallery id, a reference to an image containing that subject, and face boundaries or eye coordinates for that subject. Face boundaries or eye coordinates can be copied from the results of a Detect or Detect Features operation.

Matching a face within a gallery is achieved by issuing a Find command with a specified gallery id, a reference to an image containing some unknown face, and the face boundaries or eye coordinates of the face in the image. Face boundaries or eye coordinates can be copied from the results of a Detect or Detect Features operation. A list of potential matching known subjects ("candidates") is returned along with match similarity scores.

Update Operations

In addition to enrolling a known subject, this subject's identity may be modified in one of two ways. Enroll operations will return a transaction id corresponding to each separate face that was presented for enrolling a subject. This transaction id may be used to update the subject id associated with a face or to disassociate this face from a subject. Updating a subject id for a face will simply assign the biometric representing this face to a separate subject identity. Similarly, delete operations will remove this biometric template's association from a particular subject, thus deleting it from the Facial Recognition System.

Gallery Operations

The API also allows for gallery management. Operations are List Galleries, View Gallery, Add To Gallery, and Remove From Gallery. List galleries will return a list of all galleries associated with an API key. View Gallery will return a list of all Subjects belonging to a Gallery. Add To Gallery will add a subject to an existing or new gallery. Remove From Gallery will remove a Subject from a Gallery and will delete this Gallery if no subjects remain.

Pose

The Animetrics Face Recognition API very uniquely has the capability to detect and recognize faces in off-centered orientations. This means that if a picture is taken of someone who is not looking at the camera, our face detection and recognition algorithms will still be able to find and recognize faces.

Detect Features operations may also return a "SetPose" image, which is a A zero-corrected "mugshot" representation of a Face. The Face has been rotated around the X, Y, and Z axes for zero Pitch, Yaw, and Roll."

Request/Response

All requests to the API are made via standard HTTP GET and HTTP POST requests. Specific methods, endpoints, and required request parameters are listed in the function reference. API responses are all returned in JSON. Example responses are also shown in the function reference documentation.

Usage

You may sign up for an API key to make further use of the Animetrics Face Recognition API by providing us with your email. Keys will be mailed to this address. We will never share your email with anyone. Developer keys will allow up to 30 api requests per day. Please use our Mashape interface or contact us at api@animetrics.com if you need further access.