Amazon Rekognition
Developer Guide

Example 3: Searching Faces

This section provides working examples of API operations that you can use to search a face collection for face matches. Examples using both AWS CLI and AWS SDK for Java are provided.

For information about collections and search faces API operations, see Storage-Based API Operations: Storing Faces and Searching Face Matches.

Searching Faces: Using the AWS CLI

You can search a face collection for face matches using the search-faces (see SearchFaces) and search-faces-by-image (see SearchFacesByImage) commands:

  • Search faces by face ID – You can use the search-faces command to search a face collection for face matches by providing a face ID (that is, one of the face IDs that exists in the face collection). Then, the command searches the collection for similar faces.

    For this exercise, if you don't know a face ID value, you can use the list-faces command:

    aws rekognition list-faces \ --collection-id "collection-id" \ --region us-east-1 \ --profile adminuser

    Specify the search-faces command, as shown following:

    aws rekognition search-faces \ --face-id face-id \ --collection-id "collection-id" \ --region us-east-1 \ --profile adminuser

    The following is the example response that includes the search face ID you provided as input and three face matches. For more information about the response, see Searching Faces in a Face Collection.

    { "SearchedFaceId": "e0182208-f475-55b4-8d88-cf162509718d", "FaceMatches": [ { "Face": { "BoundingBox": { "Width": 0.49505001306533813, "Top": 0.221110999584198, "Left": 0.3069309890270233, "Height": 0.33333298563957214 }, "FaceId": "9b01ac35-61be-55b0-bc95-54b6421e4950", "ExternalImageId": "example-image.jpg", "Confidence": 99.99949645996094, "ImageId": "fba488d7-9c3a-537f-a30a-b8a1ee326b6c" }, "Similarity": 0.9172449111938477 }, { "Face": { "BoundingBox": { "Width": 0.2044440060853958, "Top": 0.22542400658130646, "Left": 0.46222200989723206, "Height": 0.3118639886379242 }, "FaceId": "98fd3f10-a078-5b35-83c5-5d5c8423a8fc", "ExternalImageId": "example-image.jpg", "Confidence": 99.99810028076172, "ImageId": "b5d3f633-1b8c-560a-adfb-08891b6536a0" }, "Similarity": 0.9123537540435791 }, { "Face": { "BoundingBox": { "Width": 0.6153849959373474, "Top": 0.24423100054264069, "Left": 0.17654499411582947, "Height": 0.4692310094833374 }, "FaceId": "407b95a5-f8f7-50c7-bf86-27c9ba5c6931", "ExternalImageId": "example-image.jpg", "Confidence": 99.99970245361328, "ImageId": "af554b0d-fcb2-56e8-9658-69aec6c901be" }, "Similarity": 0.6758826971054077 } ] }
  • Search faces by providing an image as input – In this case, Amazon Rekognition first detects the face in the input image, and then searches the collection for matching faces. The following search-faces-by-image command specifies an S3 object as input image.

    aws rekognition search-faces-by-image \ --image '{"S3Object":{"Bucket":"bucket-name","Name":"Example.jpg"}}' \ --collection-id "collection-id" \ --region us-east-1 \ --profile adminuser

    The following is an example response that includes the bounding box of the face in the input image, and a list of face matches. For more information about the response, see Searching Faces in a Face Collection.

    { "SearchedFaceBoundingBox": { "Width": 0.10111111402511597, "Top": 0.32203391194343567, "Left": 0.23999999463558197, "Height": 0.1542372852563858 }, "SearchedFaceConfidence": 98.51010131835938, "FaceMatches": [ { "Face": { "BoundingBox": { "Width": 0.10111100226640701, "Top": 0.32203400135040283, "Left": 0.23999999463558197, "Height": 0.15423700213432312 }, "FaceId": "e0182208-f475-55b4-8d88-cf162509718d", "ExternalImageId": "example-image.jpg", "Confidence": 98.51010131835938, "ImageId": "b5d3f633-1b8c-560a-adfb-08891b6536a0" }, "Similarity": 99.9808578491211 } ] }

Searching Faces: Using the AWS SDK for Java

