Wykrywanie twarzy za pomocą ML Kit na Androidzie

Za pomocą ML Kit możesz wykrywać twarze na zdjęciach i filmach.

FunkcjaNiegrupowaneŁączenie w pakiety
ImplementacjaModel jest pobierany dynamicznie przez Usługi Google Play.Model jest statycznie połączony z aplikacją w czasie kompilacji.
Rozmiar aplikacjiZwiększono rozmiar o około 800 KB.Zwiększenie rozmiaru o około 6,9 MB.
Czas inicjowaniaMożliwe, że przed pierwszym użyciem trzeba będzie poczekać na pobranie modelu.Model jest dostępny od razu

Wypróbuj

Zanim zaczniesz

  1. Upewnij się, że w sekcji buildscript i allprojects w pliku build.gradle Google na poziomie projektu znajduje się repozytorium Maven.

  2. Dodaj zależności dla bibliotek ML Kit na Androida do pliku Gradle na poziomie modułu. Zwykle ma on postać app/build.gradle. Wybierz jedną z tych zależności w zależności od potrzeb:

    Aby połączyć model w pakiet z aplikacją:

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

    Aby używać modelu w Usługach Google Play:

    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. Jeśli zdecydujesz się używać modelu w Usługach Google Play, możesz skonfigurować automatyczne pobieranie modelu przez aplikację po jej zainstalowaniu ze Sklepu Play. Aby to zrobić, dodaj tę deklarację do pliku AndroidManifest.xml aplikacji:

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

    Możesz też wyraźnie sprawdzić dostępność modelu i poprosić o pobranie za pomocą interfejsu ModuleInstallClient API z Usług Google Play.

    Jeśli nie włączysz pobierania modelu podczas instalacji ani nie zażądasz jawnego pobierania, model zostanie pobrany przy pierwszym uruchomieniu detektora. Żądania wysłane przed zakończeniem pobierania nie dają żadnych wyników.

Wskazówki dotyczące obrazu wejściowego

Do rozpoznawania twarzy użyj obrazu o wymiarach co najmniej 480 x 360 pikseli. Aby narzędzie ML Kit mogło dokładnie wykrywać twarze, obrazy wejściowe muszą zawierać twarze reprezentowane przez wystarczającą ilość danych pikseli. Ogólnie każda twarz, która ma być wykrywana na obrazie, powinna mieć rozmiar co najmniej 100 × 100 pikseli. Jeśli chcesz wykrywać kontury twarzy, ML Kit wymaga wprowadzania danych w wyższej rozdzielczości: każda twarz powinna mieć co najmniej 200 × 200 pikseli.

Jeśli wykryjesz twarze w aplikacji rejestrującej dane w czasie rzeczywistym, możesz też wziąć pod uwagę ogólne wymiary obrazów wejściowych. Mniejsze obrazy mogą być przetwarzane szybciej. Aby zmniejszyć opóźnienie, rób obrazy w niższej rozdzielczości, pamiętając przy tym o powyższych wymaganiach dotyczących dokładności i dopilnuj, by twarz osoby, która była widoczna na obrazie, zajmowała jak najwięcej miejsca na obrazie. Zobacz też wskazówki dotyczące zwiększania wydajności w czasie rzeczywistym.

Słaba ostrość obrazu może również wpływać na dokładność. Jeśli nie uda się uzyskać zadowalających wyników, poproś użytkownika o ponowne zrobienie zdjęcia.

Orientacja twarzy względem kamery może też wpływać na to, co wykryje zestaw ML Kit. Zobacz Pojęcia związane z wykrywaniem twarzy.

1. Skonfiguruj wykrywanie twarzy

Jeśli przed zastosowaniem wykrywania twarzy do zdjęcia chcesz zmienić któreś z domyślnych ustawień wykrywania twarzy, określ je za pomocą obiektu FaceDetectorOptions. Możesz zmienić te ustawienia:

