/** * Find similar - looking faces for a query face from a list of candidate faces (given by a face list or a face ID array) and return similar face IDs ranked by similarity. * The candidate face list has a limitation of 1000 faces. * * @param faceId Query face. The faceId comes from the {@link FaceTaskBuilder#detectFace(boolean, boolean, EnumSet, InputStream)} . * @param faceIds A candidate face list. Face list simply represents a list of faces, reference Face List - Create a Face List for more detail. faceListId and faceIds should not be provided at the same time. * @param faceListId A face ID array of candidate faces. Length of faceIds should between [1, 1000]. Parameter faceListId and faceIds should not be provided at the same time. * @param maxNumOfCandidates Only top maxNumOfCandidatesReturned most similar faces will be returned. maxNumOfCandidatesReturned ranges between [1, 20]. * @return a built {@link FindSimilarFacesAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237">MS Cognitive Docs (Face - Find Similar)</a> */ public FindSimilarFacesAction findSimilarFace(String faceId, List<String> faceIds, String faceListId, int maxNumOfCandidates) { Validation.validateArray(faceIds, 0, 1000, new ParameterValidationException("faceIds", "length must be between 1 & 1000")); Validation.validateInt(maxNumOfCandidates, 20, new ParameterValidationException("maxNumOfCandidates", "length must be between 1 & 20")); Validation.validateExclusive(faceIds, faceListId, new ParameterValidationException("faceIds", "must only supply either faceListId OR a faceId (pass null or empty collection)")); return new FindSimilarFacesAction(cognitiveContext, faceId, faceIds, faceListId, maxNumOfCandidates); } }