2017/05/25 - Amazon Rekognition - 1 updated api methods
Changes Update rekognition client to latest version
{'FaceMatches': {'Face': {'Landmarks': [{'Type': 'EYE_LEFT | EYE_RIGHT | NOSE '
'| MOUTH_LEFT | MOUTH_RIGHT | '
'LEFT_EYEBROW_LEFT | '
'LEFT_EYEBROW_RIGHT | '
'LEFT_EYEBROW_UP | '
'RIGHT_EYEBROW_LEFT | '
'RIGHT_EYEBROW_RIGHT | '
'RIGHT_EYEBROW_UP | '
'LEFT_EYE_LEFT | '
'LEFT_EYE_RIGHT | LEFT_EYE_UP '
'| LEFT_EYE_DOWN | '
'RIGHT_EYE_LEFT | '
'RIGHT_EYE_RIGHT | '
'RIGHT_EYE_UP | '
'RIGHT_EYE_DOWN | NOSE_LEFT | '
'NOSE_RIGHT | MOUTH_UP | '
'MOUTH_DOWN | LEFT_PUPIL | '
'RIGHT_PUPIL',
'X': 'float',
'Y': 'float'}],
'Pose': {'Pitch': 'float',
'Roll': 'float',
'Yaw': 'float'},
'Quality': {'Brightness': 'float',
'Sharpness': 'float'}}},
'SourceImageOrientationCorrection': 'ROTATE_0 | ROTATE_90 | ROTATE_180 | '
'ROTATE_270',
'TargetImageOrientationCorrection': 'ROTATE_0 | ROTATE_90 | ROTATE_180 | '
'ROTATE_270',
'UnmatchedFaces': [{'BoundingBox': {'Height': 'float',
'Left': 'float',
'Top': 'float',
'Width': 'float'},
'Confidence': 'float',
'Landmarks': [{'Type': 'EYE_LEFT | EYE_RIGHT | NOSE | '
'MOUTH_LEFT | MOUTH_RIGHT | '
'LEFT_EYEBROW_LEFT | '
'LEFT_EYEBROW_RIGHT | '
'LEFT_EYEBROW_UP | '
'RIGHT_EYEBROW_LEFT | '
'RIGHT_EYEBROW_RIGHT | '
'RIGHT_EYEBROW_UP | LEFT_EYE_LEFT '
'| LEFT_EYE_RIGHT | LEFT_EYE_UP | '
'LEFT_EYE_DOWN | RIGHT_EYE_LEFT | '
'RIGHT_EYE_RIGHT | RIGHT_EYE_UP | '
'RIGHT_EYE_DOWN | NOSE_LEFT | '
'NOSE_RIGHT | MOUTH_UP | '
'MOUTH_DOWN | LEFT_PUPIL | '
'RIGHT_PUPIL',
'X': 'float',
'Y': 'float'}],
'Pose': {'Pitch': 'float',
'Roll': 'float',
'Yaw': 'float'},
'Quality': {'Brightness': 'float', 'Sharpness': 'float'}}]}
Compares a face in the source input image with each face detected in the target input image.
In response, the operation returns an array of face matches ordered by similarity score in descending order. For each face match, the response provides a bounding box of the face, facial landmarks, pose details (pitch, role, and yaw), quality (brightness and sharpness), and confidence value (indicating the level of confidence that the bounding box contains a face). The response also provides a similarity score, which indicates how closely the faces match.
If the image doesn't contain Exif metadata, CompareFaces returns orientation information for the source and target images. Use these values to display the images with the correct image orientation.
For an example, see get-started-exercise-compare-faces.
This operation requires permissions to perform the rekognition:CompareFaces action.
See also: AWS API Documentation
Request Syntax
client.compare_faces(
SourceImage={
'Bytes': b'bytes',
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
}
},
TargetImage={
'Bytes': b'bytes',
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
}
},
SimilarityThreshold=...
)
dict
[REQUIRED]
The source image, either as bytes or as an S3 object.
Bytes (bytes) --
Blob of image bytes up to 5 MBs.
S3Object (dict) --
Identifies an S3 object as the image source.
Bucket (string) --
Name of the S3 bucket.
Name (string) --
S3 object key name.
Version (string) --
If the bucket is versioning enabled, you can specify the object version.
dict
[REQUIRED]
The target image, either as bytes or as an S3 object.
Bytes (bytes) --
Blob of image bytes up to 5 MBs.
S3Object (dict) --
Identifies an S3 object as the image source.
Bucket (string) --
Name of the S3 bucket.
Name (string) --
S3 object key name.
Version (string) --
If the bucket is versioning enabled, you can specify the object version.
float
The minimum level of confidence in the face matches that a match must meet to be included in the FaceMatches array.
dict
Response Syntax
{
'SourceImageFace': {
'BoundingBox': {
'Width': ...,
'Height': ...,
'Left': ...,
'Top': ...
},
'Confidence': ...
},
'FaceMatches': [
{
'Similarity': ...,
'Face': {
'BoundingBox': {
'Width': ...,
'Height': ...,
'Left': ...,
'Top': ...
},
'Confidence': ...,
'Landmarks': [
{
'Type': 'EYE_LEFT'|'EYE_RIGHT'|'NOSE'|'MOUTH_LEFT'|'MOUTH_RIGHT'|'LEFT_EYEBROW_LEFT'|'LEFT_EYEBROW_RIGHT'|'LEFT_EYEBROW_UP'|'RIGHT_EYEBROW_LEFT'|'RIGHT_EYEBROW_RIGHT'|'RIGHT_EYEBROW_UP'|'LEFT_EYE_LEFT'|'LEFT_EYE_RIGHT'|'LEFT_EYE_UP'|'LEFT_EYE_DOWN'|'RIGHT_EYE_LEFT'|'RIGHT_EYE_RIGHT'|'RIGHT_EYE_UP'|'RIGHT_EYE_DOWN'|'NOSE_LEFT'|'NOSE_RIGHT'|'MOUTH_UP'|'MOUTH_DOWN'|'LEFT_PUPIL'|'RIGHT_PUPIL',
'X': ...,
'Y': ...
},
],
'Pose': {
'Roll': ...,
'Yaw': ...,
'Pitch': ...
},
'Quality': {
'Brightness': ...,
'Sharpness': ...
}
}
},
],
'UnmatchedFaces': [
{
'BoundingBox': {
'Width': ...,
'Height': ...,
'Left': ...,
'Top': ...
},
'Confidence': ...,
'Landmarks': [
{
'Type': 'EYE_LEFT'|'EYE_RIGHT'|'NOSE'|'MOUTH_LEFT'|'MOUTH_RIGHT'|'LEFT_EYEBROW_LEFT'|'LEFT_EYEBROW_RIGHT'|'LEFT_EYEBROW_UP'|'RIGHT_EYEBROW_LEFT'|'RIGHT_EYEBROW_RIGHT'|'RIGHT_EYEBROW_UP'|'LEFT_EYE_LEFT'|'LEFT_EYE_RIGHT'|'LEFT_EYE_UP'|'LEFT_EYE_DOWN'|'RIGHT_EYE_LEFT'|'RIGHT_EYE_RIGHT'|'RIGHT_EYE_UP'|'RIGHT_EYE_DOWN'|'NOSE_LEFT'|'NOSE_RIGHT'|'MOUTH_UP'|'MOUTH_DOWN'|'LEFT_PUPIL'|'RIGHT_PUPIL',
'X': ...,
'Y': ...
},
],
'Pose': {
'Roll': ...,
'Yaw': ...,
'Pitch': ...
},
'Quality': {
'Brightness': ...,
'Sharpness': ...
}
},
],
'SourceImageOrientationCorrection': 'ROTATE_0'|'ROTATE_90'|'ROTATE_180'|'ROTATE_270',
'TargetImageOrientationCorrection': 'ROTATE_0'|'ROTATE_90'|'ROTATE_180'|'ROTATE_270'
}
Response Structure
(dict) --
SourceImageFace (dict) --
The face in the source image that was used for comparison.
BoundingBox (dict) --
Identifies the bounding box around the object or face. The left (x-coordinate) and top (y-coordinate) are coordinates representing the top and left sides of the bounding box. Note that the upper-left corner of the image is the origin (0,0).
The top and left values returned are ratios of the overall image size. For example, if the input image is 700x200 pixels, and the top-left coordinate of the bounding box is 350x50 pixels, the API returns a left value of 0.5 (350/700) and a top value of 0.25 (50/200).
The width and height values represent the dimensions of the bounding box as a ratio of the overall image dimension. For example, if the input image is 700x200 pixels, and the bounding box width is 70 pixels, the width returned is 0.1.
Width (float) --
Width of the bounding box as a ratio of the overall image width.
Height (float) --
Height of the bounding box as a ratio of the overall image height.
Left (float) --
Left coordinate of the bounding box as a ratio of overall image width.
Top (float) --
Top coordinate of the bounding box as a ratio of overall image height.
Confidence (float) --
Confidence level that the selected bounding box contains a face.
FaceMatches (list) --
An array of faces in the target image that match the source image face. Each CompareFacesMatch object provides the bounding box, the confidence level that the bounding box contains a face, and the similarity score for the face in the bounding box and the face in the source image.
(dict) --
Provides information about a face in a target image that matches the source image face analysed by CompareFaces. The Face property contains the bounding box of the face in the target image. The Similarity property is the confidence that the source image face matches the face in the bounding box.
Similarity (float) --
Level of confidence that the faces match.
Face (dict) --
Provides face metadata (bounding box and confidence that the bounding box actually contains a face).
BoundingBox (dict) --
Identifies the bounding box around the object or face. The left (x-coordinate) and top (y-coordinate) are coordinates representing the top and left sides of the bounding box. Note that the upper-left corner of the image is the origin (0,0).
The top and left values returned are ratios of the overall image size. For example, if the input image is 700x200 pixels, and the top-left coordinate of the bounding box is 350x50 pixels, the API returns a left value of 0.5 (350/700) and a top value of 0.25 (50/200).
The width and height values represent the dimensions of the bounding box as a ratio of the overall image dimension. For example, if the input image is 700x200 pixels, and the bounding box width is 70 pixels, the width returned is 0.1.
Width (float) --
Width of the bounding box as a ratio of the overall image width.
Height (float) --
Height of the bounding box as a ratio of the overall image height.
Left (float) --
Left coordinate of the bounding box as a ratio of overall image width.
Top (float) --
Top coordinate of the bounding box as a ratio of overall image height.
Confidence (float) --
Level of confidence that what the bounding box contains is a face.
Landmarks (list) --
An array of facial landmarks.
(dict) --
Indicates the location of the landmark on the face.
Type (string) --
Type of the landmark.
X (float) --
x-coordinate from the top left of the landmark expressed as the ration of the width of the image. For example, if the images is 700x200 and the x-coordinate of the landmark is at 350 pixels, this value is 0.5.
Y (float) --
y-coordinate from the top left of the landmark expressed as the ration of the height of the image. For example, if the images is 700x200 and the y-coordinate of the landmark is at 100 pixels, this value is 0.5.
Pose (dict) --
Indicates the pose of the face as determined by its pitch, roll, and yaw.
Roll (float) --
Value representing the face rotation on the roll axis.
Yaw (float) --
Value representing the face rotation on the yaw axis.
Pitch (float) --
Value representing the face rotation on the pitch axis.
Quality (dict) --
Identifies face image brightness and sharpness.
Brightness (float) --
Value representing brightness of the face. The service returns a value between 0 and 100 (inclusive). A higher value indicates a brighter face image.
Sharpness (float) --
Value representing sharpness of the face. The service returns a value between 0 and 100 (inclusive). A higher value indicates a sharper face image.
UnmatchedFaces (list) --
An array of faces in the target image that did not match the source image face.
(dict) --
Provides face metadata for target image faces that are analysed by CompareFaces.
BoundingBox (dict) --
Identifies the bounding box around the object or face. The left (x-coordinate) and top (y-coordinate) are coordinates representing the top and left sides of the bounding box. Note that the upper-left corner of the image is the origin (0,0).
The top and left values returned are ratios of the overall image size. For example, if the input image is 700x200 pixels, and the top-left coordinate of the bounding box is 350x50 pixels, the API returns a left value of 0.5 (350/700) and a top value of 0.25 (50/200).
The width and height values represent the dimensions of the bounding box as a ratio of the overall image dimension. For example, if the input image is 700x200 pixels, and the bounding box width is 70 pixels, the width returned is 0.1.
Width (float) --
Width of the bounding box as a ratio of the overall image width.
Height (float) --
Height of the bounding box as a ratio of the overall image height.
Left (float) --
Left coordinate of the bounding box as a ratio of overall image width.
Top (float) --
Top coordinate of the bounding box as a ratio of overall image height.
Confidence (float) --
Level of confidence that what the bounding box contains is a face.
Landmarks (list) --
An array of facial landmarks.
(dict) --
Indicates the location of the landmark on the face.
Type (string) --
Type of the landmark.
X (float) --
x-coordinate from the top left of the landmark expressed as the ration of the width of the image. For example, if the images is 700x200 and the x-coordinate of the landmark is at 350 pixels, this value is 0.5.
Y (float) --
y-coordinate from the top left of the landmark expressed as the ration of the height of the image. For example, if the images is 700x200 and the y-coordinate of the landmark is at 100 pixels, this value is 0.5.
Pose (dict) --
Indicates the pose of the face as determined by its pitch, roll, and yaw.
Roll (float) --
Value representing the face rotation on the roll axis.
Yaw (float) --
Value representing the face rotation on the yaw axis.
Pitch (float) --
Value representing the face rotation on the pitch axis.
Quality (dict) --
Identifies face image brightness and sharpness.
Brightness (float) --
Value representing brightness of the face. The service returns a value between 0 and 100 (inclusive). A higher value indicates a brighter face image.
Sharpness (float) --
Value representing sharpness of the face. The service returns a value between 0 and 100 (inclusive). A higher value indicates a sharper face image.
SourceImageOrientationCorrection (string) --
The orientation of the source image (counterclockwise direction). If your application displays the source image, you can use this value to correct image orientation. The bounding box coordinates returned in SourceImageFace represent the location of the face before the image orientation is corrected.
TargetImageOrientationCorrection (string) --
The orientation of the target image (in counterclockwise direction). If your application displays the target image, you can use this value to correct the orientation of the image. The bounding box coordinates returned in FaceMatches and UnmatchedFaces represent face locations before the image orientation is corrected.