FaceDetector

public final class FaceDetector extends Detector<Face>

Detector for finding Faces in a supplied image.

A face detector is created via an associated builder class, specifying the relevant detection options. For example, the code below creates a face detector which is optimized for tracking a single, relatively large face (e.g., the user of a device).

FaceDetector detector = new FaceDetector.Builder(context)
   .setProminentFaceOnly(true)
   .build();
 
A detector may be used to run detection synchronously given a Frame, like this:
SparseArray<Face> faces = detector.detect(frame);
 
Alternatively, a detector may be used within a pipeline structure, in conjunction with sources (e.g., CameraSource) and processors (e.g., LargestFaceFocusingProcessor), enabling you to construct fairly advanced detection pipelines with minimal coding.

For example, the code below creates and starts a pipeline that continuously receives preview frames from a camera source for the front facing camera, runs detection on the frames, manages tracking of the most prominent face, and delivers continuous update notifications over time to a developer-defined "FaceTracker" instance.

detector.setProcessor(
   new LargestFaceFocusingProcessor(
     detector,
     new FaceTracker()));

 CameraSource cameraSource = new CameraSource.Builder(context, detector)
   .setFacing(CameraSource.CAMERA_FACING_FRONT)
   .setRequestedPreviewSize(320, 240)
   .build()
   .start();
 
Where "FaceTracker" is a Tracker callback for receiving notifications on the detected "Face" instance over time.

The face detector can be run with fairly low resolution images (e.g., 320x240). Running face detection on low resolution images is significantly faster than high resolution images. Note that the camera source's default preview resolution is much higher than is needed by this detector; you can often achieve higher speed/efficiency by reducing the preview size as illustrated above. However, you should also keep in mind that at lower resolutions, the face detector may miss some smaller faces due to having a less detailed image.

Adding the vision functionality dependency to your project's AndroidManifest.xml will indicate to the installer that it should download the dependency on application install.

Nested Class Summary

class FaceDetector.Builder Builder for creating face detector instances. 

Constant Summary

int ACCURATE_MODE Indicates a preference for accuracy in extended settings that may make an accuracy vs.
int ALL_CLASSIFICATIONS Performs "eyes open" and "smiling" classification.
int ALL_LANDMARKS Detects all landmarks.
int FAST_MODE Indicates a preference for speed in extended settings that may make an accuracy vs.
int NO_CLASSIFICATIONS Does not perform classification.
int NO_LANDMARKS Does not perform landmark detection.

Public Method Summary

SparseArray<Face>
detect(Frame frame)
Analyzes the supplied frame to find faces, returning faces with associated tracking ID mappings.
boolean
isOperational()
Indicates whether the detector has all of the required dependencies available locally in order to do detection.
void
release()
Releases the resources associated with this detector.
boolean
setFocus(int id)
Sets the ID of the face to exclusively track in future use of the detector.

Protected Method Summary

void
finalize()
Secondary mechanism for freeing the underlying native detector resources, in case the developer forgot to call the release() method.

Inherited Method Summary

Constants

public static final int ACCURATE_MODE

Indicates a preference for accuracy in extended settings that may make an accuracy vs. speed trade-off. This will tend to detect more faces and may be more precise in determining values such as position, at the cost of speed.

Constant Value: 1

public static final int ALL_CLASSIFICATIONS

Performs "eyes open" and "smiling" classification.

Constant Value: 1

public static final int ALL_LANDMARKS

Detects all landmarks.

Constant Value: 1

public static final int FAST_MODE

Indicates a preference for speed in extended settings that may make an accuracy vs. speed trade-off. This will tend to detect fewer faces and may be less precise in determining values such as position, but will run faster.

Constant Value: 0

public static final int NO_CLASSIFICATIONS

Does not perform classification.

Constant Value: 0

public static final int NO_LANDMARKS

Does not perform landmark detection.

Constant Value: 0

Public Methods

public SparseArray<Face> detect (Frame frame)

Analyzes the supplied frame to find faces, returning faces with associated tracking ID mappings.

Returns
  • mapping of int to Face, where the int domain represents the ID of the associated item. If tracking is enabled, as the same face is detected in consecutive frames the detector will return the same ID for that face.
Throws
IllegalArgumentException if the frame is null.
RuntimeException if the detector has been released.

public boolean isOperational ()

Indicates whether the detector has all of the required dependencies available locally in order to do detection.

When an app is first installed, it may be necessary to download required files. If this returns false, those files are not yet available. Usually this download is taken care of at application install time, but this is not guaranteed. In some cases the download may have been delayed.

If your code has added a processor, an indication of the detector operational state is also indicated with the detectorIsOperational() method. You can check this in your app as it processes detection results, and can convey this state to the user if appropriate.

Returns
  • true if the detector is operational, false if the dependency download is in progress

public void release ()

Releases the resources associated with this detector.

public boolean setFocus (int id)

Sets the ID of the face to exclusively track in future use of the detector. This can be used to avoid unnecessary work in detecting all faces in future frames, when it's only necessary to receive results for a specific face. After setting this ID, the detector will only return results for the associated face. When that face is no longer present in a frame, the detector will revert back to detecting all faces.

Parameters
id tracking ID to become the focus for future detections. This is a mapping ID as returned from detect(Frame) or received from getDetectedItems().
Returns
  • whether the focus succeeded. Invalid ids will return false.
Throws
RuntimeException if the detector has been released.

Protected Methods

protected void finalize ()

Secondary mechanism for freeing the underlying native detector resources, in case the developer forgot to call the release() method.

Throws
Throwable