How to use

Utils

in

cognitivej.core

public VisionImage<T> firstImage() {
  return Utils.elementAt(images, 0);
}

@NotNull
public List<Face> findFaces(@NotNull File imageFile) {
  return findFaces(Utils.fileToFileInputStream(imageFile));
}

  public static void validateExclusive(List collection, String str, ParameterValidationException toThrow) {
    if ((Utils.isEmpty(collection) && Utils.isBlank(str))
        || (Utils.isNotEmpty(collection) && Utils.isNotBlank(str)))
      throw toThrow;
  }
}

/**
 * Saves the image to the disk and launches the default viewer for images.
 *
 * @param file - the file where the image will be saved
 * @return this
 */
@NotNull
public ImageOverlayBuilder toDiskAndLaunchViewer(@NotNull File file) {
  toDisk(file);
  try {
    Desktop.getDesktop().open(file);
    Utils.waitFor(3, TimeUnit.SECONDS);
  } catch (IOException e) {
    throw new CognitiveException("Could not open image", e);
  }
  return this;
}

public static void validateArray(@NotNull List elements, int min, int max, @NotNull ParameterValidationException toThrow) {
  if (min == 0 && Utils.isEmpty(elements))
    return;
  if (Utils.isEmpty(elements) || elements.size() < min || elements.size() > max)
    throw toThrow;
}

@NotNull
private IdentificationSet identifyPersonInGroup(@NotNull String personGroupId, @NotNull Face singleFace) {
  Identification identification = Utils.elementAt(faceTaskBuilder.identifyFaces(Collections.singletonList(singleFace.faceId), personGroupId, 1).withResult(), 0);
  if (identification != null && Utils.isNotEmpty(identification.candidates))
    return new IdentificationSet(singleFace, identification, personBuilder.getPerson(personGroupId, identification.candidates.get(0).personId).withResult());
  return new IdentificationSet(singleFace, identification);
}

public static boolean isEmpty(Collection collection) {
  return !isNotEmpty(collection);
}

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();
  });
}

/**
 * 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);
}

public Person createPersonInGroup(final String personGroupId, String personName, boolean createGroupIfMissing) {
  if (createGroupIfMissing) {
    boolean exists = !Utils.throwsException(() -> personGroupBuilder.getGroup(personGroupId), PersonGroupNotFoundException.class);
    if (!exists) {
      personGroupBuilder.createGroup(personGroupId, personGroupId, "");
    }
  }
  return personBuilder.createPerson(personGroupId, personName, "").withResult();
}

public static boolean isNotBlank(String str) {
  return !isBlank(str);
}

@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);
}

private void buildContext(Object image) {
  workingContext.setPath("vision/v1.0/ocr")
      .httpMethod(HttpMethod.POST);
  if (Utils.isNotBlank(language))
    workingContext().addQueryParameter("language", language);
  workingContext().addQueryParameter("detectOrientation", String.valueOf(detectOrientation));
  if (image instanceof String)
    workingContext.addPayload("url", String.valueOf(image));
  if (image instanceof InputStream)
    workingContext.addPayload(IMAGE_INPUT_STREAM_KEY, image);
}

public static void main(String[] args) throws IOException {
  FaceScenarios faceScenarios = new FaceScenarios(getProperty("azure.cognitive.subscriptionKey"),
      getProperty("azure.cognitive.emotion.subscriptionKey"));
  ImageOverlayBuilder imageOverlayBuilder = ImageOverlayBuilder.builder(IMAGE);
  List<ImageHolder> candidates = candidates();
  People people = ScenarioHelper.
      createPeopleFromHoldingImages(candidates, ImageNamingStrategy.DEFAULT);
  String groupId = faceScenarios.
      createGroupWithPeople(randomAlphabetic(6).toLowerCase(), people);
  Utils.waitFor(10, TimeUnit.SECONDS); //let the training be completed
  java.util.List<IdentificationSet> identificationSets = faceScenarios.identifyPersonsInGroup(groupId, IMAGE);
  imageOverlayBuilder.identify(identificationSets);
  buildGrid(imageOverlayBuilder, people);
  imageOverlayBuilder.launchViewer().toClipboard();
  faceScenarios.deleteGroup(groupId);
}

/**
 * @param image - the Image (as an inputStream
 * @see FaceScenarios#findSingleFace(String)
 * @return Face
 */
@NotNull
public Face findSingleFace(@NotNull InputStream image) {
  List<Face> faces = faceTaskBuilder.detectFace(true, true, FaceAttributes.ALL, image).withResult();
  if (Utils.isEmpty(faces) || faces.size() > 1)
    throw new SingleFaceNotFoundException(Utils.isEmpty(faces) ? 0 : faces.size(), "a single face was not present");
  return faces.get(0);
}

@NotNull
private List<IdentificationSet> buildIdentificationList(@NotNull String personGroupId, @NotNull List<Face> faces, @NotNull List<Identification> identificationList) {
  List<IdentificationSet> identificationSetList = new ArrayList<>();
  for (Identification identification : identificationList) {
    Optional<Face> first = faces.stream().filter(x -> x.faceId.equals(identification.faceId)).findFirst();
    identificationSetList.add(new IdentificationSet(first.get(), identification, Utils.isNotEmpty(identification.candidates) ? personBuilder.getPerson(personGroupId, identification.candidates.get(0).personId).withResult() : null));
    System.out.println(identification);
  }
  return identificationSetList;
}

/**
 * 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);
}

/**
 * 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;
}

/**
 * Find a faces within a local image
 *
 * @param image the image URL
 * @return the found faces
 */
@NotNull
public Emotion findEmotionSingleFace(@NotNull String image) {
  List<Emotion> emotions = emotionBuilder.emotionRecognition(image).withResult();
  if (Utils.isEmpty(emotions) || emotions.size() > 1)
    throw new SingleFaceNotFoundException(Utils.isEmpty(emotions) ? 0 : emotions.size(), "a single face was not present");
  return emotions.get(0);
}

private void buildContext(Object image) {
  workingContext.setPath("vision/v1.0/analyze")
      .httpMethod(HttpMethod.POST);
  if (Utils.isNotEmpty(visualFeatures))
    workingContext().addQueryParameter("visualFeatures", StringUtils.join(visualFeatures, ','));
  if (Utils.isNotEmpty(visualFeatures))
    workingContext().addQueryParameter("details", StringUtils.join(domainSpecificDetails, ','));
  if (image instanceof String)
    workingContext.addPayload("url", String.valueOf(image));
  if (image instanceof InputStream)
    workingContext.addPayload(IMAGE_INPUT_STREAM_KEY, image);
}