זיהוי פנים באמצעות ערכת ML Kit ב-Android

אפשר להשתמש ב-ML Kit כדי לזהות פנים בתמונות ובסרטונים.

ה-API הזה זמין באמצעות ספרייה לא מקובצת שחייבת להוריד לפני השימוש, או ספרייה בחבילה שתגדיל את גודל האפליקציה שלך. צפייה במדריך הזה תמצאו מידע נוסף על ההבדלים. בין שתי אפשרויות ההתקנה.

תכונה	לא חלק מהחבילה	בחבילה
הטמעה	הורדת המודל מתבצעת באופן דינמי דרך Google Play Services.	המודל מקושר באופן סטטי לאפליקציה בזמן ה-build.
גודל האפליקציה	הגדלה של כ-800KB.	הגדלה של כ-6.9MB.
זמן האתחול	יכול להיות שתצטרכו להמתין להורדת המודל לפני השימוש הראשון.	הדגם זמין באופן מיידי

רוצה לנסות?

• מומלץ לשחק עם האפליקציה לדוגמה כדי .
• נסו את הקוד בעצמכם בעזרת Codelab.

לפני שמתחילים

ל-API הזה נדרשת רמת API של Android 21 ומעלה. חשוב לוודא שה-build של האפליקציה משתמש בערך minSdkVersion של 21 ומעלה.

1. בקובץ build.gradle ברמת הפרויקט, חשוב לכלול את במאגר Maven בקטע buildscript וגם בקטע allprojects.

2. הוספת יחסי התלות של ספריות ML Kit Android למודול של המודול ברמת האפליקציה, שהוא בדרך כלל app/build.gradle. יש לבחור אחד מ- בהתאם לצרכים שלכם:

   כדי לקבץ את המודל עם האפליקציה:

   dependencies {
     // ...
     // Use this dependency to bundle the model with your app
     implementation 'com.google.mlkit:face-detection:16.1.7'
   }
   

   כדי להשתמש במודל ב-Google Play Services:

   dependencies {
     // ...
     // Use this dependency to use the dynamically downloaded model in Google Play Services
     implementation 'com.google.android.gms:play-services-mlkit-face-detection:17.1.0'
   }
   

3. אם בוחרים להשתמש במודל ב-Google Play Services, אפשר להגדיר האפליקציה תוריד את המודל באופן אוטומטי למכשיר אחרי שהאפליקציה מותקנת מחנות Play. כדי לעשות את זה, צריך להוסיף את ההצהרה הבאה אל קובץ AndroidManifest.xml של האפליקציה:

   <application ...>
         ...
         <meta-data
             android:name="com.google.mlkit.vision.DEPENDENCIES"
             android:value="face" >
         <!-- To use multiple models: android:value="face,model2,model3" -->
   </application>
   

   אפשר גם לבדוק באופן מפורש את זמינות המודל ולבקש הורדה דרך API של ModuleInstallClient ב-Google Play Services.

   אם לא תפעילו הורדות של מודלים בזמן ההתקנה או תבקשו הורדה מפורשת, מתבצעת הורדה של המודל בפעם הראשונה שמפעילים את הגלאי. הבקשות שלכם לפני שההורדה הסתיימה, לא נמצאו תוצאות.

הנחיות להוספת תמונה

לזיהוי פנים, עליך להשתמש בתמונה במידות של 480x360 פיקסלים לפחות. כדי ש-ML Kit יוכל לזהות פנים באופן מדויק, תמונות הקלט חייבות להכיל פנים שמיוצגים על ידי כמות מספקת של נתוני פיקסלים. באופן כללי, כל פנים שרוצים לזיהוי תמונה, צריכים להיות לפחות 100x100 פיקסלים. אם רוצים לזהות את קווי המתאר של הפנים, ל-ML Kit נדרש קלט ברזולוציה גבוהה יותר: כל פנים צריכה להיות לפחות 200x200 פיקסלים.

