* For a given input image, first detects the largest face in the image, and * then searches the specified collection for matching faces. The operation * compares the features of the input face with faces in the specified * collection. *
** To search for all faces in an input image, you might first call the * IndexFaces operation, and then use the face IDs returned in subsequent * calls to the SearchFaces operation. *
*
* You can also call the DetectFaces operation and use the bounding
* boxes in the response to make face crops, which then you can pass in to the
* SearchFacesByImage operation.
*
* You pass the input image either as base64-encoded image bytes or as a * reference to an image in an Amazon S3 bucket. If you use the AWS CLI to call * Amazon Rekognition operations, passing image bytes is not supported. The * image must be either a PNG or JPEG formatted file. *
*
* The response returns an array of faces that match, ordered by similarity
* score with the highest similarity first. More specifically, it is an array of
* metadata for each face match found. Along with the metadata, the response
* also includes a similarity indicating how similar the face is to
* the input face. In the response, the operation also returns the bounding box
* (and a confidence level that the bounding box contains a face) of the face
* that Amazon Rekognition used for the input image.
*
* If no faces are detected in the input image, SearchFacesByImage
* returns an InvalidParameterException error.
*
* For an example, Searching for a Face Using an Image in the Amazon Rekognition * Developer Guide. *
*
* The QualityFilter input parameter allows you to filter out
* detected faces that don’t meet a required quality bar. The quality bar is
* based on a variety of common use cases. Use QualityFilter to set
* the quality bar for filtering by specifying LOW,
* MEDIUM, or HIGH. If you do not want to filter
* detected faces, specify NONE. The default value is
* NONE.
*
* To use quality filtering, you need a collection associated with version 3 of * the face model or higher. To get the version of the face model associated * with a collection, call DescribeCollection. *
*
* This operation requires permissions to perform the
* rekognition:SearchFacesByImage action.
*
* ID of the collection to search. *
*
* Constraints:
* Length: 1 - 255
* Pattern: [a-zA-Z0-9_.\-]+
*/
private String collectionId;
/**
*
* The input image as base64-encoded bytes or an S3 object. If you use the * AWS CLI to call Amazon Rekognition operations, passing base64-encoded * image bytes is not supported. *
*
* If you are using an AWS SDK to call Amazon Rekognition, you might not
* need to base64-encode image bytes passed using the Bytes
* field. For more information, see Images in the Amazon Rekognition
* developer guide.
*
* Maximum number of faces to return. The operation returns the maximum * number of faces with the highest confidence in the match. *
*
* Constraints:
* Range: 1 - 4096
*/
private Integer maxFaces;
/**
*
* (Optional) Specifies the minimum confidence in the face match to return. * For example, don't return any matches where confidence in matches is less * than 70%. The default value is 80%. *
*
* Constraints:
* Length: 0.0 - 100.0
*/
private Float faceMatchThreshold;
/**
*
* A filter that specifies a quality bar for how much filtering is done to
* identify faces. Filtered faces aren't searched for in the collection. If
* you specify AUTO, Amazon Rekognition chooses the quality
* bar. If you specify LOW, MEDIUM, or
* HIGH, filtering removes all faces that don’t meet the chosen
* quality bar. The quality bar is based on a variety of common use cases.
* Low-quality detections can occur for a number of reasons. Some examples
* are an object that's misidentified as a face, a face that's too blurry,
* or a face with a pose that's too extreme to use. If you specify
* NONE, no filtering is performed. The default value is
* NONE.
*
* To use quality filtering, the collection you are using must be associated * with version 3 of the face model or higher. *
*
* Constraints:
* Allowed Values: NONE, AUTO, LOW, MEDIUM, HIGH
*/
private String qualityFilter;
/**
* Default constructor for SearchFacesByImageRequest object. Callers should
* use the setter or fluent setter (with...) methods to initialize any
* additional object members.
*/
public SearchFacesByImageRequest() {
}
/**
* Constructs a new SearchFacesByImageRequest object. Callers should use the
* setter or fluent setter (with...) methods to initialize any additional
* object members.
*
* @param collectionId
* ID of the collection to search. *
* @param image* The input image as base64-encoded bytes or an S3 object. If * you use the AWS CLI to call Amazon Rekognition operations, * passing base64-encoded image bytes is not supported. *
*
* If you are using an AWS SDK to call Amazon Rekognition, you
* might not need to base64-encode image bytes passed using the
* Bytes field. For more information, see Images in
* the Amazon Rekognition developer guide.
*
* ID of the collection to search. *
*
* Constraints:
* Length: 1 - 255
* Pattern: [a-zA-Z0-9_.\-]+
*
* @return
* ID of the collection to search. *
*/ public String getCollectionId() { return collectionId; } /** ** ID of the collection to search. *
*
* Constraints:
* Length: 1 - 255
* Pattern: [a-zA-Z0-9_.\-]+
*
* @param collectionId
* ID of the collection to search. *
*/ public void setCollectionId(String collectionId) { this.collectionId = collectionId; } /** ** ID of the collection to search. *
** Returns a reference to this object so that method calls can be chained * together. *
* Constraints:
* Length: 1 - 255
* Pattern: [a-zA-Z0-9_.\-]+
*
* @param collectionId
* ID of the collection to search. *
* @return A reference to this updated object so that method calls can be * chained together. */ public SearchFacesByImageRequest withCollectionId(String collectionId) { this.collectionId = collectionId; return this; } /** ** The input image as base64-encoded bytes or an S3 object. If you use the * AWS CLI to call Amazon Rekognition operations, passing base64-encoded * image bytes is not supported. *
*
* If you are using an AWS SDK to call Amazon Rekognition, you might not
* need to base64-encode image bytes passed using the Bytes
* field. For more information, see Images in the Amazon Rekognition
* developer guide.
*
* The input image as base64-encoded bytes or an S3 object. If you * use the AWS CLI to call Amazon Rekognition operations, passing * base64-encoded image bytes is not supported. *
*
* If you are using an AWS SDK to call Amazon Rekognition, you might
* not need to base64-encode image bytes passed using the
* Bytes field. For more information, see Images in the
* Amazon Rekognition developer guide.
*
* The input image as base64-encoded bytes or an S3 object. If you use the * AWS CLI to call Amazon Rekognition operations, passing base64-encoded * image bytes is not supported. *
*
* If you are using an AWS SDK to call Amazon Rekognition, you might not
* need to base64-encode image bytes passed using the Bytes
* field. For more information, see Images in the Amazon Rekognition
* developer guide.
*
* The input image as base64-encoded bytes or an S3 object. If * you use the AWS CLI to call Amazon Rekognition operations, * passing base64-encoded image bytes is not supported. *
*
* If you are using an AWS SDK to call Amazon Rekognition, you
* might not need to base64-encode image bytes passed using the
* Bytes field. For more information, see Images in
* the Amazon Rekognition developer guide.
*
* The input image as base64-encoded bytes or an S3 object. If you use the * AWS CLI to call Amazon Rekognition operations, passing base64-encoded * image bytes is not supported. *
*
* If you are using an AWS SDK to call Amazon Rekognition, you might not
* need to base64-encode image bytes passed using the Bytes
* field. For more information, see Images in the Amazon Rekognition
* developer guide.
*
* Returns a reference to this object so that method calls can be chained * together. * * @param image
* The input image as base64-encoded bytes or an S3 object. If * you use the AWS CLI to call Amazon Rekognition operations, * passing base64-encoded image bytes is not supported. *
*
* If you are using an AWS SDK to call Amazon Rekognition, you
* might not need to base64-encode image bytes passed using the
* Bytes field. For more information, see Images in
* the Amazon Rekognition developer guide.
*
* Maximum number of faces to return. The operation returns the maximum * number of faces with the highest confidence in the match. *
*
* Constraints:
* Range: 1 - 4096
*
* @return
* Maximum number of faces to return. The operation returns the * maximum number of faces with the highest confidence in the match. *
*/ public Integer getMaxFaces() { return maxFaces; } /** ** Maximum number of faces to return. The operation returns the maximum * number of faces with the highest confidence in the match. *
*
* Constraints:
* Range: 1 - 4096
*
* @param maxFaces
* Maximum number of faces to return. The operation returns the * maximum number of faces with the highest confidence in the * match. *
*/ public void setMaxFaces(Integer maxFaces) { this.maxFaces = maxFaces; } /** ** Maximum number of faces to return. The operation returns the maximum * number of faces with the highest confidence in the match. *
** Returns a reference to this object so that method calls can be chained * together. *
* Constraints:
* Range: 1 - 4096
*
* @param maxFaces
* Maximum number of faces to return. The operation returns the * maximum number of faces with the highest confidence in the * match. *
* @return A reference to this updated object so that method calls can be * chained together. */ public SearchFacesByImageRequest withMaxFaces(Integer maxFaces) { this.maxFaces = maxFaces; return this; } /** ** (Optional) Specifies the minimum confidence in the face match to return. * For example, don't return any matches where confidence in matches is less * than 70%. The default value is 80%. *
*
* Constraints:
* Length: 0.0 - 100.0
*
* @return
* (Optional) Specifies the minimum confidence in the face match to * return. For example, don't return any matches where confidence in * matches is less than 70%. The default value is 80%. *
*/ public Float getFaceMatchThreshold() { return faceMatchThreshold; } /** ** (Optional) Specifies the minimum confidence in the face match to return. * For example, don't return any matches where confidence in matches is less * than 70%. The default value is 80%. *
*
* Constraints:
* Length: 0.0 - 100.0
*
* @param faceMatchThreshold
* (Optional) Specifies the minimum confidence in the face match * to return. For example, don't return any matches where * confidence in matches is less than 70%. The default value is * 80%. *
*/ public void setFaceMatchThreshold(Float faceMatchThreshold) { this.faceMatchThreshold = faceMatchThreshold; } /** ** (Optional) Specifies the minimum confidence in the face match to return. * For example, don't return any matches where confidence in matches is less * than 70%. The default value is 80%. *
** Returns a reference to this object so that method calls can be chained * together. *
* Constraints:
* Length: 0.0 - 100.0
*
* @param faceMatchThreshold
* (Optional) Specifies the minimum confidence in the face match * to return. For example, don't return any matches where * confidence in matches is less than 70%. The default value is * 80%. *
* @return A reference to this updated object so that method calls can be * chained together. */ public SearchFacesByImageRequest withFaceMatchThreshold(Float faceMatchThreshold) { this.faceMatchThreshold = faceMatchThreshold; return this; } /** *
* A filter that specifies a quality bar for how much filtering is done to
* identify faces. Filtered faces aren't searched for in the collection. If
* you specify AUTO, Amazon Rekognition chooses the quality
* bar. If you specify LOW, MEDIUM, or
* HIGH, filtering removes all faces that don’t meet the chosen
* quality bar. The quality bar is based on a variety of common use cases.
* Low-quality detections can occur for a number of reasons. Some examples
* are an object that's misidentified as a face, a face that's too blurry,
* or a face with a pose that's too extreme to use. If you specify
* NONE, no filtering is performed. The default value is
* NONE.
*
* To use quality filtering, the collection you are using must be associated * with version 3 of the face model or higher. *
*
* Constraints:
* Allowed Values: NONE, AUTO, LOW, MEDIUM, HIGH
*
* @return
* A filter that specifies a quality bar for how much filtering is
* done to identify faces. Filtered faces aren't searched for in the
* collection. If you specify AUTO, Amazon Rekognition
* chooses the quality bar. If you specify LOW,
* MEDIUM, or HIGH, filtering removes all
* faces that don’t meet the chosen quality bar. The quality bar is
* based on a variety of common use cases. Low-quality detections
* can occur for a number of reasons. Some examples are an object
* that's misidentified as a face, a face that's too blurry, or a
* face with a pose that's too extreme to use. If you specify
* NONE, no filtering is performed. The default value
* is NONE.
*
* To use quality filtering, the collection you are using must be * associated with version 3 of the face model or higher. *
* @see QualityFilter */ public String getQualityFilter() { return qualityFilter; } /** *
* A filter that specifies a quality bar for how much filtering is done to
* identify faces. Filtered faces aren't searched for in the collection. If
* you specify AUTO, Amazon Rekognition chooses the quality
* bar. If you specify LOW, MEDIUM, or
* HIGH, filtering removes all faces that don’t meet the chosen
* quality bar. The quality bar is based on a variety of common use cases.
* Low-quality detections can occur for a number of reasons. Some examples
* are an object that's misidentified as a face, a face that's too blurry,
* or a face with a pose that's too extreme to use. If you specify
* NONE, no filtering is performed. The default value is
* NONE.
*
* To use quality filtering, the collection you are using must be associated * with version 3 of the face model or higher. *
*
* Constraints:
* Allowed Values: NONE, AUTO, LOW, MEDIUM, HIGH
*
* @param qualityFilter
* A filter that specifies a quality bar for how much filtering
* is done to identify faces. Filtered faces aren't searched for
* in the collection. If you specify AUTO, Amazon
* Rekognition chooses the quality bar. If you specify
* LOW, MEDIUM, or HIGH,
* filtering removes all faces that don’t meet the chosen quality
* bar. The quality bar is based on a variety of common use
* cases. Low-quality detections can occur for a number of
* reasons. Some examples are an object that's misidentified as a
* face, a face that's too blurry, or a face with a pose that's
* too extreme to use. If you specify NONE, no
* filtering is performed. The default value is NONE
* .
*
* To use quality filtering, the collection you are using must be * associated with version 3 of the face model or higher. *
* @see QualityFilter */ public void setQualityFilter(String qualityFilter) { this.qualityFilter = qualityFilter; } /** *
* A filter that specifies a quality bar for how much filtering is done to
* identify faces. Filtered faces aren't searched for in the collection. If
* you specify AUTO, Amazon Rekognition chooses the quality
* bar. If you specify LOW, MEDIUM, or
* HIGH, filtering removes all faces that don’t meet the chosen
* quality bar. The quality bar is based on a variety of common use cases.
* Low-quality detections can occur for a number of reasons. Some examples
* are an object that's misidentified as a face, a face that's too blurry,
* or a face with a pose that's too extreme to use. If you specify
* NONE, no filtering is performed. The default value is
* NONE.
*
* To use quality filtering, the collection you are using must be associated * with version 3 of the face model or higher. *
** Returns a reference to this object so that method calls can be chained * together. *
* Constraints:
* Allowed Values: NONE, AUTO, LOW, MEDIUM, HIGH
*
* @param qualityFilter
* A filter that specifies a quality bar for how much filtering
* is done to identify faces. Filtered faces aren't searched for
* in the collection. If you specify AUTO, Amazon
* Rekognition chooses the quality bar. If you specify
* LOW, MEDIUM, or HIGH,
* filtering removes all faces that don’t meet the chosen quality
* bar. The quality bar is based on a variety of common use
* cases. Low-quality detections can occur for a number of
* reasons. Some examples are an object that's misidentified as a
* face, a face that's too blurry, or a face with a pose that's
* too extreme to use. If you specify NONE, no
* filtering is performed. The default value is NONE
* .
*
* To use quality filtering, the collection you are using must be * associated with version 3 of the face model or higher. *
* @return A reference to this updated object so that method calls can be * chained together. * @see QualityFilter */ public SearchFacesByImageRequest withQualityFilter(String qualityFilter) { this.qualityFilter = qualityFilter; return this; } /** *
* A filter that specifies a quality bar for how much filtering is done to
* identify faces. Filtered faces aren't searched for in the collection. If
* you specify AUTO, Amazon Rekognition chooses the quality
* bar. If you specify LOW, MEDIUM, or
* HIGH, filtering removes all faces that don’t meet the chosen
* quality bar. The quality bar is based on a variety of common use cases.
* Low-quality detections can occur for a number of reasons. Some examples
* are an object that's misidentified as a face, a face that's too blurry,
* or a face with a pose that's too extreme to use. If you specify
* NONE, no filtering is performed. The default value is
* NONE.
*
* To use quality filtering, the collection you are using must be associated * with version 3 of the face model or higher. *
*
* Constraints:
* Allowed Values: NONE, AUTO, LOW, MEDIUM, HIGH
*
* @param qualityFilter
* A filter that specifies a quality bar for how much filtering
* is done to identify faces. Filtered faces aren't searched for
* in the collection. If you specify AUTO, Amazon
* Rekognition chooses the quality bar. If you specify
* LOW, MEDIUM, or HIGH,
* filtering removes all faces that don’t meet the chosen quality
* bar. The quality bar is based on a variety of common use
* cases. Low-quality detections can occur for a number of
* reasons. Some examples are an object that's misidentified as a
* face, a face that's too blurry, or a face with a pose that's
* too extreme to use. If you specify NONE, no
* filtering is performed. The default value is NONE
* .
*
* To use quality filtering, the collection you are using must be * associated with version 3 of the face model or higher. *
* @see QualityFilter */ public void setQualityFilter(QualityFilter qualityFilter) { this.qualityFilter = qualityFilter.toString(); } /** *
* A filter that specifies a quality bar for how much filtering is done to
* identify faces. Filtered faces aren't searched for in the collection. If
* you specify AUTO, Amazon Rekognition chooses the quality
* bar. If you specify LOW, MEDIUM, or
* HIGH, filtering removes all faces that don’t meet the chosen
* quality bar. The quality bar is based on a variety of common use cases.
* Low-quality detections can occur for a number of reasons. Some examples
* are an object that's misidentified as a face, a face that's too blurry,
* or a face with a pose that's too extreme to use. If you specify
* NONE, no filtering is performed. The default value is
* NONE.
*
* To use quality filtering, the collection you are using must be associated * with version 3 of the face model or higher. *
** Returns a reference to this object so that method calls can be chained * together. *
* Constraints:
* Allowed Values: NONE, AUTO, LOW, MEDIUM, HIGH
*
* @param qualityFilter
* A filter that specifies a quality bar for how much filtering
* is done to identify faces. Filtered faces aren't searched for
* in the collection. If you specify AUTO, Amazon
* Rekognition chooses the quality bar. If you specify
* LOW, MEDIUM, or HIGH,
* filtering removes all faces that don’t meet the chosen quality
* bar. The quality bar is based on a variety of common use
* cases. Low-quality detections can occur for a number of
* reasons. Some examples are an object that's misidentified as a
* face, a face that's too blurry, or a face with a pose that's
* too extreme to use. If you specify NONE, no
* filtering is performed. The default value is NONE
* .
*
* To use quality filtering, the collection you are using must be * associated with version 3 of the face model or higher. *
* @return A reference to this updated object so that method calls can be * chained together. * @see QualityFilter */ public SearchFacesByImageRequest withQualityFilter(QualityFilter qualityFilter) { this.qualityFilter = qualityFilter.toString(); return this; } /** * Returns a string representation of this object; useful for testing and * debugging. * * @return A string representation of this object. * @see java.lang.Object#toString() */ @Override public String toString() { StringBuilder sb = new StringBuilder(); sb.append("{"); if (getCollectionId() != null) sb.append("CollectionId: " + getCollectionId() + ","); if (getImage() != null) sb.append("Image: " + getImage() + ","); if (getMaxFaces() != null) sb.append("MaxFaces: " + getMaxFaces() + ","); if (getFaceMatchThreshold() != null) sb.append("FaceMatchThreshold: " + getFaceMatchThreshold() + ","); if (getQualityFilter() != null) sb.append("QualityFilter: " + getQualityFilter()); sb.append("}"); return sb.toString(); } @Override public int hashCode() { final int prime = 31; int hashCode = 1; hashCode = prime * hashCode + ((getCollectionId() == null) ? 0 : getCollectionId().hashCode()); hashCode = prime * hashCode + ((getImage() == null) ? 0 : getImage().hashCode()); hashCode = prime * hashCode + ((getMaxFaces() == null) ? 0 : getMaxFaces().hashCode()); hashCode = prime * hashCode + ((getFaceMatchThreshold() == null) ? 0 : getFaceMatchThreshold().hashCode()); hashCode = prime * hashCode + ((getQualityFilter() == null) ? 0 : getQualityFilter().hashCode()); return hashCode; } @Override public boolean equals(Object obj) { if (this == obj) return true; if (obj == null) return false; if (obj instanceof SearchFacesByImageRequest == false) return false; SearchFacesByImageRequest other = (SearchFacesByImageRequest) obj; if (other.getCollectionId() == null ^ this.getCollectionId() == null) return false; if (other.getCollectionId() != null && other.getCollectionId().equals(this.getCollectionId()) == false) return false; if (other.getImage() == null ^ this.getImage() == null) return false; if (other.getImage() != null && other.getImage().equals(this.getImage()) == false) return false; if (other.getMaxFaces() == null ^ this.getMaxFaces() == null) return false; if (other.getMaxFaces() != null && other.getMaxFaces().equals(this.getMaxFaces()) == false) return false; if (other.getFaceMatchThreshold() == null ^ this.getFaceMatchThreshold() == null) return false; if (other.getFaceMatchThreshold() != null && other.getFaceMatchThreshold().equals(this.getFaceMatchThreshold()) == false) return false; if (other.getQualityFilter() == null ^ this.getQualityFilter() == null) return false; if (other.getQualityFilter() != null && other.getQualityFilter().equals(this.getQualityFilter()) == false) return false; return true; } }