The following AWS SDK for Java code example stores three faces to an Amazon Rekognition face collection. Then, it searches the face collection for face matches. It shows usage of both SearchFaces and SearchFacesByImage API operations. The code example specifies both the FaceMatchThreshold and MaxFaces parameters to limit the results returned in the response.

import java.util.List; import com.amazonaws.AmazonClientException; import com.amazonaws.auth.AWSCredentials; import com.amazonaws.auth.AWSStaticCredentialsProvider; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.regions.Regions; import; import; import; import; import; import; import; import; import; import; import; public class SearchFacesExample { public static final String COLLECTION_ID = "collectionid"; public static final String S3_BUCKET = "S3Bucket"; public static void main(String[] args) throws Exception { AWSCredentials credentials; try { credentials = new ProfileCredentialsProvider("AdminUser").getCredentials(); } catch (Exception e) { throw new AmazonClientException( "Cannot load the credentials from the credential profiles file. " + "Please make sure that your credentials file is at the correct " + "location (/Users/userid/.aws/credentials), and is in a valid format.", e); } AmazonRekognition amazonRekognition = AmazonRekognitionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCredentials(new AWSStaticCredentialsProvider(credentials)) .build(); IndexFacesResult indexFacesResult = callIndexFaces(COLLECTION_ID, amazonRekognition, "image1.jpg"); //2. Retrieve face ID of the 1st face added. String faceId = indexFacesResult.getFaceRecords().stream() .map(f-> f.getFace().getFaceId()) .findFirst().orElseThrow(()-> new IllegalArgumentException( "No face found")); callIndexFaces(COLLECTION_ID, amazonRekognition, "image2.jpg"); callIndexFaces(COLLECTION_ID, amazonRekognition, "image3.jpg"); Float threshold = 70F; int maxFaces = 2; //3. Search similar faces for a give face (identified by face ID). System.out.println("Faces matching FaceId: " + faceId); SearchFacesResult searchFacesResult = callSearchFaces(COLLECTION_ID, faceId, threshold, maxFaces, amazonRekognition); List < FaceMatch > faceMatches = searchFacesResult.getFaceMatches(); for (FaceMatch face: faceMatches) { System.out.println(face.getFace().toString()); System.out.println(); } //4. Get an image object in S3 bucket. String fileName = "imagex.jpg"; Image image = getImageUtil(S3_BUCKET, fileName); //5. Search collection for faces similar to the largest face in the image. SearchFacesByImageResult searchFacesByImageResult = callSearchFacesByImage(COLLECTION_ID, image, threshold, maxFaces, amazonRekognition); System.out.println("Faces matching largest face in image " + fileName); List < FaceMatch > faceImageMatches = searchFacesByImageResult.getFaceMatches(); for (FaceMatch face: faceImageMatches) { System.out.println(face.getFace().toString()); System.out.println(); } } private static IndexFacesResult callIndexFaces( String collectionId, AmazonRekognition amazonRekognition, String name) { IndexFacesRequest req = new IndexFacesRequest() .withImage(getImageUtil(S3_BUCKET, name)) .withCollectionId(collectionId) .withExternalImageId(name); return amazonRekognition.indexFaces(req); } private static SearchFacesByImageResult callSearchFacesByImage(String collectionId, Image image, Float threshold, int maxFaces, AmazonRekognition amazonRekognition ) { SearchFacesByImageRequest searchFacesByImageRequest = new SearchFacesByImageRequest() .withCollectionId(collectionId) .withImage(image) .withFaceMatchThreshold(threshold) .withMaxFaces(maxFaces); return amazonRekognition.searchFacesByImage(searchFacesByImageRequest); } private static SearchFacesResult callSearchFaces(String collectionId, String faceId, Float threshold, int maxFaces, AmazonRekognition amazonRekognition) { SearchFacesRequest searchFacesRequest = new SearchFacesRequest() .withCollectionId(collectionId) .withFaceId(faceId) .withFaceMatchThreshold(threshold) .withMaxFaces(maxFaces); return amazonRekognition.searchFaces(searchFacesRequest); } private static Image getImageUtil(String bucket, String key) { return new Image() .withS3Object(new S3Object() .withBucket(bucket) .withName(key)); } }