/** * List all people in a person group, and retrieve person information (including person ID, name, user data and registered faces of the person). * * @param personGroupId - The target person's belonging person group's ID. * @return a built {@link ListPersonsInPersonGroupAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241">MS Cognitive Docs (Person - List Persons in a Person Group)</a> */ @NotNull public ListPersonsInPersonGroupAction listPersonsInPersonGroup(@NotNull String personGroupId) { Validation.validate(personGroupId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("personGroupId", "Person group ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); return new ListPersonsInPersonGroupAction(cognitiveContext, personGroupId); } }
/** * 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); } }
/** * 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); }
/** * 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); }
/** * This operation generates a thumbnail image with the user-specified width and height. * <p>By default, the service analyzes the image, identifies the region of interest (ROI), and generates smart cropping coordinates based on the ROI. * <p>Smart cropping helps when you specify an aspect ratio that differs from that of the input image * * @param width Width of the thumbnail. It must be between 1 and 1024. Recommended minimum of 50. * @param height Height of the thumbnail. It must be between 1 and 1024. Recommended minimum of 50. * @param smartCrop Boolean flag for enabling smart cropping. * @param imageUrl URL of input image. * @return a built {@link GetThumbnailAction} * @see <a href="https://dev.projectoxford.ai/docs/services/56f91f2d778daf23d8ec6739/operations/56f91f2e778daf14a499e1fb">MS Cognitive Docs (Computer Vision - Get Thumbnail)</a> */ @NotNull public GetThumbnailAction getThumbnail(int width, int height, boolean smartCrop, @NotNull String imageUrl) { Validation.validateInt(width, 1024, new ParameterValidationException("width", "It must be between 1 and 1024. Recommended minimum of 50.")); Validation.validateInt(height, 1024, new ParameterValidationException("height", "It must be between 1 and 1024. Recommended minimum of 50.")); return new GetThumbnailAction(cognitiveContext, width, height, smartCrop, imageUrl); }
@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); }
/** * Delete an existing person group. Persisted face images of all people in the person group will also be deleted. * * @param personGroupId - ID of the target person group. * @return a built {@link DeletePersonGroupAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245">MS Cognitive Docs (Person Group - DELETE)</a> */ @NotNull public DeletePersonGroupAction deleteGroup(@NotNull String personGroupId) { Validation.validate(personGroupId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("personGroupId", "Person group ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); return new DeletePersonGroupAction(cognitiveContext, personGroupId); }
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(); }); }
/** * Delete an existing face list according to face list ID. Persisted face images in the face list will also be deleted. * * @param faceListId - Valid character is letter in lower case or digit or '-' or '_', maximum length is 64. * @return a built {@link DeletePersonGroupAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f">MS Cognitive Docs (Face List - Delete a Face List)</a> */ @NotNull public DeleteFaceListAction deleteFaceList(@NotNull String faceListId) { Validation.validate(faceListId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("faceListId", "Person group ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); return new DeleteFaceListAction(cognitiveContext, faceListId); }
/** * 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; }
/** * Delete an existing person from a person group. Persisted face images of the person will also be deleted. * * @param personGroupId - The target person's belonging person group's ID. * @param personId - The target person ID. * @return a built {@link GetPersonAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d">MS Cognitive Docs (Person - Delete a Person)</a> */ @NotNull public DeletePersonAction deletePerson(@NotNull String personGroupId, @NotNull String personId) { Validation.validate(personGroupId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("personGroupId", "Person group ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); return new DeletePersonAction(cognitiveContext, personGroupId, personId); }
/** * Update a person face's userData field. * * @param personGroupId - The target person's belonging person group's ID. * @param personId - The target person ID. * @param persistedFaceId - The target face ID. * @param userData - Attach user data to person's face. The size limit is 1KB. * @return a built {@link UpdateFaceToPersonAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395243">MS Cognitive Docs (Person - Update a Person Face)</a> */ @NotNull public UpdateFaceToPersonAction updatePersonFace(@NotNull String personGroupId, @NotNull String personId, @NotNull String persistedFaceId, @Nullable String userData) { Validation.validate(personGroupId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("personGroupId", "Person group ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); Validation.validate(userData, 1, new ParameterValidationException("userData", "User-specified data for any purpose. The maximum length is 1KB.")); return new UpdateFaceToPersonAction(cognitiveContext, personGroupId, personId, persistedFaceId, userData); }
/** * Update a person's name or userData field. * * @param personGroupId - The target person's belonging person group's ID. * @param personId - The target person ID. * @param name - Target person's display name. The maximum length is 128. * @param userData - Optional fields for user-provided data attached to a person. Size limit is 16KB. * @return a built {@link UpdatePersonAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395242">MS Cognitive Docs (Person - Update a Person)</a> */ @NotNull public UpdatePersonAction updatePerson(@NotNull String personGroupId, @NotNull String personId, String name, String userData) { Validation.validate(personGroupId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("personGroupId", "Person group ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); Validation.validate(name, "^.{1,128}$", new ParameterValidationException("name", "The maximum length is 128")); Validation.validate(userData, 16, new ParameterValidationException("userData", "The size limit is 16KB")); return new UpdatePersonAction(cognitiveContext, personGroupId, personId, name, userData); }
/** * Retrieve a person's information, including registered faces, name and userData. * * @param personGroupId - The target person's belonging person group's ID. * @param personId - The target person ID. * @return a built {@link GetPersonAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523f">MS Cognitive Docs (Person - Get a Person)</a> */ @NotNull public GetPersonAction getPerson(@NotNull String personGroupId, @NotNull String personId) { Validation.validate(personGroupId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("personGroupId", "Person group ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); return new GetPersonAction(cognitiveContext, personGroupId, personId); }
/** * Delete an existing face from a face list (given by a face ID and a face list ID). Persisted image related to the face will also be deleted. * * @param faceListId Valid character is letter in lower case or digit or '-' or '_', maximum length is 64. * @param persistedFaceId Valid character is letter in lower case or digit or '-' or '_', maximum length is 64. * @return a built {@link DeleteFaceListFaceAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251">MS Cognitive Docs (Face List - Delete a Face from a Face List)</a> */ @NotNull public DeleteFaceListFaceAction deleteFaceListFace(@NotNull String faceListId, @NotNull String persistedFaceId) { Validation.validate(faceListId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("faceListId", "FaceListId is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); return new DeleteFaceListFaceAction(cognitiveContext, faceListId, persistedFaceId); }
/** * Retrieve the information of a person group, including its name and userData. * <p> This API returns person group information only, use {@link cognitivej.vision.face.person.PersonBuilder#listPersonsInPersonGroup(String)} in a Person Group instead to retrieve person information under the person group. * * @param personGroupId - ID of the target person group. * @return a built {@link GetPersonGroupAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395246">MS Cognitive Docs (Person Group - GET)</a> */ @NotNull public GetPersonGroupAction getGroup(@NotNull String personGroupId) { Validation.validate(personGroupId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("personGroupId", "Person group ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); return new GetPersonGroupAction(cognitiveContext, personGroupId); }
/** * Update an existing person group's display name and userData. * * @param personGroupId - User-provided person group ID as a string. The valid characters include numbers, english letters in lower case, '-' and '_'. The maximum length of the personGroupId is 64 * @param name - Person group display name. The maximum length is 128. * @param userData - User-provided data attached to the person group. The size limit is 16KB (UTF-16 encoded). * @return a built {@link UpdatePersonGroupAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524a">MS Cognitive Docs (Person Group - UPDATE)</a> */ @NotNull public UpdatePersonGroupAction updateGroup(@NotNull String personGroupId, @NotNull String name, @Nullable String userData) { Validation.validate(personGroupId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("personGroupId", "Person group ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); Validation.validate(name, "^.{1,128}$", new ParameterValidationException("name", "The maximum length is 128")); Validation.validate(userData, 16, new ParameterValidationException("userData", "The size limit is 16KB")); return new UpdatePersonGroupAction(cognitiveContext, personGroupId, name, userData); }
/** * Retrieve a face list's information, including face list ID, name, userData and faces in the face list. Face list simply represents a list of faces, and could be treated as a searchable data source in Face - Find Similar. * * @param faceListId - Valid character is letter in lower case or digit or '-' or '_', maximum length is 64. * @return a built {@link GetFaceListAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c">MS Cognitive Docs (Face List - Get a Face List)</a> */ @NotNull public GetFaceListAction getFaceList(String faceListId) { Validation.validate(faceListId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("faceListId", "FaceList ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); return new GetFaceListAction(cognitiveContext, faceListId); }
/** * Create a new person in a specified person group for identify. A newly created person have no registered face, you can call Person - Add a Person Face API to add faces to the person. * <p> * The number of persons has a subscription limit. * * @param personGroupId - The target person's belonging person group's ID. * @param name - Target person's display name. The maximum length is 128. * @param userData - Optional fields for user-provided data attached to a person. Size limit is 16KB. * @return a built {@link CreatePersonAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c">MS Cognitive Docs (Person - CREATE)</a> */ @NotNull public CreatePersonAction createPerson(@NotNull String personGroupId, @NotNull String name, @Nullable String userData) { Validation.validate(personGroupId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("personGroupId", "Person group ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); Validation.validate(name, "^.{1,128}$", new ParameterValidationException("name", "The maximum length is 128")); Validation.validate(userData, 16, new ParameterValidationException("userData", "The size limit is 16KB")); return new CreatePersonAction(cognitiveContext, personGroupId, name, userData); }
/** * Retrieve information about a face (specified by face ID, person ID and its belonging person group ID). * * @param personGroupId - The target person's belonging person group's ID. * @param personId - The target person ID. * @param persistedFaceId - The target face ID. * @return a built {@link GetPersonFaceAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395240">MS Cognitive Docs (Person - Get a Person Face)</a> */ @NotNull public GetPersonFaceAction getPersonFace(@NotNull String personGroupId, @NotNull String personId, String persistedFaceId) { Validation.validate(personGroupId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("personGroupId", "Person group ID is invalid. Valid format should be a string composed by numbers, english letters in lower case, '-', '_', and no longer than 64 characters.")); return new GetPersonFaceAction(cognitiveContext, personGroupId, personId, persistedFaceId); }