Glossary

A

Attributes

Attributes are optional in the detection results, such as age, gender, head pose, facial hair, smiling. They can be obtained from the detection API by specifying the query parameters: returnFaceAttributes. Attributes give extra information regarding selected faces; in addition to the face ID and the rectangle.

For more details, please refer to the guide Face - Detect.

Age (Attribute)

Age is one of the attributes that describes the age of a particular face. The age attribute is optional in the detection results, and can be controlled with a detection request by specifying the returnFaceAttributes parameter.

For more details, please refer to the guide Face - Detect.

B

C

Candidate

Candidates are essentially identification results (e.g. identified persons and level of confidence in detections). A candidate is represented by the PersonID and confidence, indicating that the person is identified with a high level of confidence.

For more details, please refer to the guide Face - Identify.

Confidence

Confidence is a measurement revealing the similarity between faces or Person in numerical values –which is used in identification, and verification to indicate the similarities of searched, identified and verified results.

For more details, please refer to the following guides: Face - Find Similar, Face - Identify, Face - Verify.

D

Detection/Face Detection

Face detection is the action of locating faces in images. Users can upload an image or specify an image URL in the request. The detected faces are returned with face IDs indicating a unique identity in Face API. The rectangles indicate the face locations in the image in pixels, as well as the optional attributes for each face such as age, gender, head pose, facial hair and smiling.

For more details, please refer to the guide Face - Detect.

E

F

Face

Face is a unified term for the results derived from Face API related with detected faces. Ultimately, face is represented by a unified identity (Face ID), a specified region in images (Face Rectangle), and extra face related attributes, such as age, gender, landmarks and head pose. Additionally, faces can be returned from detection.

For more details, please refer to the guide Face - Detect.

Face API

Face API is a cloud-based API that provides the most advanced algorithms for face detection and recognition. The main functionality of Face API can be divided into two categories: face detection with attributes, and face recognition.

For more details, please refer to the following guides: Face API Overview, Face - Detect, Face - Find Similar, Face - Group, Face - Identify, Face - Verify.

Face Attributes/Facial Attributes

Please see Attributes.

Face ID

Face ID is derived from the detection results, in which a string represents a face in Face API.

For more details, please refer to the guide Face - Detect.

Face Landmarks/Facial Landmarks

Landmarks are optional in the detection results; which are semantic facial points, such as the eyes, nose and mouth (illustrated in following figure). Landmarks can be controlled with a detection request by the Boolean number returnFaceLandmarks. If returnFaceLandmarks is set as true, the returned faces will have landmark attributes.

For more details, please refer to the guide Face - Detect.

HowToDetectFace

Face Rectangle

Face rectangle is derived from the detection results, which is an upright rectangle (left, top, width, height) in images in pixels. The top-left corner of a face (left, top), besides the width and height, indicates face sizes in x and y axes respectively.

For more details, please refer to the guide Face - Detect.

Facial Hair (Attribute)

Facial hair is one of the attributes used to describe the facial hair length of the available faces. The facial hair attribute is optional in the detection results, and can be controlled with a detection request by returnFaceAttributes. If returnFaceAttributes contains 'facialHair', the returned faces will have facial hair attributes.

For more details, please refer to the guide Face - Detect.

FaceList

FaceList is a collection of PersistedFace and is the unit of Find Similar. A FaceList comes with a FaceList ID, as well as other attributes such as Name and User Data.

For more details, please refer to the following guides: FaceList - Create, FaceList - Get.

FaceList ID

FaceList ID is a user provided string used as an identifier of a FaceList. The FaceList ID must be unique within the subscription.

For more details, please refer to the following guides: FaceList - Create, FaceList - Get.

Find Similar

This API is used to search/query similar faces based on a collection of faces. Query faces and face collections are represented as face IDs or FceList ID/LargeFaceList ID in the request. Returned results are searched similar faces, represented by face IDs or PersistedFace IDs.

For more details, please refer to the following guides: Face - Find Similar, LargeFaceList - Create, FaceList - Create.

G

Gender (Attribute)

Gender is one of the attributes used to describe the genders of the available faces. The gender attribute is optional in the detection results, and can be controlled with a detection request by returnFaceAttributes. If returnfaceAttributes contains 'gender', the returned faces will have gender attributes.