אם אתם מזהים פנים באפליקציה בזמן אמת, יכול להיות שתרצו כדי לקחת בחשבון את המידות הכוללות של תמונות הקלט. ניתן להשתמש בתמונות קטנות יותר מעובד מהר יותר, כדי לצמצם את זמן האחזור, לצלם תמונות ברזולוציות נמוכות יותר לעמוד בדרישות הדיוק שפורטו למעלה, ולוודא הפנים של מושא הצילום תופסות כמה שיותר מהתמונה. ראו גם טיפים לשיפור הביצועים בזמן אמת.

גם מיקוד תמונה לא טוב יכול להשפיע על רמת הדיוק. אם לא מתקבל אישור מצידך תוצאות, בקשו מהמשתמש לצלם מחדש את התמונה.

הכיוון של הפנים ביחס למצלמה יכול להשפיע גם על ש-ML Kit מזהה. צפייה מושגים של זיהוי פנים.

1. הגדרת גלאי הפנים

לפני שמפעילים זיהוי פנים על תמונה, אם רוצים לשנות את הגדרות ברירת המחדל של מזהה הפנים, יש לציין את ההגדרות האלה אובייקט FaceDetectorOptions. אפשר לשנות את ההגדרות הבאות:

הגדרות
setPerformanceMode	PERFORMANCE_MODE_FAST (ברירת המחדל) | PERFORMANCE_MODE_ACCURATE העדפה של המהירות או הדיוק בזיהוי פנים.
setLandmarkMode	LANDMARK_MODE_NONE (ברירת המחדל) | LANDMARK_MODE_ALL האם לנסות לזהות "סימני דרך" לפנים: עיניים, אוזניים, אף, הלחיים, הפה וכו'.
setContourMode	CONTOUR_MODE_NONE (ברירת המחדל) | CONTOUR_MODE_ALL הגדרה שקובעת אם לזהות את קווי המתאר של תווי הפנים. קווי המתאר הם לזהות רק את הפנים הבולטות ביותר בתמונה.
setClassificationMode	CLASSIFICATION_MODE_NONE (ברירת המחדל) | CLASSIFICATION_MODE_ALL האם לסווג פנים בקטגוריות כמו 'חיוך', וגם "עיניים פקוחות".
setMinFaceSize	float (ברירת המחדל: 0.1f) מגדיר את גודל הפנים הקטן ביותר הרצוי, מבוטא כיחס של רוחב הראש עד רוחב התמונה.
enableTracking	false (ברירת מחדל) | true האם להקצות או לא להקצות מזהה, שיכול לשמש כדי לעקוב פנים בין תמונות. שימו לב שכשזיהוי קווי מתאר מופעל, רק פנים אחת זיהוי הפנים לא מספק תוצאות מועילות. בשביל זה סיבה, וכדי לשפר את מהירות הזיהוי, אל תפעילו שני קווי מתאר זיהוי פנים ומעקב אחר הפנים.

לדוגמה:

Kotlin

// High-accuracy landmark detection and face classification
val highAccuracyOpts = FaceDetectorOptions.Builder()
        .setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_ACCURATE)
        .setLandmarkMode(FaceDetectorOptions.LANDMARK_MODE_ALL)
        .setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
        .build()

// Real-time contour detection
val realTimeOpts = FaceDetectorOptions.Builder()
        .setContourMode(FaceDetectorOptions.CONTOUR_MODE_ALL)
        .build()
FaceDetectionActivity.kt

Java

// High-accuracy landmark detection and face classification
FaceDetectorOptions highAccuracyOpts =
        new FaceDetectorOptions.Builder()
                .setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_ACCURATE)
                .setLandmarkMode(FaceDetectorOptions.LANDMARK_MODE_ALL)
                .setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
                .build();

// Real-time contour detection
FaceDetectorOptions realTimeOpts =
        new FaceDetectorOptions.Builder()
                .setContourMode(FaceDetectorOptions.CONTOUR_MODE_ALL)
                .build();
FaceDetectionActivity.java

2. הכנת תמונת הקלט

