/** * 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); }
/** * 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); }
/** * 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); } }
/** * 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); }
/** * 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 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); }
/** * 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 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 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); }
/** * 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); }
/** * Update face changes to a face list. Face list simply represents a list of faces, and could be treat as a searchable data source in Face - Find Similar. * * @param faceListId 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 FaceList display name. The maximum length is 128. * @param userData User-provided data attached to the faceList. The size limit is 16KB (UTF-16 encoded). * @return a built {@link UpdateFaceListAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524e">MS Cognitive Docs (Face List - Update a Face List)</a> */ @NotNull public UpdateFaceListAction updateFaceList(@NotNull String faceListId, @NotNull String name, @Nullable String userData) { 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.")); Validation.validate(name, "^.{1,128}$", new ParameterValidationException("name", "The maximum length is 128")); Validation.validate(Utils.blankIfNull(userData), 16, new ParameterValidationException("userData", "The size limit is 16KB")); return new UpdateFaceListAction(cognitiveContext, faceListId, 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); }
/** * Retrieve the training status of a person group (completed or ongoing). * <p>Training can be triggered by the Person Group - Train Person Group API. The training will process for a while on the server side. * * @param personGroupId - ID of the target person group. * @return a built {@link GetPersonGroupTrainingStatusAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395247">MS Cognitive Docs (Person Group - TRAINING STATUS)</a> */ @NotNull GetPersonGroupTrainingStatusAction personGroupTrainingStatus(@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 GetPersonGroupTrainingStatusAction(cognitiveContext, personGroupId); }
/** * Create a new person group with specified person group ID, name and user-provided data. * <p> * A person group is one of the most important parameters for the Face - Identify API. The Identify searches person faces in a specified person group. * * @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 CreatePersonGroupAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244">MS Cognitive Docs (Person Group - CREATE)</a> */ @NotNull public CreatePersonGroupAction createGroup(@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 CreatePersonGroupAction(cognitiveContext, personGroupId, name, userData); }
/** * Delete a face from a person. Relative image for the persisted face will also be deleted. * * @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 DeletePersonFaceAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e">MS Cognitive Docs (Person - Delete a Person Face)</a> */ @NotNull public DeletePersonFaceAction deletePersonFace(@NotNull String personGroupId, 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 DeletePersonFaceAction(cognitiveContext, personGroupId, personId, persistedFaceId); }
/** * Queue a person group training task, the training task may not be started immediately. * <p> * Any updates to person group will not take effect in Face - Identify until person group is successfully trained. You can query the training status by calling Person Group - Get Person Group Training Status API. * * @param personGroupId - ID of the target person group. * @return a built {@link TrainPersonGroupAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249">MS Cognitive Docs (Person Group - TRAIN)</a> */ @NotNull public TrainPersonGroupAction trainGroup(@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 TrainPersonGroupAction(cognitiveContext, personGroupId); }
/** * Create an empty face list with user-specified face list ID, name and an optional user-data. 64 face lists are allowed to exist in one subscription. * <p> * Face list is a group of faces, and these faces will not expire. Face list is used as a parameter of source faces in Face - Find Similar. Face List is useful when to find similar faces in a fixed face set very often, e.g. to find a similar face in a face list of celebrities, friends, or family members. * <p> * A face list can have a maximum of 1000 faces * * @param faceListId Valid character is letter in lower case or digit or '-' or '_', maximum length is 64. * @param name Name of the created face list, maximum length is 128. * @param userData User-specified data for any purpose. The maximum length is 16KB. * @return a built {@link CreateFaceListAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b">MS Cognitive Docs (Face List - Create a Face List)</a> */ @NotNull public CreateFaceListAction createFaceList(@NotNull String faceListId, @Nullable String name, @Nullable String userData) { Validation.validate(faceListId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("faceListId", "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.")); Validation.validate(name, "^.{1,128}$", new ParameterValidationException("name", "The maximum length is 128")); Validation.validate(Utils.blankIfNull(userData), 16, new ParameterValidationException("userData", "The size limit is 16KB")); return new CreateFaceListAction(cognitiveContext, faceListId, name, userData); }
/** * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns an persistedFaceId representing the added face, and persistedFaceId will not expire. * <p> * The persistedFaceId will be used in output JSON of Face - Find Similar, or in Face List - Delete a Face from a Face List to remove face from a face list. * JPEG, PNG, GIF(the first frame), and BMP are supported. The image file size should be no larger than 4MB. * The detectable face size is between 36x36 to 4096x4096 pixels. The faces out of this range will not be detected. * Rectangle specified by targetFace should contain exactly one face. Zero or multiple faces will be regarded as an error. Out of detectable face size, large head-pose, or very large occlusions will also result in fail to add a person face. * The given rectangle specifies both face location and face size at the same time. There is no guarantee of corrent result if you are using rectangle which are not returned from Face - Detect. * Face list is a group of faces, and these faces will not expire. Face list is used as a parameter of source faces in Face - Find Similar. Face List is useful when to find similar faces in a fixed face set very often, e.g. to find a similar face in a face list of celebrities, friends, or family members. * <p> * A face list can have a maximum of 1000 faces. * * @param faceListId Valid character is letter in lower case or digit or '-' or '_', maximum length is 64. * @param userData User-specified data for any purpose. The maximum length is 1KB. * @param targetFace A face rectangle to specify the target face to be added into the face list, in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". No targetFace means to detect the only face in the entire image. * @param imageUrl Image url. Image file size should between 1KB to 4MB. Only one face is allowed per image. * @return a built {@link AddFaceToFaceListAction} * @see <a href="https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250">MS Cognitive Docs (Face List - Add a Face to a Face List * )</a> */ @NotNull public AddFaceToFaceListAction addFaceToFaceList(@NotNull String faceListId, @Nullable String userData, @Nullable String targetFace, @NotNull String imageUrl) { Validation.validate(faceListId, "^[a-z0-9_-]{1,64}$", new ParameterValidationException("faceListId", "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.")); Validation.validate(Utils.blankIfNull(userData), 1, new ParameterValidationException("userData", "The size limit is 1KB")); return new AddFaceToFaceListAction(cognitiveContext, faceListId, userData, targetFace, imageUrl); }