Selfie-Segmentierung mit ML Kit für Android

Diese API wird in der Betaversion angeboten und unterliegt keinem SLA und keiner Richtlinie zur Einstellung von Produkten und Diensten. An dieser API können Änderungen vorgenommen werden, die die Abwärtskompatibilität beeinträchtigen.

ML Kit bietet ein optimiertes SDK für die Selfie-Segmentierung.

Diese API verwendet eine gebündelte Bibliothek, die die Größe Ihrer App erhöht. Weitere Informationen finden Sie in diesem Leitfaden.

Die Selfie Segmenter-Assets sind zum Zeitpunkt der Erstellung statisch mit Ihrer App verknüpft. Dadurch wird die Downloadgröße Ihrer App um etwa 4, 5 MB erhöht und die API-Latenz kann je nach Größe des Eingabebilds (gemessen auf einem Pixel 4) zwischen 25 ms und 65 ms variieren.

Ausprobieren

• Probieren Sie die Beispiel-App aus, um ein Beispiel für die Verwendung dieser API zu sehen.

Hinweis

Diese API erfordert Android API-Level 21 oder höher. Achten Sie darauf, dass die Build-Datei Ihrer Anwendung einen minSdkVersion-Wert von 21 oder höher verwendet.

1. Fügen Sie in der Datei build.gradle auf Projektebene in den Abschnitten buildscript und allprojects das Maven-Repository von Google ein.
2. Fügen Sie der Gradle-Datei Ihres Moduls auf App-Ebene die Abhängigkeiten für die ML Kit-Android-Bibliotheken hinzu. Diese Datei ist normalerweise app/build.gradle:

dependencies {
  implementation 'com.google.mlkit:segmentation-selfie:16.0.0-beta4'
}

1. Segmenter-Instanz erstellen

Segmentierungsoptionen

Um ein Bild zu segmentieren, erstellen Sie zuerst eine Instanz von Segmenter. Geben Sie dazu die folgenden Optionen an.

Detektormodus

Der Segmenter funktioniert in zwei Modi. Wählen Sie die Option aus, die zu Ihrem Anwendungsfall passt.

STREAM_MODE (default)

Dieser Modus ist für das Streamen von Frames aus Videos oder Kameras geeignet. In diesem Modus nutzt die Segmentierung die Ergebnisse früherer Frames, um eine flüssigere Segmentierung zu ermöglichen.

SINGLE_IMAGE_MODE

Dieser Modus ist für einzelne Bilder geeignet, die keinen Bezug haben. In diesem Modus verarbeitet die Segmentierung jedes Bild einzeln, ohne eine Glättung über Frames.

Maske für Rohgröße aktivieren

Fordert den Segmentierer auf, die Maske mit der Rohgröße zurückzugeben, die der Größe der Modellausgabe entspricht.

Die Größe der Rohmaske (z.B. 256 x 256) ist in der Regel kleiner als die Größe des Eingabebilds. Rufe SegmentationMask#getWidth() und SegmentationMask#getHeight() auf, um die Maskengröße zu erhalten, wenn du diese Option aktivierst.

Ohne Angabe dieser Option skaliert der Segmentierer die Rohmaske neu, damit sie der Größe des Eingabebilds entspricht. Ziehen Sie diese Option in Betracht, wenn Sie eine benutzerdefinierte Logik zur Neuskalierung anwenden möchten oder eine Neuskalierung für Ihren Anwendungsfall nicht erforderlich ist.

Legen Sie die Segmentierungsoptionen fest:

Kotlin

val options =
        SelfieSegmenterOptions.Builder()
            .setDetectorMode(SelfieSegmenterOptions.STREAM_MODE)
            .enableRawSizeMask()
            .build()

Java

SelfieSegmenterOptions options =
        new SelfieSegmenterOptions.Builder()
            .setDetectorMode(SelfieSegmenterOptions.STREAM_MODE)
            .enableRawSizeMask()
            .build();