כדי לזהות פנים בתמונה, צריך ליצור אובייקט InputImage מ-Bitmap, media.Image, ByteBuffer, ממערך בייטים או מקובץ במכשיר. לאחר מכן מעבירים את האובייקט InputImage אל השיטה process של FaceDetector.

כדי להשתמש בזיהוי פנים, עליך להשתמש בתמונה שהמידות שלה הן לפחות 480x360 פיקסלים. אם מזהים פנים בזמן אמת, אפשר לצלם פריימים ברזולוציה המינימלית הזו, יעזרו לכם לצמצם את זמן האחזור.

אפשר ליצור InputImage ממקורות שונים, מוסבר על כל אחד מהם בהמשך.

באמצעות media.Image

כדי ליצור InputImage מאובייקט media.Image, למשל כשמצלמים תמונה המצלמה של המכשיר, מעבירים את האובייקט media.Image ואת ל-InputImage.fromMediaImage().

אם משתמשים ספריית CameraX, OnImageCapturedListener ImageAnalysis.Analyzer מחלקות מחשבים את ערך הסבב עבורך.

Kotlin

private class YourImageAnalyzer : ImageAnalysis.Analyzer {

    override fun analyze(imageProxy: ImageProxy) {
        val mediaImage = imageProxy.image
        if (mediaImage != null) {
            val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

Java

private class YourAnalyzer implements ImageAnalysis.Analyzer {

    @Override
    public void analyze(ImageProxy imageProxy) {
        Image mediaImage = imageProxy.getImage();
        if (mediaImage != null) {
          InputImage image =
                InputImage.fromMediaImage(mediaImage, imageProxy.getImageInfo().getRotationDegrees());
          // Pass image to an ML Kit Vision API
          // ...
        }
    }
}

אם לא משתמשים בספריית מצלמה שמאפשרת לקבוע את כיוון הסיבוב של התמונה, הוא יכול לחשב אותו על סמך זווית הסיבוב של המכשיר וכיוון המצלמה החיישן במכשיר:

Kotlin

private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 0)
    ORIENTATIONS.append(Surface.ROTATION_90, 90)
    ORIENTATIONS.append(Surface.ROTATION_180, 180)
    ORIENTATIONS.append(Surface.ROTATION_270, 270)
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Throws(CameraAccessException::class)
private fun getRotationCompensation(cameraId: String, activity: Activity, isFrontFacing: Boolean): Int {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    val deviceRotation = activity.windowManager.defaultDisplay.rotation
    var rotationCompensation = ORIENTATIONS.get(deviceRotation)

    // Get the device's sensor orientation.
    val cameraManager = activity.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION)!!

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360
    }
    return rotationCompensation
}
MLKitVisionImage.kt

Java

private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
static {
    ORIENTATIONS.append(Surface.ROTATION_0, 0);
    ORIENTATIONS.append(Surface.ROTATION_90, 90);
    ORIENTATIONS.append(Surface.ROTATION_180, 180);
    ORIENTATIONS.append(Surface.ROTATION_270, 270);
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
private int getRotationCompensation(String cameraId, Activity activity, boolean isFrontFacing)
        throws CameraAccessException {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation();
    int rotationCompensation = ORIENTATIONS.get(deviceRotation);

    // Get the device's sensor orientation.
    CameraManager cameraManager = (CameraManager) activity.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360;
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360;
    }
    return rotationCompensation;
}

לאחר מכן, מעבירים את האובייקט media.Image הערך של מעלה הסיבוב ל-InputImage.fromMediaImage():

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromMediaImage(mediaImage, rotation);

שימוש ב-URI של קובץ

כדי ליצור InputImage מ-URI של קובץ, מעבירים את ההקשר של האפליקציה ואת ה-URI של הקובץ InputImage.fromFilePath() זה שימושי כאשר צריך להשתמש ב-Intent ACTION_GET_CONTENT כדי לבקש מהמשתמש לבחור תמונה מאפליקציית הגלריה.

Kotlin

val image: InputImage
try {
    image = InputImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}
MLKitVisionImage.kt

Java

InputImage image;
try {
    image = InputImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}