For more details, please refer to the guide Face - Detect.

Grouping

Face grouping is the grouping of a collection of faces according to facial similarities. Face collections are indicated by the face ID collections in the request. As a result of grouping, similar faces are grouped together as groups, and faces that are not similar to any other face are merged together as a messy group. There is at the most, one messy group in the grouping result.

For more details, please refer to the guide Face - Group.

Groups

Groups are derived from the grouping results. Each group contains a collection of similar faces, where faces are indicated by face IDs.

For more details, please refer to the guide Face - Group.

H

Head Pose (Attribute)

Head pose is one of the attributes that represents face orientation in 3D space according to roll, pitch and yaw angles, as shown in following figure. The value ranges of roll and yaw are [-180, 180] and [-90, 90] in degrees. In the current version, the pitch value returned from detection is always 0. The head pose attribute is optional in the detection results, and can be controlled with a detection request by the returnFaceAttributes parameter. If returnFaceAttributes parameter contains 'headPose', the returned faces will have head pose attributes.

For more details, please refer to the guide Face - Detect.

GlossaryHeadPose

I

Identification

Identification is to identify one or more faces from a LargePersonGroup/PersonGroup. A PersonGroup/LargePersonGroup is a collection of Persons. Faces and the LargePersonGroup/PersonGroup are represented by face IDs and LargePersonGroup IDs/PersonGroup IDs respectively in the request. Identified results are candidates, represented by Persons with confidence. Multiple faces in the input are considered separately, and each face will have its own identified result.

Note

The LargePersonGroup/PersonGroup should be trained successfully before identification. If the LargePersonGroup/PersonGroup is not trained, or the training status is not shown as 'succeeded' (i.e. 'running', 'failed', or 'timeout'), the request response is 400.

For more details, please refer to the following guides: Face - Identify, LargePersonGroup Person - Create, LargePersonGroup - Create, LargePersonGroup - Train, PersonGroup Person - Create, PersonGroup - Create, PersonGroup - Train.

IsIdentical

IsIdentical is a Boolean field of verification results indicating whether two faces belong to the same person.

For more details, please refer to the guide Face - Verify.

J

K

L

Landmarks

Please see face landmarks.

LargeFaceList

LargeFaceList is a collection of PersistedFace and is the unit of Find Similar. A LargeFaceList comes with a LargeFaceList ID, as well as other attributes such as Name and User Data.

For more details, please refer to the following guides: LargeFaceList - Create, LargeFaceList - Get, LargeFaceList - List Face.

LargeFaceList ID

LargeFaceList ID is a user provided string used as an identifier of a LargeFaceList. The LargeFaceList ID must be unique within the subscription.

For more details, please refer to the following guides: LargeFaceList - Create, LargeFaceList - Get.

LargePersonGroup

LargePersonGroup is a collection of Persons and is the unit of Identification. A LargePersonGroup comes with a LargePersonGroup ID, as well as other attributes such as Name and User Data.

For more details, please refer to the following guides: LargePersonGroup - Create, LargePersonGroup - Get, LargePersonGroup Person - List.

LargePersonGroup ID

LargePersonGroup ID is a user provided string used as an identifier of a LargePersonGroup. The LargePersonGroup ID must be unique within the subscription.

For more details, please refer to the following guides: LargePersonGroup - Create, LargePersonGroup - Get.

M

Messy group

Messy group is derived from the grouping results; which contains faces not similar to any other face. Each face in a messy group is indicated by the face ID.

For more details, please refer to the guide Face - Group.

N

Name (Person)

Name is a user friendly descriptive string for Person. Unlike the Person ID, the name of people can be duplicated within a group.

For more details, please refer to the following guides: LargePersonGroup Person - Create, LargePersonGroup Person - Get, PersonGroup Person - Create, PersonGroup Person - Get.

Name (LargePersonGroup/PersonGroup)

Name is also a user friendly descriptive string for LargePersonGroup/PersonGroup. Unlike the LargePersonGroup ID/PersonGroup ID, the name of LargePersonGroups/PersonGroups can be duplicated within a subscription.

For more details, please refer to the following guides: LargePersonGroup - Create, LargePersonGroup - Get, PersonGroup - Create, PersonGroup - Get.

