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

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.