Erstellen Sie eine Instanz von Segmenter. Übergeben Sie die angegebenen Optionen:

Kotlin

val segmenter = Segmentation.getClient(options)

Java

Segmenter segmenter = Segmentation.getClient(options);

2. Eingabebild vorbereiten

Um ein Bild zu segmentieren, erstellen Sie ein InputImage-Objekt aus einem Bitmap-, media.Image-, ByteBuffer-, Byte-Array oder einer Datei auf dem Gerät.

Sie können ein InputImage-Objekt aus verschiedenen Quellen erstellen. Diese werden im Folgenden beschrieben.

Mit einem media.Image

Wenn Sie ein InputImage-Objekt aus einem media.Image-Objekt erstellen möchten, z. B. wenn Sie ein Bild mit der Kamera eines Geräts aufnehmen, übergeben Sie das media.Image-Objekt und die Bilddrehung an InputImage.fromMediaImage().

Wenn Sie die CameraX-Bibliothek verwenden, berechnen die Klassen OnImageCapturedListener und ImageAnalysis.Analyzer den Rotationswert für Sie.

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

Wenn du keine Kamerabibliothek verwendest, die den Drehgrad des Bildes angibt, kannst du ihn anhand des Gerätedrehungsgrads und der Ausrichtung des Kamerasensors im Gerät berechnen:

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

Übergeben Sie dann das Objekt media.Image und den Wert für den Rotationsgrad an InputImage.fromMediaImage():

Kotlin

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

Java

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

Datei-URI verwenden

Übergeben Sie den App-Kontext und den Datei-URI an InputImage.fromFilePath(), um ein InputImage-Objekt aus einem Datei-URI zu erstellen. Das ist nützlich, wenn du den Nutzer mit einem ACTION_GET_CONTENT-Intent zur Auswahl eines Bildes aus der Galerie-App aufforderst.

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

Mit ByteBuffer oder ByteArray

Berechnen Sie zuerst den Bilddrehungsgrad wie zuvor für die media.Image-Eingabe beschrieben, um ein InputImage-Objekt aus einem ByteBuffer- oder ByteArray-Objekt zu erstellen. Erstellen Sie dann das InputImage-Objekt mit dem Puffer oder Array und geben dabei Höhe, Breite, Farbcodierungsformat und Rotationsgrad des Bildes an:

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

Mit einem Bitmap

Mit der folgenden Deklaration kannst du ein InputImage-Objekt aus einem Bitmap-Objekt erstellen:

Kotlin

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

Java

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

Das Bild wird durch ein Bitmap-Objekt zusammen mit Rotationsgraden dargestellt.

3. Bild verarbeiten

Übergeben Sie das vorbereitete InputImage-Objekt an die process-Methode der Segmenter.

Kotlin

Task<SegmentationMask> result = segmenter.process(image)
       .addOnSuccessListener { results ->
           // Task completed successfully
           // ...
       }
       .addOnFailureListener { e ->
           // Task failed with an exception
           // ...
       }

Java

Task<SegmentationMask> result =
        segmenter.process(image)
                .addOnSuccessListener(
                        new OnSuccessListener<SegmentationMask>() {
                            @Override
                            public void onSuccess(SegmentationMask mask) {
                                // Task completed successfully
                                // ...
                            }
                        })
                .addOnFailureListener(
                        new OnFailureListener() {
                            @Override
                            public void onFailure(@NonNull Exception e) {
                                // Task failed with an exception
                                // ...
                            }
                        });

Hinweis: Wenn du die CameraX API verwendest, musst du ImageProxy nach der Verwendung schließen. Dazu fügst du dem Task-Objekt, das von der Methode process zurückgegeben wird, ein OnCompleteListener hinzu. Ein Beispiel hierfür finden Sie in der Beispiel-App der Kurzanleitung in der Klasse VisionProcessorBase.

4. Segmentierungsergebnis abrufen

So erhalten Sie das Segmentierungsergebnis:

Kotlin

