SearchUsersByImage
searches the specified CollectionID for users in a
collection that match the largest face detected in a supplied image. By default,
SearchUsersByImage returns UserIDs for which the similarity score is greater than 80%.
The similarity indicates how closely the UserID matches the largest face detected in the
supplied image. If multiple UserIDs are returned, they are listed in order of highest
similarity score to lowest. Optionally, you can use the UserMatchThreshold to specify a
different value. For more information, see Managing users in a collection.
To search users by image (SDK)
-
If you haven't already:
-
Create or update a user with
AmazonRekognitionFullAccess
permissions. For more information, see Step 1: Set up an AWS account and create a User. -
Install and configure the AWS CLI and the AWS SDKs. For more information, see Step 2: Set up the AWS CLI and AWS SDKs.
-
-
Use the following examples to call the
SearchUsersByImage
operation.This Java example searchers the users in a collection based off an inpute image, using the
SearchUsersByImage
operation.import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.Image; import com.amazonaws.services.rekognition.model.S3Object; import com.amazonaws.services.rekognition.model.SearchUsersByImageRequest; import com.amazonaws.services.rekognition.model.SearchUsersByImageResult; import com.amazonaws.services.rekognition.model.UserMatch; public class SearchUsersByImage { //Replace bucket, collectionId and photo with your values. public static final String collectionId = "MyCollection"; public static final String s3Bucket = "bucket"; public static final String s3PhotoFileKey = "input.jpg"; public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); // Get an image object from S3 bucket. Image image = new Image() .withS3Object(new S3Object() .withBucket(s3Bucket) .withName(s3PhotoFileKey)); // Search collection for users similar to the largest face in the image. SearchUsersByImageRequest request = new SearchUsersByImageRequest() .withCollectionId(collectionId) .withImage(image) .withUserMatchThreshold(70F) .withMaxUsers(2); SearchUsersByImageResult result = rekognitionClient.searchUsersByImage(request); System.out.println("Printing search result with matched user and similarity score"); for (UserMatch match: result.getUserMatches()) { System.out.println(match.getUser().getUserId() + " with similarity score " + match.getSimilarity()); } } }
SearchUsersByImage operation
request
The request for SearchUsersByImage
includes the the collection to
search in and the source image location. In this example, the source image is stored
in an Amazon S3 bucket ( S3Object
). Also specified are the maximum
number of users to return ( MaxUsers
) and the minimum confidence that
must be matched for a user to be returned ( UserMatchThreshold
).
{
"CollectionId": "MyCollection",
"Image": {
"S3Object": {
"Bucket": "bucket",
"Name": "input.jpg"
}
},
"MaxUsers": 2,
"UserMatchThreshold": 99
}
SearchUsersByImage operation
response
The response for SearchUsersByImage
includes a
FaceDetail
object for the SearchedFace
, as well as a
list of UserMatches with the UserId
, Similarity
, and
UserStatus
for each. If the input image contained more than one
face, a list of UnsearchedFaces will be also returned.
{
"SearchedFace": {
"FaceDetail": {
"BoundingBox": {
"Width": 0.23692893981933594,
"Top": 0.19235000014305115,
"Left": 0.39177176356315613,
"Height": 0.5437348484992981
}
}
},
"UserMatches": [
{
"User": {
"UserId": "demoUser1",
"UserStatus": "ACTIVE"
},
"Similarity": 100.0
},
{
"User": {
"UserId": "demoUser2",
"UserStatus": "ACTIVE"
},
"Similarity": 99.97946166992188
}
],
"FaceModelVersion": "6",
"UnsearchedFaces": [
{
"FaceDetails": {
"BoundingBox": {
"Width": 0.031677018851041794,
"Top": 0.5593535900115967,
"Left": 0.6102562546730042,
"Height": 0.0682177022099495
}
},
"Reasons": [
"FACE_NOT_LARGEST"
]
},
{
"FaceDetails": {
"BoundingBox": {
"Width": 0.03254449740052223,
"Top": 0.6080358028411865,
"Left": 0.516062319278717,
"Height": 0.06347997486591339
}
},
"Reasons": [
"FACE_NOT_LARGEST"
]
}
]
}