eu.id3.face

## Class FaceAnalyser

- java.lang.Object
- - eu.id3.face.FaceAnalyser

- All Implemented Interfaces:
    java.io.Serializable, java.lang.AutoCloseable

      public class FaceAnalyser
      extends java.lang.Object
      implements java.lang.AutoCloseable, java.io.Serializable

  Provides methods for analysing the characteristics of portrait image.
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `FaceAnalyser()` Creates a new instance of the FaceAnalyser class.
    `FaceAnalyser(long handle)` Creates a new instance of the FaceAnalyser class.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Image` | `applyAlphaMask(Image image, Image mask)` Applies an alpha mask to suppress the background and returns a 32-bit BGRA image.
    `Image` | `applyMask(Image image, Image mask, int red, int green, int blue)` Applies a mask to replace the background with the specified color and returns a 24-bit BGR image.
    `boolean` | `checkColorizedImage(Image image)` Verifies if an image is colorized or grayscale.
    `void` | `close()` Releases all resources used by this FaceAnalyser.
    `int` | `computeAge(Image image, DetectedFace detectedFace)` Computes the age of a detected face.
    `FaceAttributes` | `computeAttributes(Image image, DetectedFace detectedFace)` Computes the attributes of a detected face.
    `BackgroundUniformity` | `computeBackgroundUniformity(Image image, DetectedFace detectedFace)` Computes the background uniformity behind a detected face.
    `FaceExpression` | `computeExpression(Image image, DetectedFace detectedFace)` Computes the expression of a detected face.
    `EyeGaze` | `computeEyeGaze(Image image, DetectedFace detectedFace, PointList landmarks)` Computes the eye gaze of a detected face.
    `int[]` | `computeEyeOpenness(Image image, DetectedFace detectedFace, PointList landmarks)` Computes the eye openness of a detected face.
    `int[]` | `computeEyeRedness(Image image, DetectedFace detectedFace, PointList landmarks)` Computes the eye redness of a detected face.
    `GeometricAttributes` | `computeGeometricAttributes(Image image, DetectedFace detectedFace, PointList landmarks)` Computes the geometric attributes of a detected face.
    `GlassesAttributes` | `computeGlassesAttributes(Image image, DetectedFace detectedFace, PointList landmarks)` Computes the glasses attributes of a detected face.
    `PointList` | `computeLandmarks(Image image, DetectedFace detectedFace)` Computes 68 landmarks of a detected face.
    `int` | `computeNoise(Image image)` Measures the image noise.
    `PhotographicAttributes` | `computePhotographicAttributes(Image image, DetectedFace detectedFace, PointList landmarks)` Computes the photographic attributes of a detected face.
    `FacePose` | `computePose(DetectedFace detectedFace)` Computes the pose of a detected face.
    `FacePose` | `computePoseWithLandmarks(DetectedFace detectedFace, PointList landmarks)` Computes the pose of a detected face using the specified 68-point landmarks.
    `int` | `detectFaceMask(Image image, DetectedFace detectedFace)` Detects the presence of a face mask on a detected face.
    `FaceOcclusionScores` | `detectOcclusions(Image image, DetectedFace detectedFace)` Detects occlusions on the subject's face.
    `protected void` | `finalize()` Finalizer for this class.
    `int` | `getExpressionSensibility()` Gets the sensibility of the expression classifier.
    `long` | `getHandle()` Gets the native handle.
    `int` | `getOverExposureSensibility()` Gets the sensibility of the over-exposure classifier, from 0 to 255.
    `int` | `getThreadCount()` Gets the number of threads to be used for face analysis.
    `int` | `getUnderExposureSensibility()` Gets the sensibility of the under-exposure classifier, from 0 to 255.
    `Image` | `removeCompressionArtifacts(Image image)` Upscale and enhance the image of a face.
    `Image` | `segmentBackground(Image image)` Computes face segmentation mask for background removal.
    `Image` | `segmentFace(Image image)` Computes a segmentation map of a face.
    `void` | `setExpressionSensibility(int expressionSensibility)` Sets the sensibility of the expression classifier.
    `void` | `setOverExposureSensibility(int overExposureSensibility)` Sets the sensibility of the over-exposure classifier, from 0 to 255.
    `void` | `setThreadCount(int threadCount)` Sets the number of threads to be used for face analysis.
    `void` | `setUnderExposureSensibility(int underExposureSensibility)` Sets the sensibility of the under-exposure classifier, from 0 to 255.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### FaceAnalyser

          public FaceAnalyser()
                       throws FaceException

      Creates a new instance of the FaceAnalyser class.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### FaceAnalyser

          public FaceAnalyser(long handle)
                       throws FaceException

      Creates a new instance of the FaceAnalyser class.
      Parameters:
        `handle` - Handle to the FaceAnalyser.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

  - ### Method Detail

    - #### close

          public void close()

      Releases all resources used by this FaceAnalyser.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`

    - #### finalize

          protected void finalize()

      Finalizer for this class. Finalizers are deprecated since Java 9+. This method is not guaranteed to be called. To release all memory held by this class please be sure to call the close() method.
      Overrides:
        `finalize` in class `java.lang.Object`

    - #### getHandle

          public long getHandle()

      Gets the native handle.
      Returns:
        The native handle.

    - #### getExpressionSensibility

          public int getExpressionSensibility()
                                       throws FaceException

      Gets the sensibility of the expression classifier. The higher the value, the more sensitive the algorithm will be, meaning that it will be less likely to estimate neutral expression out of the detected face. Hint: Default value is 60.
      Returns:
        Sensibility of the expression classifier.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### setExpressionSensibility

          public void setExpressionSensibility(int expressionSensibility)
                                        throws FaceException

      Sets the sensibility of the expression classifier. The higher the value, the more sensitive the algorithm will be, meaning that it will be less likely to estimate neutral expression out of the detected face. Hint: Default value is 60.
      Parameters:
        `expressionSensibility` - Sensibility of the expression classifier.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### getOverExposureSensibility

          public int getOverExposureSensibility()
                                         throws FaceException

      Gets the sensibility of the over-exposure classifier, from 0 to 255. The lower the value, the more sensitive the algorithm will be, meaning that it will be more likely to estimate over-exposed face images. Hint: Default value is 188.
      Returns:
        Sensibility of the over-exposure classifier, from 0 to 255.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### setOverExposureSensibility

          public void setOverExposureSensibility(int overExposureSensibility)
                                          throws FaceException

      Sets the sensibility of the over-exposure classifier, from 0 to 255. The lower the value, the more sensitive the algorithm will be, meaning that it will be more likely to estimate over-exposed face images. Hint: Default value is 188.
      Parameters:
        `overExposureSensibility` - Sensibility of the over-exposure classifier, from 0 to 255.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### getThreadCount

          public int getThreadCount()
                             throws FaceException

      Gets the number of threads to be used for face analysis. Hint: Default value is 1. Allocating more than one thread can increase the speed of the process.
      Returns:
        Number of threads to be used for face analysis.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### setThreadCount

          public void setThreadCount(int threadCount)
                              throws FaceException

      Sets the number of threads to be used for face analysis. Hint: Default value is 1. Allocating more than one thread can increase the speed of the process.
      Parameters:
        `threadCount` - Number of threads to be used for face analysis.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### getUnderExposureSensibility

          public int getUnderExposureSensibility()
                                          throws FaceException

      Gets the sensibility of the under-exposure classifier, from 0 to 255. The higher the value, the more sensitive the algorithm will be, meaning that it will be more likely to estimate under-exposed face images. Hint: Default value is 66.
      Returns:
        Sensibility of the under-exposure classifier, from 0 to 255.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### setUnderExposureSensibility

          public void setUnderExposureSensibility(int underExposureSensibility)
                                           throws FaceException

      Sets the sensibility of the under-exposure classifier, from 0 to 255. The higher the value, the more sensitive the algorithm will be, meaning that it will be more likely to estimate under-exposed face images. Hint: Default value is 66.
      Parameters:
        `underExposureSensibility` - Sensibility of the under-exposure classifier, from 0 to 255.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### applyAlphaMask

          public Image applyAlphaMask(Image image,
                                      Image mask)
                               throws FaceException

      Applies an alpha mask to suppress the background and returns a 32-bit BGRA image.
      Parameters:
        `image` - Source image to process.
        `mask` - Mask of segmented face.
      Returns:
        The output image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### applyMask

          public Image applyMask(Image image,
                                 Image mask,
                                 int red,
                                 int green,
                                 int blue)
                          throws FaceException

      Applies a mask to replace the background with the specified color and returns a 24-bit BGR image.
      Parameters:
        `image` - Source image to process.
        `mask` - Mask to be applied. Must be a 8-bit greyscale image of same size as the input image.
        `red` - Green channel of the background color. Must be a value from 0 to 255.
        `green` - Red channel of the background color. Must be a value from 0 to 255.
        `blue` - Blue channel of the background color. Must be a value from 0 to 255.
      Returns:
        The output image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### checkColorizedImage

          public boolean checkColorizedImage(Image image)
                                      throws FaceException

      Verifies if an image is colorized or grayscale.
      Parameters:
        `image` - Source image to process.
      Returns:
        The boolean decision: True if colorized, False if grayscale.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computeAge

          public int computeAge(Image image,
                                DetectedFace detectedFace)
                         throws FaceException

      Computes the age of a detected face. Important: Loading the ``FaceAgeEstimator`` model is required to use this function.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
      Returns:
        The estimated age of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computeAttributes

          public FaceAttributes computeAttributes(Image image,
                                                  DetectedFace detectedFace)
                                           throws FaceException

      Computes the attributes of a detected face. Important: Loading the model ``FaceAttributesClassifier`` is required to use this function.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
      Returns:
        The estimated attributes of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computeBackgroundUniformity

          public BackgroundUniformity computeBackgroundUniformity(Image image,
                                                                  DetectedFace detectedFace)
                                                           throws FaceException

      Computes the background uniformity behind a detected face. This function must be used for a portrait image with only one face in it. A high uniformity score means that the background is uniform. Important: Loading the model ``FaceBackgroundUniformity`` is required to use this function.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
      Returns:
        The estimated background uniformity. Both color and texture scores are in the range [0:100]. The minimum recommended thresholds are respectively 80 for color and 80 for texture.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computeExpression

          public FaceExpression computeExpression(Image image,
                                                  DetectedFace detectedFace)
                                           throws FaceException

      Computes the expression of a detected face. Important: Loading the ``FaceExpressionClassifier`` model is required to use this function.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
      Returns:
        The estimated expression of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computeEyeGaze

          public EyeGaze computeEyeGaze(Image image,
                                        DetectedFace detectedFace,
                                        PointList landmarks)
                                 throws FaceException

      Computes the eye gaze of a detected face. Important: Loading the ``EyeGazeEstimator`` model is required to use this function.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
        `landmarks` - Estimated landmarks of the detected face. Must be computed with the face analyser.
      Returns:
        The estimated gaze of left and right eyes of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computeEyeOpenness

          public int[] computeEyeOpenness(Image image,
                                          DetectedFace detectedFace,
                                          PointList landmarks)
                                   throws FaceException

      Computes the eye openness of a detected face. The minimum recommanded value for is 90. Important: Loading the ``EyeOpennessDetector`` model is required to use this function.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
        `landmarks` - Estimated landmarks of the detected face. Must be computed with the face analyser.
      Returns:
        The estimated openness scores of left and right eyes of the detected face in this order.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computeEyeRedness

          public int[] computeEyeRedness(Image image,
                                         DetectedFace detectedFace,
                                         PointList landmarks)
                                  throws FaceException

      Computes the eye redness of a detected face. The maximum recommanded value for an ICAO-compliant portrait is 10. Important: Loading the ``EyeRednessDetector`` model is required to use this function.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
        `landmarks` - Estimated landmarks of the detected face. Must be computed with the face analyser.
      Returns:
        The estimated redness scores of left and right eyes of the detected face in this order.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computeGeometricAttributes

          public GeometricAttributes computeGeometricAttributes(Image image,
                                                                DetectedFace detectedFace,
                                                                PointList landmarks)
                                                         throws FaceException

      Computes the geometric attributes of a detected face. This function must be used for a portrait image with only one face in it.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
        `landmarks` - Estimated landmarks of the detected face. Must be computed with the face analyser.
      Returns:
        The estimated geometric attributes of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computeGlassesAttributes

          public GlassesAttributes computeGlassesAttributes(Image image,
                                                            DetectedFace detectedFace,
                                                            PointList landmarks)
                                                     throws FaceException

      Computes the glasses attributes of a detected face. This function must be used for a portrait image with only one face in it.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
        `landmarks` - Estimated landmarks of the detected face. Must be computed with the face analyser.
      Returns:
        The estimated glasses attributes of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computeLandmarks

          public PointList computeLandmarks(Image image,
                                            DetectedFace detectedFace)
                                     throws FaceException

      Computes 68 landmarks of a detected face. Important: Loading the ``FaceLandmarksEstimator`` model is required to use this function.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
      Returns:
        The estimated landmarks of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computeNoise

          public int computeNoise(Image image)
                           throws FaceException

      Measures the image noise.
      Parameters:
        `image` - Source image to process.
      Returns:
        The estimated noise score. 0 means no noise, 100 means no signal.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computePhotographicAttributes

          public PhotographicAttributes computePhotographicAttributes(Image image,
                                                                      DetectedFace detectedFace,
                                                                      PointList landmarks)
                                                               throws FaceException

      Computes the photographic attributes of a detected face. This function must be used for a portrait image with only one face in it.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
        `landmarks` - Estimated landmarks of the detected face. Must be computed with the face analyser.
      Returns:
        The estimated photographic attributes of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computePose

          public FacePose computePose(DetectedFace detectedFace)
                               throws FaceException

      Computes the pose of a detected face. Important: Loading the ``FacePoseEstimator`` model is required to use this function.
      Parameters:
        `detectedFace` - Detected face to process.
      Returns:
        The estimated pose of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### computePoseWithLandmarks

          public FacePose computePoseWithLandmarks(DetectedFace detectedFace,
                                                   PointList landmarks)
                                            throws FaceException

      Computes the pose of a detected face using the specified 68-point landmarks. Loading the model ``FacePoseEstimator1A`` is required to use this function.
      Parameters:
        `detectedFace` - Detected face to process.
        `landmarks` - Estimated landmarks of the detected face. Must be computed with the face analyser.
      Returns:
        The estimated pose of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### detectFaceMask

          public int detectFaceMask(Image image,
                                    DetectedFace detectedFace)
                             throws FaceException

      Detects the presence of a face mask on a detected face. A high score means that there is a high chance that the person is wearing a mask. The minimum recommended threshold is 15. Important: Loading the ``FaceMaskClassifier``, model is required to use this function.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
      Returns:
        The face mask presence score of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### detectOcclusions

          public FaceOcclusionScores detectOcclusions(Image image,
                                                      DetectedFace detectedFace)
                                               throws FaceException

      Detects occlusions on the subject's face. Important: This function requires the ``FaceOcclusionDetector`` model to be loaded.
      Parameters:
        `image` - Source image to process.
        `detectedFace` - Detected face to process.
      Returns:
        The occlusion scores of the detected face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### removeCompressionArtifacts

          public Image removeCompressionArtifacts(Image image)
                                           throws FaceException

      Upscale and enhance the image of a face. Important: This methods requires the ``CompressionArtifactRemover`` model to be loaded.
      Parameters:
        `image` - Source image to process.
      Returns:
        The enhanced face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### segmentBackground

          public Image segmentBackground(Image image)
                                  throws FaceException

      Computes face segmentation mask for background removal. Important: This methods requires the ``FaceBackgroundSegmenter`` model to be loaded.
      Parameters:
        `image` - Source image to process.
      Returns:
        The mask of segmented face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### segmentFace

          public Image segmentFace(Image image)
                            throws FaceException

      Computes a segmentation map of a face. Important: This methods requires the ``FaceSegmenter`` model to be loaded.
      Parameters:
        `image` - Source image to process.
      Returns:
        The map of segmented face.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

Copyright © id3 Technologies. All rights reserved. eu.id3.face