Searching for a face with a face
ID
You can use the SearchFaces
operation to search for users in a collection that match the largest face in a supplied
image.
The face ID is returned in the IndexFaces
operation response when the face is detected and added to a collection. For more
information, see Managing faces in a collection.
To search for a face in a collection using its face ID (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 SearchFaces
operation.
- Java
-
This example displays information about faces that match a face
identified by its ID.
Change the value of collectionID to the collection
that contains the required face. Change the value of
faceId to the identifier of the face you want to
find.
//Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
//PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.)
package aws.example.rekognition.image;
import com.amazonaws.services.rekognition.AmazonRekognition;
import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.amazonaws.services.rekognition.model.FaceMatch;
import com.amazonaws.services.rekognition.model.SearchFacesRequest;
import com.amazonaws.services.rekognition.model.SearchFacesResult;
import java.util.List;
public class SearchFaceMatchingIdCollection {
public static final String collectionId = "MyCollection";
public static final String faceId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
public static void main(String[] args) throws Exception {
AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient();
ObjectMapper objectMapper = new ObjectMapper();
// Search collection for faces matching the face id.
SearchFacesRequest searchFacesRequest = new SearchFacesRequest()
.withCollectionId(collectionId)
.withFaceId(faceId)
.withFaceMatchThreshold(70F)
.withMaxFaces(2);
SearchFacesResult searchFacesByIdResult =
rekognitionClient.searchFaces(searchFacesRequest);
System.out.println("Face matching faceId " + faceId);
List < FaceMatch > faceImageMatches = searchFacesByIdResult.getFaceMatches();
for (FaceMatch face: faceImageMatches) {
System.out.println(objectMapper.writerWithDefaultPrettyPrinter()
.writeValueAsString(face));
System.out.println();
}
}
}
Run the example code. Information about matching faces is
displayed.
- Java V2
-
This code is taken from the AWS Documentation SDK examples
GitHub repository. See the full example here.
// snippet-start:[rekognition.java2.match_faces_collection.import]
import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.rekognition.RekognitionClient;
import software.amazon.awssdk.services.rekognition.model.SearchFacesRequest;
import software.amazon.awssdk.services.rekognition.model.SearchFacesResponse;
import software.amazon.awssdk.services.rekognition.model.FaceMatch;
import software.amazon.awssdk.services.rekognition.model.RekognitionException;
import java.util.List;
// snippet-end:[rekognition.java2.match_faces_collection.import]
/**
* Before running this Java V2 code example, set up your development environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*/
public class SearchFaceMatchingIdCollection {
public static void main(String[] args) {
final String usage = "\n" +
"Usage: " +
" <collectionId> <sourceImage>\n\n" +
"Where:\n" +
" collectionId - The id of the collection. \n" +
" sourceImage - The path to the image (for example, C:\\AWS\\pic1.png). \n\n";
if (args.length != 2) {
System.out.println(usage);
System.exit(1);
}
String collectionId = args[0];
String faceId = args[1];
Region region = Region.US_EAST_1;
RekognitionClient rekClient = RekognitionClient.builder()
.region(region)
.credentialsProvider(ProfileCredentialsProvider.create("profile-name"))
.build();
System.out.println("Searching for a face in a collections");
searchFacebyId(rekClient, collectionId, faceId ) ;
rekClient.close();
}
// snippet-start:[rekognition.java2.match_faces_collection.main]
public static void searchFacebyId(RekognitionClient rekClient,String collectionId, String faceId) {
try {
SearchFacesRequest searchFacesRequest = SearchFacesRequest.builder()
.collectionId(collectionId)
.faceId(faceId)
.faceMatchThreshold(70F)
.maxFaces(2)
.build();
SearchFacesResponse imageResponse = rekClient.searchFaces(searchFacesRequest) ;
System.out.println("Faces matching in the collection");
List<FaceMatch> faceImageMatches = imageResponse.faceMatches();
for (FaceMatch face: faceImageMatches) {
System.out.println("The similarity level is "+face.similarity());
System.out.println();
}
} catch (RekognitionException e) {
System.out.println(e.getMessage());
System.exit(1);
}
}
// snippet-end:[rekognition.java2.match_faces_collection.main]
}
- AWS CLI
-
This AWS CLI command displays the JSON output for the
search-faces CLI operation. Replace the value of
face-id with the face identifier that you want to
search for, and replace the value of collection-id with
the collection you want to search in. Replace the value of
profile_name in the line that creates the Rekognition
session with the name of your developer profile.
aws rekognition search-faces --face-id face-id --collection-id "collection-id" --profile profile-name
- Python
-
This example displays information about faces that match a face
identified by its ID.
Change the value of collectionID to the collection
that contains the required face. Change the value of
faceId to the identifier of the face you want to
find. Replace the value of profile_name in the line
that creates the Rekognition session with the name of your developer
profile.
# Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.)
import boto3
def search_face_in_collection(face_id, collection_id):
threshold = 90
max_faces = 2
session = boto3.Session(profile_name='profile-name')
client = session.client('rekognition')
response = client.search_faces(CollectionId=collection_id,
FaceId=face_id,
FaceMatchThreshold=threshold,
MaxFaces=max_faces)
face_matches = response['FaceMatches']
print('Matching faces')
for match in face_matches:
print('FaceId:' + match['Face']['FaceId'])
print('Similarity: ' + "{:.2f}".format(match['Similarity']) + "%")
return len(face_matches)
def main():
face_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
collection_id = 'collection-id'
faces = []
faces.append(face_id)
faces_count = search_face_in_collection(face_id, collection_id)
print("faces found: " + str(faces_count))
if __name__ == "__main__":
main()
- .NET
-
This example displays information about faces that match a face
identified by its ID.
Change the value of collectionID to the collection
that contains the required face. Change the value of
faceId to the identifier of the face that you want
to find.
//Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
//PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.)
using System;
using Amazon.Rekognition;
using Amazon.Rekognition.Model;
public class SearchFacesMatchingId
{
public static void Example()
{
String collectionId = "MyCollection";
String faceId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient();
// Search collection for faces matching the face id.
SearchFacesRequest searchFacesRequest = new SearchFacesRequest()
{
CollectionId = collectionId,
FaceId = faceId,
FaceMatchThreshold = 70F,
MaxFaces = 2
};
SearchFacesResponse searchFacesResponse = rekognitionClient.SearchFaces(searchFacesRequest);
Console.WriteLine("Face matching faceId " + faceId);
Console.WriteLine("Matche(s): ");
foreach (FaceMatch face in searchFacesResponse.FaceMatches)
Console.WriteLine("FaceId: " + face.Face.FaceId + ", Similarity: " + face.Similarity);
}
}
Run the example code. Information about matching faces is
displayed.
SearchFaces operation
request
Given a face ID (each face stored in the face collection has a face ID),
SearchFaces searches the specified face collection for similar
faces. The response doesn't include the face you are searching for. It includes only
similar faces. By default, SearchFaces returns faces for which the
algorithm detects similarity of greater than 80%. The similarity indicates how
closely the face matches with the input face. Optionally, you can use
FaceMatchThreshold to specify a different value.
{
"CollectionId": "MyCollection",
"FaceId": "0b683aed-a0f1-48b2-9b5e-139e9cc2a757",
"MaxFaces": 2,
"FaceMatchThreshold": 99
}
SearchFaces operation
response
The operation returns an array of face matches that were found and the face ID you
provided as input.
{
"SearchedFaceId": "7ecf8c19-5274-5917-9c91-1db9ae0449e2",
"FaceMatches": [ list of face matches found ]
}
For each face match that was found, the response includes similarity and face
metadata, as shown in the following example response:
{
...
"FaceMatches": [
{
"Similarity": 100.0,
"Face": {
"BoundingBox": {
"Width": 0.6154,
"Top": 0.2442,
"Left": 0.1765,
"Height": 0.4692
},
"FaceId": "84de1c86-5059-53f2-a432-34ebb704615d",
"Confidence": 99.9997,
"ImageId": "d38ebf91-1a11-58fc-ba42-f978b3f32f60"
}
},
{
"Similarity": 84.6859,
"Face": {
"BoundingBox": {
"Width": 0.2044,
"Top": 0.2254,
"Left": 0.4622,
"Height": 0.3119
},
"FaceId": "6fc892c7-5739-50da-a0d7-80cc92c0ba54",
"Confidence": 99.9981,
"ImageId": "5d913eaf-cf7f-5e09-8c8f-cb1bdea8e6aa"
}
}
]
}