Ustawienia
setPerformanceMode PERFORMANCE_MODE_FAST (domyślny) | PERFORMANCE_MODE_ACCURATE

Zwiększ szybkość lub dokładność wykrywania twarzy.

setLandmarkMode LANDMARK_MODE_NONE (domyślny) | LANDMARK_MODE_ALL

Określa, czy chcesz zidentyfikować „charakterystyczne cechy” twarzy: oczy, uszy, nos, policzki, usta itd.

setContourMode CONTOUR_MODE_NONE (domyślny) | CONTOUR_MODE_ALL

Czy wykrywać kontury twarzy. Kontury są wykrywane tylko dla najbardziej widocznej twarzy na obrazie.

setClassificationMode CLASSIFICATION_MODE_NONE (domyślny) | CLASSIFICATION_MODE_ALL

Określa, czy należy klasyfikować twarze w kategoriach, takich jak „uśmiech” i „otwarte oczy”.

setMinFaceSize float (domyślnie: 0.1f)

Ustawia najmniejszy żądany rozmiar twarzy wyrażony jako stosunek szerokości głowy do szerokości obrazu.

enableTracking false (domyślny) | true

Określa, czy przypisać twarzom identyfikator, który może służyć do śledzenia twarzy na różnych obrazach.

Pamiętaj, że gdy wykrywanie konturu jest włączone, wykrywana jest tylko 1 twarz, więc śledzenie twarzy nie daje przydatnych wyników. Dlatego i aby poprawić szybkość wykrywania, nie włączaj jednocześnie wykrywania konturu i śledzenia twarzy.

Na przykład:

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()

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();

2. Przygotowywanie obrazu wejściowego

Aby wykrywać twarze na zdjęciu, utwórz obiekt InputImage z Bitmap, media.Image, ByteBuffer, tablicy bajtów lub pliku na urządzeniu. Następnie przekaż obiekt InputImage do metody process metody FaceDetector.

Do wykrywania twarzy użyj obrazu o wymiarach co najmniej 480 x 360 pikseli. Jeśli wykrywasz twarze w czasie rzeczywistym, nagrywanie klatek w tej minimalnej rozdzielczości może pomóc w zmniejszeniu czasu oczekiwania.

Obiekt InputImage możesz tworzyć z różnych źródeł. Zostały one wyjaśnione poniżej.

Przy użyciu: media.Image

Aby utworzyć obiekt InputImage z obiektu media.Image, na przykład podczas robienia zdjęcia aparatem urządzenia, przekaż obiekt media.Image i obrót obrazu do wartości InputImage.fromMediaImage().

Jeśli używasz biblioteki KameraX, klasy OnImageCapturedListener i ImageAnalysis.Analyzer obliczają za Ciebie wartość rotacji.

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
          // ...
        }
    }
}

Jeśli nie korzystasz z biblioteki aparatu, która określa stopień obrotu obrazu, możesz ją obliczyć na podstawie stopnia obrotu urządzenia i orientacji czujnika aparatu:

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
}

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;
}

Następnie przekaż obiekt media.Image i wartość stopnia obrotu do InputImage.fromMediaImage():

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)

Java

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

Korzystanie z identyfikatora URI pliku

Aby utworzyć obiekt InputImage na podstawie identyfikatora URI pliku, przekaż kontekst aplikacji i identyfikator URI pliku do InputImage.fromFilePath(). Jest to przydatne, gdy używasz intencji ACTION_GET_CONTENT, aby prosić użytkownika o wybranie obrazu z aplikacji galerii.

Kotlin

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

Java

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

Za pomocą: ByteBuffer lub ByteArray

Aby utworzyć obiekt InputImage na podstawie ByteBuffer lub ByteArray, najpierw oblicz stopień obrotu obrazu zgodnie z opisem powyżej dla danych wejściowych media.Image. Następnie utwórz obiekt InputImage z buforem lub tablicą oraz podaj wysokość, szerokość, format kodowania kolorów i stopień obrotu obrazu:

