Java tutorial
/* * Copyright (C) 2013 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.hardware.camera2.params; import android.graphics.Point; import android.graphics.Rect; import android.hardware.camera2.CameraCharacteristics; import android.hardware.camera2.CameraMetadata; import android.hardware.camera2.CaptureResult; /** * Describes a face detected in an image. */ public final class Face { /** * The ID is {@code -1} when the optional set of fields is unsupported. * * @see Face#Face(Rect, int) * @see #getId() */ public static final int ID_UNSUPPORTED = -1; /** * The minimum possible value for the confidence level. * * @see #getScore() */ public static final int SCORE_MIN = 1; /** * The maximum possible value for the confidence level. * * @see #getScore() */ public static final int SCORE_MAX = 100; private final Rect mBounds; private final int mScore; private final int mId; private final Point mLeftEye; private final Point mRightEye; private final Point mMouth; /** * Create a new face with all fields set. * * <p>The id, leftEyePosition, rightEyePosition, and mouthPosition are considered optional. * They are only required when the {@link CaptureResult} reports that the value of key * {@link CaptureResult#STATISTICS_FACE_DETECT_MODE} is * {@link CameraMetadata#STATISTICS_FACE_DETECT_MODE_FULL}. * If the id is {@value #ID_UNSUPPORTED} then the leftEyePosition, rightEyePosition, and * mouthPositions are guaranteed to be {@code null}. Otherwise, each of leftEyePosition, * rightEyePosition, and mouthPosition may be independently null or not-null.</p> * * @param bounds Bounds of the face. * @param score Confidence level between {@value #SCORE_MIN}-{@value #SCORE_MAX}. * @param id A unique ID per face visible to the tracker. * @param leftEyePosition The position of the left eye. * @param rightEyePosition The position of the right eye. * @param mouthPosition The position of the mouth. * * @throws IllegalArgumentException * if bounds is {@code null}, * or if the confidence is not in the range of * {@value #SCORE_MIN}-{@value #SCORE_MAX}, * or if id is {@value #ID_UNSUPPORTED} and * leftEyePosition/rightEyePosition/mouthPosition aren't all null, * or else if id is negative. * * @hide */ public Face(Rect bounds, int score, int id, Point leftEyePosition, Point rightEyePosition, Point mouthPosition) { checkNotNull("bounds", bounds); if (score < SCORE_MIN || score > SCORE_MAX) { throw new IllegalArgumentException("Confidence out of range"); } else if (id < 0 && id != ID_UNSUPPORTED) { throw new IllegalArgumentException("Id out of range"); } if (id == ID_UNSUPPORTED) { checkNull("leftEyePosition", leftEyePosition); checkNull("rightEyePosition", rightEyePosition); checkNull("mouthPosition", mouthPosition); } mBounds = bounds; mScore = score; mId = id; mLeftEye = leftEyePosition; mRightEye = rightEyePosition; mMouth = mouthPosition; } /** * Create a new face without the optional fields. * * <p>The id, leftEyePosition, rightEyePosition, and mouthPosition are considered optional. * If the id is {@value #ID_UNSUPPORTED} then the leftEyePosition, rightEyePosition, and * mouthPositions are guaranteed to be {@code null}. Otherwise, each of leftEyePosition, * rightEyePosition, and mouthPosition may be independently null or not-null. When devices * report the value of key {@link CaptureResult#STATISTICS_FACE_DETECT_MODE} as * {@link CameraMetadata#STATISTICS_FACE_DETECT_MODE_SIMPLE} in {@link CaptureResult}, * the face id of each face is expected to be {@value #ID_UNSUPPORTED}, the leftEyePosition, * rightEyePosition, and mouthPositions are expected to be {@code null} for each face.</p> * * @param bounds Bounds of the face. * @param score Confidence level between {@value #SCORE_MIN}-{@value #SCORE_MAX}. * * @throws IllegalArgumentException * if bounds is {@code null}, * or if the confidence is not in the range of * {@value #SCORE_MIN}-{@value #SCORE_MAX}. * * @hide */ public Face(Rect bounds, int score) { this(bounds, score, ID_UNSUPPORTED, /*leftEyePosition*/null, /*rightEyePosition*/null, /*mouthPosition*/null); } /** * Bounds of the face. * * <p>A rectangle relative to the sensor's * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE}, with (0,0) * representing the top-left corner of the active array rectangle.</p> * * <p>There is no constraints on the the Rectangle value other than it * is not-{@code null}.</p> */ public Rect getBounds() { return mBounds; } /** * The confidence level for the detection of the face. * * <p>The range is {@value #SCORE_MIN} to {@value #SCORE_MAX}. * {@value #SCORE_MAX} is the highest confidence.</p> * * <p>Depending on the device, even very low-confidence faces may be * listed, so applications should filter out faces with low confidence, * depending on the use case. For a typical point-and-shoot camera * application that wishes to display rectangles around detected faces, * filtering out faces with confidence less than half of {@value #SCORE_MAX} * is recommended.</p> * * @see #SCORE_MAX * @see #SCORE_MIN */ public int getScore() { return mScore; } /** * An unique id per face while the face is visible to the tracker. * * <p> * If the face leaves the field-of-view and comes back, it will get a new * id.</p> * * <p>This is an optional field, may not be supported on all devices. * If the id is {@value #ID_UNSUPPORTED} then the leftEyePosition, rightEyePosition, and * mouthPositions are guaranteed to be {@code null}. Otherwise, each of leftEyePosition, * rightEyePosition, and mouthPosition may be independently null or not-null. When devices * report the value of key {@link CaptureResult#STATISTICS_FACE_DETECT_MODE} as * {@link CameraMetadata#STATISTICS_FACE_DETECT_MODE_SIMPLE} in {@link CaptureResult}, * the face id of each face is expected to be {@value #ID_UNSUPPORTED}.</p> * * <p>This value will either be {@value #ID_UNSUPPORTED} or * otherwise greater than {@code 0}.</p> * * @see #ID_UNSUPPORTED */ public int getId() { return mId; } /** * The coordinates of the center of the left eye. * * <p>The coordinates are in * the same space as the ones for {@link #getBounds}. This is an * optional field, may not be supported on all devices. If not * supported, the value will always be set to null. * This value will always be null only if {@link #getId()} returns * {@value #ID_UNSUPPORTED}.</p> * * @return The left eye position, or {@code null} if unknown. */ public Point getLeftEyePosition() { return mLeftEye; } /** * The coordinates of the center of the right eye. * * <p>The coordinates are * in the same space as the ones for {@link #getBounds}.This is an * optional field, may not be supported on all devices. If not * supported, the value will always be set to null. * This value will always be null only if {@link #getId()} returns * {@value #ID_UNSUPPORTED}.</p> * * @return The right eye position, or {@code null} if unknown. */ public Point getRightEyePosition() { return mRightEye; } /** * The coordinates of the center of the mouth. * * <p>The coordinates are in * the same space as the ones for {@link #getBounds}. This is an optional * field, may not be supported on all devices. If not * supported, the value will always be set to null. * This value will always be null only if {@link #getId()} returns * {@value #ID_UNSUPPORTED}.</p> * </p> * * @return The mouth position, or {@code null} if unknown. */ public Point getMouthPosition() { return mMouth; } /** * Represent the Face as a string for debugging purposes. */ @Override public String toString() { return String.format( "{ bounds: %s, score: %s, id: %d, " + "leftEyePosition: %s, rightEyePosition: %s, mouthPosition: %s }", mBounds, mScore, mId, mLeftEye, mRightEye, mMouth); } private static void checkNotNull(String name, Object obj) { if (obj == null) { throw new IllegalArgumentException(name + " was required, but it was null"); } } private static void checkNull(String name, Object obj) { if (obj != null) { throw new IllegalArgumentException(name + " was required to be null, but it wasn't"); } } }