שימוש ב-ByteBuffer או ב-ByteArray

כדי ליצור InputImage מ-ByteBuffer או מ-ByteArray, קודם צריך לחשב את התמונה מעלות סיבוב כפי שתואר קודם לכן עבור קלט media.Image. אחר כך יוצרים את האובייקט InputImage עם מאגר נתונים זמני או מערך, יחד עם גובה, רוחב, פורמט קידוד צבעים ומידת סיבוב:

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java

באמצעות Bitmap

כדי ליצור InputImage מאובייקט Bitmap, צריך ליצור את ההצהרה הבאה:

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);
MLKitVisionImage.java

התמונה מיוצגת על ידי אובייקט Bitmap ביחד עם מעלות סיבוב.

3. קבלת מופע של FaceDetector

Kotlin

val detector = FaceDetection.getClient(options)
// Or, to use the default option:
// val detector = FaceDetection.getClient();
FaceDetectionActivity.kt

Java

FaceDetector detector = FaceDetection.getClient(options);
// Or use the default options:
// FaceDetector detector = FaceDetection.getClient();
FaceDetectionActivity.java

4. עיבוד התמונה

מעבירים את התמונה ל-method process:

Kotlin

val result = detector.process(image)
        .addOnSuccessListener { faces ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }
FaceDetectionActivity.kt

Java

Task<List<Face>> result =
        detector.process(image)
                .addOnSuccessListener(
                        new OnSuccessListener<List<Face>>() {
                            @Override
                            public void onSuccess(List<Face> faces) {
                                // Task completed successfully
                                // ...
                            }
                        })
                .addOnFailureListener(
                        new OnFailureListener() {
                            @Override
                            public void onFailure(@NonNull Exception e) {
                                // Task failed with an exception
                                // ...
                            }
                        });
FaceDetectionActivity.java

הערה: אם אתה משתמש ב API של CameraX, חשוב לסגור את ImageProxy בסיום השימוש בו. למשל, על ידי הוספה של OnCompleteListener אל Task שהוחזר שיטת process. לצפייה VisionProcessorBase באפליקציה לדוגמה של המדריך למתחילים.

5. קבלת מידע על פנים שזוהו

אם זיהוי הפנים יצליח, תוצג רשימה של Face אובייקטים מועברים בהצלחה Listener. כל אובייקט Face מייצג פנים שזוהו בתמונה. עבור כל פנים ניתן לקבל את הקואורדינטות התוחמות בקלט וגם כל מידע אחר שהגדרתם עבורו את גלאי הפנים למצוא. לדוגמה:

Kotlin

for (face in faces) {
    val bounds = face.boundingBox
    val rotY = face.headEulerAngleY // Head is rotated to the right rotY degrees
    val rotZ = face.headEulerAngleZ // Head is tilted sideways rotZ degrees

    // If landmark detection was enabled (mouth, ears, eyes, cheeks, and
    // nose available):
    val leftEar = face.getLandmark(FaceLandmark.LEFT_EAR)
    leftEar?.let {
        val leftEarPos = leftEar.position
    }

    // If contour detection was enabled:
    val leftEyeContour = face.getContour(FaceContour.LEFT_EYE)?.points
    val upperLipBottomContour = face.getContour(FaceContour.UPPER_LIP_BOTTOM)?.points

    // If classification was enabled:
    if (face.smilingProbability != null) {
        val smileProb = face.smilingProbability
    }
    if (face.rightEyeOpenProbability != null) {
        val rightEyeOpenProb = face.rightEyeOpenProbability
    }

    // If face tracking was enabled:
    if (face.trackingId != null) {
        val id = face.trackingId
    }
}
FaceDetectionActivity.kt

Java

