Summary: Nested Classes | Constants | Methods | Protected Methods | Inherited Methods | [Expand All]
public final class

# FaceDetector

extends Detector<Face>

java.lang.Object
↳ | com.google.android.gms.vision.Detector<com.google.android.gms.vision.face.Face>
| ↳ | com.google.android.gms.vision.face.FaceDetector

## Class Overview

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.

## Summary

Nested Classes
class | FaceDetector.Builder | Builder for creating face detector instances.

Constants
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 Methods
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 Methods
void | finalize() Secondary mechanism for freeing the underlying native detector resources, in case the developer forgot to call the `release()` method.

[Expand] Inherited Methods
From class com.google.android.gms.vision.Detector
abstract SparseArray<Face> | detect(Frame frame) Analyzes the supplied frame to find target item instances (e.g., the face detector finds faces).
boolean | isOperational() Indicates whether the detector has all of the required dependencies available locally in order to do detection.
void | receiveFrame(Frame frame) Pipeline method (see class level documentation above) for receiving frames for detection.
void | release() Shuts down the detector, releasing any underlying resources.
boolean | setFocus(int id) Sets the ID of the detected item in which to exclusively track in future use of the detector.
void | setProcessor(Processor<Face> processor) Pipeline method (see class level documentation above) which sets the `Detector.Processor` instance.
From class java.lang.Object
Object | clone()
boolean | equals(Object arg0)
void | finalize()
final Class<?> | getClass()
int | hashCode()
final void | notify()
final void | notifyAll()
String | toString()
final void | wait(long arg0, int arg1)
final void | wait(long arg0)
final void | wait()

## 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 (0x00000001)

#### public static final int ALL_CLASSIFICATIONS

Performs "eyes open" and "smiling" classification.

Constant Value: 1 (0x00000001)

#### public static final int ALL_LANDMARKS

Detects all landmarks.

Constant Value: 1 (0x00000001)

#### 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 (0x00000000)

#### public static final int NO_CLASSIFICATIONS

Does not perform classification.

Constant Value: 0 (0x00000000)

#### public static final int NO_LANDMARKS

Does not perform landmark detection.

Constant Value: 0 (0x00000000)

## 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 |