val mask = segmentationMask.getBuffer()
val maskWidth = segmentationMask.getWidth()
val maskHeight = segmentationMask.getHeight()

for (val y = 0; y < maskHeight; y++) {
  for (val x = 0; x < maskWidth; x++) {
    // Gets the confidence of the (x,y) pixel in the mask being in the foreground.
    val foregroundConfidence = mask.getFloat()
  }
}

Java

ByteBuffer mask = segmentationMask.getBuffer();
int maskWidth = segmentationMask.getWidth();
int maskHeight = segmentationMask.getHeight();

for (int y = 0; y < maskHeight; y++) {
  for (int x = 0; x < maskWidth; x++) {
    // Gets the confidence of the (x,y) pixel in the mask being in the foreground.
    float foregroundConfidence = mask.getFloat();
  }
}

Ein vollständiges Beispiel für die Verwendung der Segmentierungsergebnisse finden Sie im ML Kit-Kurzanleitungsbeispiel.

Tipps zur Leistungsverbesserung

Die Qualität der Ergebnisse hängt von der Qualität des Eingabebilds ab:

• Damit ML Kit ein genaues Segmentierungsergebnis erhält, sollte das Bild mindestens 256 × 256 Pixel groß sein.
• Ein schlechter Bildfokus kann auch die Genauigkeit beeinträchtigen. Wenn Sie keine akzeptablen Ergebnisse erhalten, bitten Sie den Nutzer, ein neues Bild aufzunehmen.

Wenn Sie die Segmentierung in einer Echtzeitanwendung verwenden möchten, beachten Sie die folgenden Richtlinien, um die besten Frame-Rates zu erzielen:

• STREAM_MODE verwenden.
• Nehmen Sie Bilder mit einer niedrigeren Auflösung auf. Beachten Sie jedoch auch die Anforderungen an die Bildabmessung dieser API.
• Erwägen Sie, die Option für die Rohgröße der Maske zu aktivieren und die gesamte Neuskalierungslogik miteinander zu kombinieren. Anstatt beispielsweise zu lassen, dass die API die Maske erst neu skaliert, damit sie der eingegebenen Bildgröße entspricht, und sie dann noch einmal entsprechend der Ansichtsgröße für die Anzeige skalieren, fordern Sie einfach die Maske der Rohgröße an und kombinieren Sie diese beiden Schritte zu einem.
• Wenn Sie die Camera oder camera2 API verwenden, drosseln Sie Aufrufe an den Detektor. Falls ein neuer Videoframe verfügbar wird, während der Detektor ausgeführt wird, löschen Sie diesen. Ein Beispiel hierfür finden Sie in der Beispiel-App der Kurzanleitung in der Klasse VisionProcessorBase.
• Wenn Sie die CameraX API verwenden, muss die Abwärtsdruckstrategie auf den Standardwert ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST festgelegt sein. Dadurch wird garantiert, dass jeweils nur ein Bild zur Analyse gesendet wird. Wenn weitere Bilder erstellt werden, wenn das Analysetool ausgelastet ist, werden diese automatisch gelöscht und nicht in die Warteschlange gestellt. Sobald das zu analysierende Bild durch Aufrufen von ImageProxy.close() geschlossen wurde, wird das jeweils neueste Image bereitgestellt.
• Wenn Sie die Ausgabe des Detektors verwenden, um Grafiken über das Eingabebild einzublenden, rufen Sie zuerst das Ergebnis aus ML Kit ab und rendern Sie dann das Bild und Overlay in einem einzigen Schritt. Dies wird für jeden Eingabeframe nur einmal auf der Anzeigeoberfläche gerendert. Ein Beispiel finden Sie in der Beispiel-App aus der Kurzanleitung in den Klassen CameraSourcePreview und GraphicOverlay.
• Wenn du die Camera2 API verwendest, nimm Bilder im ImageFormat.YUV_420_888-Format auf. Wenn du die ältere Camera API verwendest, nimm Bilder im ImageFormat.NV21-Format auf.