for (Face face : faces) {
    Rect bounds = face.getBoundingBox();
    float rotY = face.getHeadEulerAngleY();  // Head is rotated to the right rotY degrees
    float rotZ = face.getHeadEulerAngleZ();  // Head is tilted sideways rotZ degrees

    // If landmark detection was enabled (mouth, ears, eyes, cheeks, and
    // nose available):
    FaceLandmark leftEar = face.getLandmark(FaceLandmark.LEFT_EAR);
    if (leftEar != null) {
        PointF leftEarPos = leftEar.getPosition();
    }

    // If contour detection was enabled:
    List<PointF> leftEyeContour =
            face.getContour(FaceContour.LEFT_EYE).getPoints();
    List<PointF> upperLipBottomContour =
            face.getContour(FaceContour.UPPER_LIP_BOTTOM).getPoints();

    // If classification was enabled:
    if (face.getSmilingProbability() != null) {
        float smileProb = face.getSmilingProbability();
    }
    if (face.getRightEyeOpenProbability() != null) {
        float rightEyeOpenProb = face.getRightEyeOpenProbability();
    }

    // If face tracking was enabled:
    if (face.getTrackingId() != null) {
        int id = face.getTrackingId();
    }
}
FaceDetectionActivity.java

דוגמה לקווי מתאר של הפנים

כשזיהוי קווי הפנים מופעל, מקבלים רשימה של נקודות עבור שכל תכונת פנים שזוהתה. הנקודות האלה מייצגות את הצורה של . הצגת פנים מושגי זיהוי לקבלת פרטים על האופן שבו קווי מתאר שמיוצגים על ידיכם.

התמונה הבאה ממחישה איך הנקודות האלה ממופות לפנים. צריך ללחוץ על תמונה כדי להגדיל אותה:

זיהוי פנים בזמן אמת

כדי להשתמש בזיהוי פנים באפליקציה בזמן אמת, צריך לפעול לפי השלבים הבאים כדי להשיג את קצבי הפריימים הטובים ביותר:

• צריך להגדיר את גלאי הפנים כך שיעשה שימוש זיהוי או סיווג פנים וזיהוי של ציוני דרך, אבל לא שניהם:

  זיהוי קווי מתאר
  זיהוי ציוני דרך
  סיווג
  זיהוי וסיווג של ציוני דרך
  זיהוי קווי מתאר וזיהוי של ציוני דרך
  זיהוי וסיווג של קווי מתאר
  זיהוי קווי מתאר, זיהוי של ציוני דרך וסיווג
  

• הפעלה של מצב FAST (מופעל כברירת מחדל).

• כדאי לצלם תמונות ברזולוציה נמוכה יותר. עם זאת, חשוב גם לזכור בדרישות של מידות התמונה ב-API הזה.

אם משתמשים Camera או camera2 API, הפעלות של הגלאי באמצעות ויסות נתונים (throttle). אם מדובר בסרטון חדש הופכת לזמינה כשהגלאי פועל, משחררים את הפריים. לצפייה VisionProcessorBase באפליקציה לדוגמה של המדריך למתחילים.

אם אתם משתמשים ב-API של CameraX, יש לוודא שאסטרטגיית הלחץ החוזר מוגדרת לערך ברירת המחדל שלה ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST כך אפשר להבטיח שרק תמונה אחת תוצג לניתוח בכל פעם. אם עוד תמונות שנוצרות כשהכלי לניתוח נתונים עמוס, הוא יוסר באופן אוטומטי ולא ימתין בתור משלוח. לאחר שהתמונה שמנתחת נסגרת על ידי קריאה ImageProxy.close(), התמונה האחרונה הבאה תישלח.

אם משתמשים בפלט של הגלאי כדי להציג גרפיקה בשכבת-על מקבלים קודם את התוצאה מ-ML Kit ואז מעבדים את התמונה וליצור שכבת-על בשלב אחד. הוא מוצג לפני השטח של המסך פעם אחת בלבד לכל מסגרת קלט. לצפייה CameraSourcePreview וגם GraphicOverlay, באפליקציה לדוגמה של המדריך למתחילים.

אם משתמשים ב- Camera2 API, מצלמים תמונות ב פורמט של ImageFormat.YUV_420_888. אם משתמשים בגרסה הישנה של ה-API של המצלמה, מצלמים תמונות ב פורמט של ImageFormat.NV21.