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 | CONTOUR_LANDMARKS | Detects contours for 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. |
int | SELFIE_MODE | Indicates a preference for predominant faces that typically appear in self-photography style and may not detect smaller and further away faces. |
Public Method Summary
SparseArray<Face> |
detect(Frame frame)
Analyzes the supplied frame to find faces, returning faces with associated
tracking ID mappings.
|
boolean | |
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 |
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.
public static final int ALL_CLASSIFICATIONS
Performs "eyes open" and "smiling" classification.
public static final int ALL_LANDMARKS
Detects all landmarks.
public static final int CONTOUR_LANDMARKS
Detects contours for landmarks.
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.
public static final int NO_CLASSIFICATIONS
Does not perform classification.
public static final int NO_LANDMARKS
Does not perform landmark detection.
public static final int SELFIE_MODE
Indicates a preference for predominant faces that typically appear in self-photography style and may not detect smaller and further away faces.
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 ()
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
Detector.Detections.getDetectedItems() . |
---|
Returns
- whether the focus succeeded. Invalid ids will return false.
Throws
RuntimeException | if the detector has been released. |
---|