O

P

PersistedFace

PersistedFace is a data structure in Face API. PersistedFace comes with a PersistedFace ID, as well as other attributes such as Name, and User Data.

For more details, please refer to the following guides: LargeFaceList - Add Face, FaceList - Add Face, LargePersonGroup Person - Add Face, PersonGroup Person - Add Face.

Person ID

Person ID is generated when a PersistedFace is created successfully. A string is created to represent this Face in Face API.

For more details, please refer to the following guides: LargeFaceList - Add Face, FaceList - Add Face, LargePersonGroup Person - Add Face, PersonGroup Person - Add Face.

Person

Person is a data structure managed in Face API. Person comes with a Person ID, as well as other attributes such as Name, a collection of PersistedFace, and User Data.

For more details, please refer to the following guides: LargePersonGroup Person - Create, LargePersonGroup Person - Get, PersonGroup Person - Create, PersonGroup Person - Get.

Person ID

Person ID is generated when a Person is created successfully. A string is created to represent this person in Face API.

For more details, please refer to the following guides: LargePersonGroup Person - Create, LargePersonGroup Person - Get, PersonGroup Person - Create, PersonGroup Person - Get.

PersonGroup

PersonGroup is a collection of Persons and is the unit of Identification. A PersonGroup comes with a PersonGroup ID, as well as other attributes such as Name and User Data.

For more details, please refer to the following guides: PersonGroup - Create, PersonGroup - Get, PersonGroup Person - List.

PersonGroup ID

PersonGroup ID is a user provided string used as an identifier of a PersonGroup. The group ID must be unique within the subscription.

For more details, please refer to the following guides: PersonGroup - Create, PersonGroup - Get.

Pose (Attribute)

Please see Head Pose.

Q

R

Recognition

Recognition is a popular application area for face technologies, such as Find Similar, Grouping, Identify,verifying two faces same or not.

For more details, please refer to the following guides: Face - Find Similar, Face - Group, Face - Identify, Face - Verify.

Rectangle (Face)

Please see face rectangle.

S

Smile (Attribute)

Smile is one of the attributes used to describe the smile expression of the available faces. The smile attribute is optional in the detection results, and can be controlled with a detection request by returnFaceAttributes. If returnFaceAttributes contains 'smile', the returned faces will have smile attributes.

For more details, please refer to the guide Face - Detect.

Similar Face Searching

Please see Find Similar.

Status (Train)

Status is a string used to describe the procedure for Training LargeFaceList/LargePersonGroups/PersonGroups, including 'notstarted', 'running', 'succeeded', 'failed'.

For more details, please refer to the guide LargeFaceList - Train, LargePersonGroup - Train, PersonGroup - Train.

Subscription key

Subscription key is a string that you need to specify as a query string parameter in order to invoke any Face API. The subscription key can be found in My Subscriptions page after you sign in to Microsoft Cognitive Services portal. There will be two keys associated with each subscription: one primary key and one secondary key. Both can be used to invoke API identically. You need to keep the subscription keys secure, and you can regenerate subscription keys at any time from My Subscriptions page as well.

T

Train (LargeFaceList/LargePersonGroup/PersonGroup)

This API is used to pre-process the LargeFaceList/LargePersonGroup/PersonGroup to ensure the Find Similar/Identification performance. If the training is not operated, or the Training Status is not shown as succeeded, the identification for this PersonGroup will result in failure.

For more details, please refer to the following guides: LargeFaceList - Train, LargePersonGroup - Train, PersonGroup - Train, Face - Identify.

U

UserData/User Data

User data is extra information associated with Person and PersonGroup/LargePersonGroup. User data is set by users to make data easier to use, understand and remember.

For more details, please refer to the following guides: LargePersonGroup - Create, LargePersonGroup - Update, LargePersonGroup Person - Create, LargePersonGroup Person - Update, PersonGroup - Create, PersonGroup - Update, PersonGroup Person - Create, PersonGroup Person - Update.

V

Verification

This API is used to verify whether two faces are the same or not. Both faces are represented as face IDs in the request. Verified results contain a Boolean field (isIdentical) indicating same if true and a number field (confidence) indicating the level of confidence.

For more details, please refer to the guide Face - Verify.

W

X

Y

Z