/** * Divide candidate faces into groups based on face similarity. * The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result. * MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts. * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try Face - Verify when you only have 2 candidate faces. * * @param faceIds Candidate face IDs. The maximum is 1000 faces. * @return a built {@link GroupFacesAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395238">MS Cognitive Docs (Face - Group)</a> */ public GroupFacesAction groupFaces(List<String> faceIds) { Validation.validateArray(faceIds, 1, 1000, new ParameterValidationException("faceIds", "length must be between 1 & 1000")); return new GroupFacesAction(cognitiveContext, faceIds); }
@NotNull public List<IdentificationSet> identifyPersonsInGroup(@NotNull String personGroupId, @NotNull List<Face> faces) { Validation.validateArray(faces, 1, 10, new ParameterValidationException("faces", "Max of 10 faces allowed")); List<Identification> collection = faceTaskBuilder.identifyFaces(Utils.extractFaceIds(faces), personGroupId, 1).withResult(); return buildIdentificationList(personGroupId, faces, collection); }
/** * Identify unknown faces from an person group. * <p> * For each face in the faceIds array, Face Identify will compute similarity for the face among all faces within a person group (given by personGroupId), and returns candidate person(s) for that face ranked by similarity confidence. The person group should be trained to make it ready for identify. See more in Person Group - Train Person Group. * <p> * Remarks: * <p> * The algorithm allows more than one face to be isIdentified, but the no more than 10 faces. * Each person in the person group could have more than one face, but no more than 64 faces. * Identification works well for frontal faces and near-frontal faces. * Number of candidates returned is restricted by maxNumOfCandidatesReturned. If no person is isIdentified, the candidate returned will be an empty array. * Try Face - Find Similar when you need to identify similar faces from a face list instead of a person group. * * @param faceIds Query faces' IDs. The length of faceIds is between [1, 10]. * @param personGroupId Target person group's ID * @param maxNumOfCandidatesReturned The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). * @return a built {@link IdentifyFacesAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239">MS Cognitive Docs (Face - Identify)</a> */ public IdentifyFacesAction identifyFaces(List<String> faceIds, String personGroupId, int maxNumOfCandidatesReturned) { Validation.validateArray(faceIds, 1, 10, new ParameterValidationException("faceIds", "length must be between 1 & 10")); Validation.validateInt(maxNumOfCandidatesReturned, 5, new ParameterValidationException("maxNumOfCandidatesReturned", "maxNumOfCandidatesReturned must be between 1 & 5")); return new IdentifyFacesAction(cognitiveContext, faceIds, personGroupId, maxNumOfCandidatesReturned); }
public void createGroupWithFromVisionImages(@NotNull String faceListId, @NotNull List<VisionImage> visionImages) { Validation.validateArray(visionImages, 1, 1000, new ParameterValidationException("visionImages", "Face list is invalid. min 1, max 1000")); boolean exists = !Utils.throwsException(() -> faceListBuilder.getFaceList(faceListId).withResult(), FaceListNotFoundException.class); if (!exists) { faceListBuilder.createFaceList(faceListId, faceListId, "").withNoResult(); } visionImages.forEach(it -> { if (it.isLocalFile()) faceListBuilder.addFaceToFaceList(faceListId, "", "", Utils.fileToFileInputStream((File) it.getImage())).withNoResult(); else faceListBuilder.addFaceToFaceList(faceListId, "", "", (String) it.getImage()).withNoResult(); }); }
/** * 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); } }
/** * Create a new group from a set of people * * @param personGroupId the person group id * @param people the people in the group * @return The created personGroupId */ public String createGroupWithPeople(@NotNull String personGroupId, @NotNull People people) { Validation.validateArray(people.simplePersons(), 1, 1000, new ParameterValidationException("people", "People list is invalid. min 1, max 1000")); boolean exists = !Utils.throwsException(() -> personGroupBuilder.getGroup(personGroupId).withResult(), PersonGroupNotFoundException.class); if (!exists) { personGroupBuilder.createGroup(personGroupId, personGroupId, "").withNoResult(); } people.simplePersons().stream().forEach(simplePerson -> { Person person = personBuilder.createPerson(personGroupId, simplePerson.personName, simplePerson.personUserData).withResult(); List<ImageHolder> personImages = simplePerson.personImages; for (ImageHolder imageHolder : personImages) { if (imageHolder.firstImage().isLocalFile()) personBuilder.addFaceToPerson(personGroupId, person.personId, "", (File) imageHolder.firstImage().getImage()).withNoResult(); else personBuilder.addFaceToPerson(personGroupId, person.personId, "", (String) imageHolder.firstImage().getImage()).withNoResult(); } }); personGroupBuilder.trainGroup(personGroupId).withNoResult(); return personGroupId; }