eu.id3.face

Class TrackedFace

java.lang.Object

eu.id3.face.TrackedFace

All Implemented Interfaces:

java.io.Serializable, java.lang.AutoCloseable

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

Represents a tracked face.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
TrackedFace() Creates a new instance of the TrackedFace class.
TrackedFace(long handle) Creates a new instance of the TrackedFace class.

Method Summary

Modifier and Type	Method and Description
TrackedFace	clone() Creates a copy of the TrackedFace object.
void	close() Releases all resources used by this TrackedFace.
static TrackedFace	create(Rectangle bounds, int detectionScore, int id, PointList landmarks) Creates a detected face.
protected void	finalize() Finalizer for this class.
static TrackedFace	fromBuffer(byte[] data) Imports the face object from a buffer.
static TrackedFace	fromFile(java.lang.String path) Imports the face object from a file.
DetectedFace	getAsDetectedFace() Gets the tracked face as a detected face.
Rectangle	getBounds() Gets the bounds of the detected face.
int	getDetectionScore() Gets the confidence score of the detected face.
int	getDistanceToCamera(Image depthImage) Gets the distance between the detected face and the camera when using a depth map in pixels.
Rectangle	getExpandedBounds(float aspectRatio, float margin) Gets the bounding box around the detected face with specified aspect ratio and specified margin.
FaceTemplate	getFaceTemplate() Gets the computed template the tracked face.
long	getHandle() Gets the native handle.
int	getId() Gets the ID of the detected face.
int	getInterocularDistance() Gets the distance between the eyes (IOD) of the detected face in pixels.
PointList	getLandmarks() Gets the landmarks (eyes, nose and mouth corners) of the detected face.
Rectangle	getPortraitBounds(float eyeImageWidthRatio, float eyeImageHeightRatio, float imageRatio) Gets the bounding box of the detected face for ICAO portrait cropping.
Rectangle	getPredictedBounds() Gets the predicted bounds of the tracked face.
TrackingStatus	getTrackingStatus() Gets the status of the tracked face.
void	rescale(float scale) Rescales the detected face object bounding box and landmarks.
void	rotate(int angle, Point center) Rotates the face object by a given angle in degrees from a given center.
void	setBounds(Rectangle bounds) Sets the bounds of the detected face.
void	setId(int id) Sets the ID of the detected face.
void	setLandmarks(PointList landmarks) Sets the landmarks (eyes, nose and mouth corners) of the detected face.
byte[]	toBuffer() Exports the face object to a buffer.
void	toFile(java.lang.String path) Saves the face object to a file.
void	translate(int tx, int ty) Translates the face object.

Methods inherited from class java.lang.Object

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

Constructor Detail

TrackedFace

public TrackedFace()
            throws FaceException

Creates a new instance of the TrackedFace class.

Throws:

FaceException - An error has occurred during Face Library execution.

TrackedFace

public TrackedFace(long handle)
            throws FaceException

Creates a new instance of the TrackedFace class.

Parameters:

handle - Handle to the TrackedFace.

Throws:

FaceException - An error has occurred during Face Library execution.

Method Detail

close

public void close()

Releases all resources used by this TrackedFace.

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.

clone

public TrackedFace clone()
                  throws FaceException

Creates a copy of the TrackedFace object.

Overrides:

clone in class java.lang.Object

Returns:

The newly created TrackedFace object.

Throws:

FaceException - An error has occurred during Face Library execution.

getBounds

public Rectangle getBounds()
                    throws FaceException

Gets the bounds of the detected face.

Returns:

Bounds of the detected face.

Throws:

FaceException - An error has occurred during Face Library execution.

setBounds

public void setBounds(Rectangle bounds)
               throws FaceException

Sets the bounds of the detected face.

Parameters:

bounds - Bounds of the detected face.

Throws:

FaceException - An error has occurred during Face Library execution.

getDetectionScore

public int getDetectionScore()
                      throws FaceException

Gets the confidence score of the detected face.

Returns:

Confidence score of the detected face.

Throws:

FaceException - An error has occurred during Face Library execution.

getFaceTemplate

public FaceTemplate getFaceTemplate()
                             throws FaceException

Gets the computed template the tracked face. It aims at tracking an identity over time and is consolidated.

Returns:

Computed template the tracked face. It aims at tracking an identity over time and is consolidated.

Throws:

FaceException - An error has occurred during Face Library execution.

getId

public int getId()
          throws FaceException

Gets the ID of the detected face.

Returns:

ID of the detected face.

Throws:

FaceException - An error has occurred during Face Library execution.

setId

public void setId(int id)
           throws FaceException

Sets the ID of the detected face.

Parameters:

id - ID of the detected face.

Throws:

FaceException - An error has occurred during Face Library execution.

getLandmarks

public PointList getLandmarks()
                       throws FaceException

Gets the landmarks (eyes, nose and mouth corners) of the detected face.

Returns:

Landmarks (eyes, nose and mouth corners) of the detected face.

Throws:

FaceException - An error has occurred during Face Library execution.

setLandmarks

public void setLandmarks(PointList landmarks)
                  throws FaceException

Sets the landmarks (eyes, nose and mouth corners) of the detected face.

Parameters:

landmarks - Landmarks (eyes, nose and mouth corners) of the detected face.

