result objects - SkyBiometry - Cloud-based Face Detection and Recognition API

Posted July 24, 2015

The result of the API call is a JSON or XML object containing the requested information. The following table summarizes response object fields:

result object

Name	Type	Value
groups	array	List of one or more group of faces found in photos, when using faces/group.
group	object	The group of faces found in photos.
uid	string	A matching user id for the group. Only works if the call provides a list of user ids, and an user id is matched with this group.
gid	string	The group id.
tids	string	A list of one or more tag ids. If the gid and uid fields are absent this means this is the ungrouped group. Those are all the faces that had no matching face, or faces that cannot be group at the moment (such as profile posed faces).
photos	array	List of all the photo objects that were included in the request, one photo per URL or image stream specified.
photo	object	The object describing an image included in the request.
url	string	Photo URL as specified in the request or temporary URL for image stream.
pid	string	Photo id, can be used as reference instead of URL for follow-up calls to methods that support it.
width	integer	Photo width in pixels.
height	integer	Photo height in pixels.
tags	array	List of zero or more face tag objects found in the photo.
tag	object	The face object found in a photo.
tid	string	The tag id. Tag ids are temporary until used in tags/save calls to associate the tag with a specific user id, at which point they become persistent.
recognizable	boolean	Value indicating whether this tag that can be recognized or can be used for training set.
threshold	integer	The recommended confidence threshold from 0-100% to use when deciding which recognition results to display (faces/recognize only). The threshold changes based on the quality of faces found, as well as the size of the user ids list specified when calling faces/recognize.
uids	array	List of possible matches for the face tag (faces/recognize only). Only user ids that were specified during the faces/recognize call (either explicitly or through a list) will be returned. Refer to the threshold for a recommendation of which confidence scores are high/low for this call. When tags are saved, the confidence score is always 100.
uid	object	A possible match for the face tag
uid	string	The user id match for the face tag.
confidence	integer	The score from 0-100% interval.
gid	string	The group id.
label	string	Optional text label describing the tag. Must have been previously specified through a tags/add ortags/save call.
confirmed	boolean	Specifies whether a tag has been confirmed or is in a temporary state. Tags are confirmed through calls to tags/add or tags/save. Unconfirmed tags are also referred to as temporary, which means that they are not persisted anywhere. All confirmed tags have the confidence score of 100.
manual	boolean	Value indicating whether the tag was added through the tags/add call which supports manual addition of otherwise undetected faces.
tagger_id	string	The tagging user id.
width	float	Face tag width as 0-100% of photo width.
height	float	Face tag height as 0-100% of photo height.
center	object	Center of face tag point. See point.
eye_left	object	Left eye point. See point.
eye_right	object	Right eye point. See point.
mouth_left	object	Left edge of mouth point. See point.
mouth_right	object	Right edge of mouth point. See point.
mouth_center	object	Mouth center point. See point.
nose	object	Nose tip point. See point.
ear_left	object	Left ear point. See point.
ear_right	object	Right ear point. See point.
chin	object	Chin point. See point.
yaw	float	Yaw (facing sideways) angle value as -90 to 90.
roll	float	Roll (face rotation) angle value as -90 to 90.
pitch	float	Pitch (up or down) angle value as -90 to 90.
attributes	object	List of determined facial attributes. See attributes.
points	array	List of detected facial feature points. Available only if detect_all_feature_points=true is specified in the request.
point	object	Detected facial feature point.
x	float	The X coordinate as 0-100% of photo width.
y	float	The Y coordinate as 0-100% of photo height.
confidence	integer	The confidence level of the point from 0-100% interval.
id	integer	The identifier of the point. Has the following format: 0xTTNN where TT is a point type (01 is MPEG-4, 02 is anthropometric and 03 is FG-NET) and NN is a point number linked to a specific point on the face.
similarities	array	List of similarities of this face tag with other face tags in request (faces/group only).
similarity	object	A similarity score of two faces tags.
tid	string	The tag id of the face matched with tag.
similarity	integer	The score from 0-100% interval.
error_code	integer	Error code, specified only when an error occurs. See errors.
error_message	string	Error message, specified only when an error occurs. See errors.
user_statuses	array	List of training statuses of the users (faces/status only).
user_status	object	The training status of the user.
uid	string	The user id that was trained.
training_set_size	integer	The number of photos used to train this model.
last_trained	integer	The last UTC time value when this user id was trained.
training_in_progress	boolean	Value indicating whether another train is running to the user id at the moment.
no_training_set	array	List of users that were not trained (faces/train only). See user_status.
created	array	List of created users (faces/train only). See user_status.
updated	array	List of updated users (faces/train only). See user_status.
unchanged	array	List of unchanged users (faces/train only). See user_status.
authenticated	boolean	Value specifying whether API usage is authenticated (account/authenticate only).
users	string/string array map	List of namespaces along with list of users in each namespace (account/users only).
namespaces	array	List of namespaces (account/namespaces only).
namespacedata	object	The object describing namespace.
name	string	The name of the namespace.
size	integer	Number of users in the namespace.
share_mode	string	Share mode of the namespace. Valid values are “Public”, “Private” and “Public Read-Only”.
owner	boolean	Value specifying whether the namespace in owned by the API user.
saved_tags	array	List of saved tags (tags/save only).
saved_tag	object	The object describing saved tag.
detected_tid	string	Detected tag id.
tid	string	Tag id.
removed_tags	array	List of removed tags (tags/remove only).
removed_tag	object	The object describing removed tag.
removed_tid	string	Removed tag id.
tid	string	Tag id.
message	string	Message from tag operation.
callback_url	string	The callback URL specified in request.
status	string	Status of the request. Valid values are “success”, “partial” and “failure”. See errors.
error_code	integer	Error code, specified only when an error occurs. See errors.
error_message	string	Error message, specified only when an error occurs. See errors.
usage	object	The usage of the API. All rate limited methods and account/limits return this object.
used	integer	Amount of photos that were processed since last rate-limit reset time (1 hour, 1 day or 1 month depending on what limits are configured in the account).
remaining	integer	Amount of photos remaining in current time window.
limit	integer	The total photos limit permitted in the current time window.
reset_time	integer	GMT Unix-timestamp of next limit reset time.
reset_time_text	string	GMT Unix timestamp of next limit reset time (in text).
namespace_used	integer	Amount of trained user tags in the namespace(s).
namespace_remaining	integer	Amount of remaining space for trained user tags in the namespace(s).
namespace_limit	integer	The maximum amount of trained user tags that can be stored in the namespace(s).
operation_id	string	The identifier of the operation that can be used when contacting our support.

Yaw (rotation about Y axis), roll (rotation about Z axis) and pitch (rotation about X axis) angles are provided in degrees in range from -90 to 90. They are Tait-Bryan angles in right-hand 3D Euclidian space in image coordinate system (i.e. X axis is horizontal and points towards the right edge of the image, Y axis is vertical and points towards the bottom edge of the image and Z axis is perpendicular to the image and points away from the viewer). The rotation is reported as it would be performed about geometrical center of the head in the following order: roll (with positive direction being clockwise, towards the left shoulder of the subject), pitch (with positive direction being down) and yaw (with positive direction being to the left, towards the right shoulder of the subject). Remember that subjects are mirrored in the photo, i.e. subject’s left eye and left body parts are at the right and vice versa.

Pavelas