Kotlin

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

Java

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

Przy użyciu: Bitmap

Aby utworzyć obiekt InputImage z obiektu Bitmap, złóż tę deklarację:

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)

Java

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

Obraz jest reprezentowany przez obiekt Bitmap razem z obróconymi stopniami.

3. Pobieranie wystąpienia funkcji FaceDetector

Kotlin

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

Java

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

4. Przetwarzanie obrazu

Przekaż obraz do metody process:

Kotlin

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

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
                                // ...
                            }
                        });

5. Uzyskiwanie informacji o wykrytych twarzach

Jeśli operacja wykrywania twarzy zakończy się powodzeniem, lista obiektów Face zostanie przekazana do nasłuchującego. Każdy obiekt Face reprezentuje twarz wykrytą na obrazie. W przypadku każdej twarzy możesz uzyskać współrzędne ograniczające na obrazie wejściowym, a także wszelkie inne informacje, które zostały przez Ciebie skonfigurowane przez wykrywanie twarzy. Na przykład:

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

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();
    }
}

Przykładowe kontury twarzy

Gdy wykrywanie konturu twarzy jest włączone, otrzymujesz listę punktów dla każdej wykrytej funkcji twarzy. Te punkty reprezentują kształt obiektu. Szczegółowe informacje o tym, jak są przedstawiane kontury, znajdziesz w artykule Pojęcia związane z wykrywaniem twarzy.

Poniższa ilustracja przedstawia sposób mapowania tych punktów na twarz. Kliknij obraz, aby go powiększyć:

przykładowa siatka konturu twarzy

Wykrywanie twarzy w czasie rzeczywistym

Jeśli chcesz używać wykrywania twarzy w aplikacji przesyłającej dane w czasie rzeczywistym, postępuj zgodnie z tymi wskazówkami, aby uzyskać najlepszą liczbę klatek:

  • Skonfiguruj wykrywacz twarzy, aby używał wykrywania konturów twarzy albo klasyfikacji i punktu orientacyjnego, ale nie obu jednocześnie:

    Wykrywanie granic






  • Włącz tryb FAST (domyślnie włączony).

  • Rozważ robienie zdjęć w niższej rozdzielczości. Pamiętaj jednak o wymaganiach tego interfejsu API dotyczących wymiarów.

  • Jeśli używasz interfejsu API Camera lub camera2, ogranicz wywołania wzorca do wykrywania treści. Jeśli podczas działania wzorca pojawi się nowa klatka wideo, upuść ją. Przykład znajdziesz w klasie VisionProcessorBase w przykładowej aplikacji krótkiego wprowadzenia.
  • Jeśli korzystasz z interfejsu API CameraX, upewnij się, że strategia dotycząca ciśnienia wstecznego jest ustawiona na wartość domyślną ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Gwarantuje to, że w danym momencie do analizy będzie dostarczany tylko 1 obraz. Jeśli w czasie, gdy analizator jest zajęty, zostanie utworzonych więcej obrazów, zostaną one automatycznie usunięte i nie zostaną umieszczone w kolejce do dostarczenia. Gdy analizowany obraz zostanie zamknięty przez wywołanie ImageProxy.close(), zostanie dostarczony następny najnowszy obraz.
  • Jeśli używasz danych wyjściowych detektora do nakładania grafiki na obraz wejściowy, najpierw pobierz wynik z ML Kit, a następnie wyrenderuj obraz i nakładkę w jednym kroku. Wyświetla się na powierzchni wyświetlacza tylko raz dla każdej klatki wejściowej. Przykład znajdziesz w klasach CameraSourcePreview i GraphicOverlay w przykładowej aplikacji z krótkim wprowadzeniem.
  • Jeśli korzystasz z interfejsu Camera2 API, zrób zdjęcia w formacie ImageFormat.YUV_420_888. Jeśli używasz starszej wersji interfejsu Camera API, zrób zdjęcia w formacie ImageFormat.NV21.