Throws:

FaceException - An error has occurred during Face Library execution.

getPredictedBounds

public Rectangle getPredictedBounds()
                             throws FaceException

Gets the predicted bounds of the tracked face. Those bounds are computed using a Kalman filter which has the effect of making them smooth and robust to false non-detections.

Returns:

Predicted bounds of the tracked face. Those bounds are computed using a Kalman filter which has the effect of making them smooth and robust to false non-detections.

Throws:

FaceException - An error has occurred during Face Library execution.

getTrackingStatus

public TrackingStatus getTrackingStatus()
                                 throws FaceException

Gets the status of the tracked face. See FaceTrackingStatus for more details.

Returns:

Status of the tracked face. See FaceTrackingStatus for more details.

Throws:

FaceException - An error has occurred during Face Library execution.

create

public static TrackedFace create(Rectangle bounds,
                                 int detectionScore,
                                 int id,
                                 PointList landmarks)
                          throws FaceException

Creates a detected face.

Parameters:

bounds - Bounds of the detected face.

detectionScore - Confidence score of the detected face.

id - ID of the detected face.

landmarks - Landmarks (eyes, nose and mouth corners) of the detected face.

Returns:

The newly created tracked face.

Throws:

FaceException - An error has occurred during Face Library execution.

fromBuffer

public static TrackedFace fromBuffer(byte[] data)
                              throws FaceException

Imports the face object from a buffer.

Parameters:

data - Buffer to import the face object from.

Returns:

The newly created tracked face.

Throws:

FaceException - An error has occurred during Face Library execution.

fromFile

public static TrackedFace fromFile(java.lang.String path)
                            throws FaceException

Imports the face object from a file.

Parameters:

path - Path to the file to import the face object from.

Returns:

The newly created tracked face.

Throws:

FaceException - An error has occurred during Face Library execution.

getAsDetectedFace

public DetectedFace getAsDetectedFace()
                               throws FaceException

Gets the tracked face as a detected face.

Returns:

The tracked face as a detected face.

Throws:

FaceException - An error has occurred during Face Library execution.

getDistanceToCamera

public int getDistanceToCamera(Image depthImage)
                        throws FaceException

Gets the distance between the detected face and the camera when using a depth map in pixels.

Parameters:

depthImage - Depth image to process.

Returns:

The estimated distance to camera in pixels.

Throws:

FaceException - An error has occurred during Face Library execution.

getExpandedBounds

public Rectangle getExpandedBounds(float aspectRatio,
                                   float margin)
                            throws FaceException

Gets the bounding box around the detected face with specified aspect ratio and specified margin.

Parameters:

aspectRatio - Aspect ratio of the bounding box. Default recommended value is 1.33 (4/3).

margin - Relative margin around the detected face. Recommended value is 0.5.

Returns:

The portrait bounds.

Throws:

FaceException - An error has occurred during Face Library execution.

getInterocularDistance

public int getInterocularDistance()
                           throws FaceException

Gets the distance between the eyes (IOD) of the detected face in pixels.

Returns:

The computed interocular distance (IOD) in pixels.

Throws:

FaceException - An error has occurred during Face Library execution.

getPortraitBounds

public Rectangle getPortraitBounds(float eyeImageWidthRatio,
                                   float eyeImageHeightRatio,
                                   float imageRatio)
                            throws FaceException

Gets the bounding box of the detected face for ICAO portrait cropping. This method shall be used to ensure compliance with the ICAO standard.

Parameters:

eyeImageWidthRatio - Ratio between eye distance and image width. Must be in the range ]0;1[. Default recommended value is 0.25.

eyeImageHeightRatio - Ratio between eye distance to top and image height. Must be in the range ]0;1[. Default recommended value is 0.45.

imageRatio - Ratio between image height and image width. Default recommended value is 1.33 (4/3).

Returns:

The portrait bounds of the detected face.

Throws:

FaceException - An error has occurred during Face Library execution.

rescale

public void rescale(float scale)
             throws FaceException

Rescales the detected face object bounding box and landmarks. This function can be useful if the image was downscaled to speed up detection, then you need to upscale the detected face to fit the source image size.

Parameters:

scale - The multiplicative rescaling factor to apply to the face object.

Throws:

FaceException - An error has occurred during Face Library execution.

rotate

public void rotate(int angle,
                   Point center)
            throws FaceException

Rotates the face object by a given angle in degrees from a given center.

Parameters:

angle - Angle of the rotation to apply to the face object.

center - Center of the rotation to apply to the face object.

Throws:

FaceException - An error has occurred during Face Library execution.

toBuffer

public byte[] toBuffer()
                throws FaceException

Exports the face object to a buffer.

Returns:

The buffer to which the face object is exported.

Throws:

FaceException - An error has occurred during Face Library execution.

toFile

public void toFile(java.lang.String path)
            throws FaceException

Saves the face object to a file.

Parameters:

path - Path to the file to export the face object to.

Throws:

FaceException - An error has occurred during Face Library execution.

translate

public void translate(int tx,
                      int ty)
               throws FaceException

Translates the face object.

Parameters:

tx - Translation to apply to the face object alongside the x-axis.

ty - Translation to apply to the face object alongside the y-axis.

Throws:

FaceException - An error has occurred during Face Library execution.