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

    All Methods Static Methods Instance Methods Concrete Methods
    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.

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