/** * 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); }
/** * 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 image Image stream. 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 InputStream image) { 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, image); }
/** * 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); }
/** * 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); }