# Class Face

java.lang.Object
com.codename1.ai.vision.Face

public final class Face extends Object

Portable face observation.

Euler angles are expressed in degrees. Bounds and landmark points use the normalized, top-left-origin coordinate space defined by `VisionRect` and `VisionPoint`.

Not every backend fills in every field. `getSmilingProbability()` and `getTrackingId()` return a negative value when the backend does not expose them -- Apple Vision reports neither -- and a landmark the backend could not locate is absent from the map. Test for those rather than assuming a complete observation.

    FaceDetector detector = new FaceDetector();
    detector.process(VisionImage.encoded(jpeg)).ready(faces -> {
        for (Face face : faces) {
            Rectangle box = face.getBounds().toBounds(photoLabel);
            if (face.getSmilingProbability() > 0.7f) {
                Log.p("smiling face at " + box);
            }
        }
    }).except(error -> Log.e(error));

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Face(VisionRect bounds, Map<String, VisionPoint> landmarks, float yaw, float pitch, float roll, float smilingProbability, int trackingId)`
  Creates a detected face without backend metadata.
  `Face(VisionRect bounds, Map<String, VisionPoint> landmarks, float yaw, float pitch, float roll, float smilingProbability, int trackingId, VisionMetadata metadata)`
  Creates a detected face with backend diagnostics.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `VisionRect`
  `getBounds()`
  `VisionPoint`
  `getLandmark(String name)`
  Looks up one named landmark.
  `Map<String, VisionPoint>`
  `getLandmarks()`
  `VisionMetadata`
  `getMetadata()`
  `float`
  `getPitch()`
  `float`
  `getRoll()`
  `float`
  `getSmilingProbability()`
  `int`
  `getTrackingId()`
  `float`
  `getYaw()`

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### Face

    public Face(VisionRect bounds, Map<String, VisionPoint> landmarks, float yaw, float pitch, float roll, float smilingProbability, int trackingId)
    Creates a detected face without backend metadata.
    Parameters:
      `bounds` - face bounds in the oriented image coordinate space
      `landmarks` - named feature points, defensively copied
      `yaw` - horizontal Euler angle in degrees
      `pitch` - vertical Euler angle in degrees
      `roll` - in-plane Euler angle in degrees
      `smilingProbability` - smile confidence, or a negative value when unavailable
      `trackingId` - stable streaming id, or a negative value when unavailable

  - ### Face

    public Face(VisionRect bounds, Map<String, VisionPoint> landmarks, float yaw, float pitch, float roll, float smilingProbability, int trackingId, VisionMetadata metadata)
    Creates a detected face with backend diagnostics.
    Parameters:
      `bounds` - face bounds in the oriented image coordinate space
      `landmarks` - named feature points, defensively copied
      `yaw` - horizontal Euler angle in degrees
      `pitch` - vertical Euler angle in degrees
      `roll` - in-plane Euler angle in degrees
      `smilingProbability` - smile confidence, or a negative value when unavailable
      `trackingId` - stable streaming id, or a negative value when unavailable
      `metadata` - backend details, or `null`

- ## Method Details

  - ### getBounds

    public VisionRect getBounds()
    Returns:
      normalized top-left-origin face bounds

  - ### getLandmark

    public VisionPoint getLandmark(String name)

    Looks up one named landmark.

    A landmark the backend could not locate is absent rather than present at a meaningless position, so a `null` return means "not found in this face", not "unsupported".

    Parameters:
      `name` - one of the `FaceLandmarks` constants
    Returns:
      the normalized landmark position, or `null` when the backend did not report it

  - ### getLandmarks

    public Map<String, VisionPoint> getLandmarks()
    Returns:
      immutable named landmark map; possibly empty

  - ### getYaw

    public float getYaw()
    Returns:
      left/right head rotation in degrees, or 0 if unavailable

  - ### getPitch

    public float getPitch()
    Returns:
      up/down head rotation in degrees, or 0 if unavailable

  - ### getRoll

    public float getRoll()
    Returns:
      in-plane head rotation in degrees, or 0 if unavailable

  - ### getSmilingProbability

    public float getSmilingProbability()
    Returns:
      smile probability in 0..1, or -1 when unavailable

  - ### getTrackingId

    public int getTrackingId()
    Returns:
      stream tracking identifier, or -1 when unavailable

  - ### getMetadata

    public VisionMetadata getMetadata()
    Returns:
      backend metadata, or `null` when manually constructed