Oznaczanie obrazów etykietami za pomocą modelu niestandardowego na Androidzie

Za pomocą ML Kit możesz rozpoznawać encje na obrazach i oznaczać je etykietami. Ten interfejs API obsługuje szeroką gamę niestandardowych modeli klasyfikacji obrazów. W artykule Modele niestandardowe z użyciem ML Kit dowiesz się, jakie są wymagania dotyczące zgodności modeli, gdzie znaleźć wytrenowane modele i jak trenować własne modele.

Etykiety obrazów można zintegrować z modelami niestandardowymi na 2 sposoby: łącząc potok w ramach aplikacji lub używając niewgrupowanego potoku, który zależy od Usług Google Play. Jeśli wybierzesz niepołączony potok, aplikacja będzie mniejsza. Szczegółowe informacje znajdziesz w poniższej tabeli.

Model niestandardowy można zintegrować na 2 sposoby: umieść go w pakiecie, umieszczając go w folderze zasobów aplikacji, lub pobierz dynamicznie z Firebase. Tabela poniżej zawiera porównanie tych 2 opcji.

Wypróbuj

• W krótkim wprowadzeniu do aplikacji Vision znajdziesz przykład użycia modelu w pakiecie, a w aplikacji z krótkim wprowadzeniem do Automl – przykład użycia hostowanego modelu.

Zanim zaczniesz

1. Pamiętaj, aby w sekcji buildscript i allprojects w pliku build.gradle na poziomie projektu uwzględnić repozytorium Google 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 swoich potrzeb:

   Aby połączyć potok z aplikacją:

   dependencies {
     // ...
     // Use this dependency to bundle the pipeline with your app
     implementation 'com.google.mlkit:image-labeling-custom:17.0.2'
   }
   

   Na potrzeby wykorzystania potoku w Usługach Google Play:

   dependencies {
     // ...
     // Use this dependency to use the dynamically downloaded pipeline in Google Play Services
     implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta5'
   }
   

3. Jeśli zdecydujesz się korzystać z potoku w Usługach Google Play, możesz skonfigurować w aplikacji automatyczne pobieranie potoku na urządzenie po jej zainstalowaniu ze Sklepu Play. W tym celu dodaj do pliku AndroidManifest.xml aplikacji tę deklarację:

   <application ...>
       ...
       <meta-data
           android:name="com.google.mlkit.vision.DEPENDENCIES"
           android:value="custom_ica" />
       <!-- To use multiple downloads: android:value="custom_ica,download2,download3" -->
   </application>
   

   Możesz też bezpośrednio sprawdzić dostępność potoku i poprosić o pobranie za pomocą interfejsu ModuleInstallClient API w Usługach Google Play.

   Jeśli nie włączysz pobierania potoku podczas instalacji lub nie poprosisz o jawne pobieranie, potok zostanie pobrany przy pierwszym uruchomieniu narzędzia do oznaczania etykietami. Żądania wysłane przed zakończeniem pobierania nie dają żadnych wyników.

4. Jeśli chcesz dynamicznie pobierać model z Firebase, dodaj zależność linkFirebase:

   Aby dynamicznie pobierać model z Firebase, dodaj zależność linkFirebase:

   dependencies {
     // ...
     // Image labeling feature with model downloaded from Firebase
     implementation 'com.google.mlkit:image-labeling-custom:17.0.2'
     // Or use the dynamically downloaded pipeline in Google Play Services
     // implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta5'
     implementation 'com.google.mlkit:linkfirebase:17.0.0'
   }
   

5. Jeśli chcesz pobrać model, dodaj Firebase do swojego projektu na Androida, jeśli jeszcze tego nie zrobiłeś. Nie jest to wymagane podczas pakowania modelu.

1. Wczytywanie modelu

Skonfiguruj źródło modelu lokalnego

Aby połączyć model z aplikacją:

1. Skopiuj plik modelu (zwykle kończący się znakami .tflite lub .lite) do folderu assets/ aplikacji. Być może najpierw trzeba będzie utworzyć folder. Aby to zrobić, kliknij prawym przyciskiem myszy folder app/, a następnie kliknij Nowy > Folder > Folder zasobów.

2. Następnie dodaj do pliku build.gradle swojej aplikacji ten kod, aby Gradle nie kompresowała pliku modelu podczas tworzenia aplikacji:

   android {
       // ...
       aaptOptions {
           noCompress "tflite"
           // or noCompress "lite"
       }
   }
   

   Plik modelu zostanie dołączony do pakietu aplikacji i będzie dostępny dla ML Kit jako nieprzetworzony zasób.

3. Utwórz obiekt LocalModel, podając ścieżkę do pliku modelu:

   Kotlin

   val localModel = LocalModel.Builder()
           .setAssetFilePath("model.tflite")
           // or .setAbsoluteFilePath(absolute file path to model file)
           // or .setUri(URI to model file)
           .build()

   Java

   LocalModel localModel =
       new LocalModel.Builder()
           .setAssetFilePath("model.tflite")
           // or .setAbsoluteFilePath(absolute file path to model file)
           // or .setUri(URI to model file)
           .build();

Skonfiguruj źródło modelu hostowane w Firebase

Aby użyć modelu hostowanego zdalnie, utwórz obiekt RemoteModel przez FirebaseModelSource, podając nazwę przypisaną do modelu podczas jego publikowania:

// Specify the name you assigned in the Firebase console.
val remoteModel =
    CustomRemoteModel
        .Builder(FirebaseModelSource.Builder("your_model_name").build())
        .build()

// Specify the name you assigned in the Firebase console.
CustomRemoteModel remoteModel =
    new CustomRemoteModel
        .Builder(new FirebaseModelSource.Builder("your_model_name").build())
        .build();

Następnie rozpocznij zadanie pobierania modelu, określając warunki, które mają mieć możliwość pobierania. Jeśli modelu nie ma na urządzeniu lub dostępna jest jego nowsza wersja, zadanie pobierze asynchronicznie model z Firebase:

val downloadConditions = DownloadConditions.Builder()
    .requireWifi()
    .build()
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
    .addOnSuccessListener {
        // Success.
    }

DownloadConditions downloadConditions = new DownloadConditions.Builder()
        .requireWifi()
        .build();
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
        .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(@NonNull Task task) {
                // Success.
            }
        });

Wiele aplikacji rozpoczyna zadanie pobierania w kodzie inicjowania, ale możesz to zrobić w dowolnym momencie, zanim zajdzie potrzeba używania modelu.

Konfigurowanie oznaczania obrazów etykietami

Po skonfigurowaniu źródeł modelu utwórz na podstawie jednego z nich obiekt ImageLabeler.

Dostępne są te ustawienia:

Jeśli masz tylko model dołączony do pakietu lokalnie, po prostu utwórz etykietę na podstawie obiektu LocalModel:

val customImageLabelerOptions = CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.5f)
    .setMaxResultCount(5)
    .build()
val labeler = ImageLabeling.getClient(customImageLabelerOptions)

CustomImageLabelerOptions customImageLabelerOptions =
        new CustomImageLabelerOptions.Builder(localModel)
            .setConfidenceThreshold(0.5f)
            .setMaxResultCount(5)
            .build();
ImageLabeler labeler = ImageLabeling.getClient(customImageLabelerOptions);

Jeśli masz model hostowany zdalnie, przed jego uruchomieniem musisz sprawdzić, czy został on pobrany. Stan zadania pobierania modelu możesz sprawdzić za pomocą metody isModelDownloaded() menedżera modeli.

Musisz to potwierdzić przed uruchomieniem osoby oznaczającej etykietami, ale jeśli używasz zarówno modelu hostowanego zdalnie, jak i modelu dołączonego lokalnie, warto wykonać tę procedurę przy tworzeniu wystąpienia osoby oznaczającej obrazy: utwórz etykietę z modelu zdalnego, jeśli został pobrany, lub z modelu lokalnego w innym przypadku.

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
    .addOnSuccessListener { isDownloaded ->
    val optionsBuilder =
        if (isDownloaded) {
            CustomImageLabelerOptions.Builder(remoteModel)
        } else {
            CustomImageLabelerOptions.Builder(localModel)
        }
    val options = optionsBuilder
                  .setConfidenceThreshold(0.5f)
                  .setMaxResultCount(5)
                  .build()
    val labeler = ImageLabeling.getClient(options)
}

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
        .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(Boolean isDownloaded) {
                CustomImageLabelerOptions.Builder optionsBuilder;
                if (isDownloaded) {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(remoteModel);
                } else {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(localModel);
                }
                CustomImageLabelerOptions options = optionsBuilder
                    .setConfidenceThreshold(0.5f)
                    .setMaxResultCount(5)
                    .build();
                ImageLabeler labeler = ImageLabeling.getClient(options);
            }
        });

Jeśli masz tylko model hostowany zdalnie, wyłącz związane z nim funkcje – na przykład wyszarz lub ukryj część interfejsu użytkownika, dopóki nie potwierdzisz, że model został pobrany. Aby to zrobić, dołącz odbiornik do metody download() menedżera modeli:

RemoteModelManager.getInstance().download(remoteModel, conditions)
    .addOnSuccessListener {
        // Download complete. Depending on your app, you could enable the ML
        // feature, or switch from the local model to the remote model, etc.
    }

RemoteModelManager.getInstance().download(remoteModel, conditions)
        .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(Void v) {
              // Download complete. Depending on your app, you could enable
              // the ML feature, or switch from the local model to the remote
              // model, etc.
            }
        });

2. Przygotuj obraz wejściowy

Obiekt InputImage możesz utworzyć z różnych źródeł. Poniżej objaśniamy każde z nich.

Przy użyciu: media.Image

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

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

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

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 używasz biblioteki aparatu, która określa kąt obrotu obrazu, możesz go obliczyć na podstawie obrotów urządzenia i orientacji czujnika aparatu:

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

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 wartości InputImage.fromMediaImage():

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

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

Przy użyciu 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 galerii.

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

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

Przy użyciu: ByteBuffer lub ByteArray

Aby utworzyć obiekt InputImage na podstawie ByteBuffer lub ByteArray, najpierw oblicz stopień obrotu obrazu w sposób opisany wcześniej 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:

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

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

Przy użyciu: Bitmap

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

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

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

Obraz jest reprezentowany przez obiekt Bitmap wraz z stopniami obrotu.

3. Uruchamianie narzędzia do etykietowania obrazów

Aby oznaczyć etykietami obiekty na obrazie, przekaż obiekt image do metody process() metody ImageLabeler.

labeler.process(image)
        .addOnSuccessListener { labels ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }
ImageLabelingActivity.kt

labeler.process(image)
        .addOnSuccessListener(new OnSuccessListener<List<ImageLabel>>() {
            @Override
            public void onSuccess(List<ImageLabel> labels) {
                // Task completed successfully
                // ...
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Task failed with an exception
                // ...
            }
        });
ImageLabelingActivity.java

4. Uzyskaj informacje o elementach oznaczonych etykietami

for (label in labels) {
    val text = label.text
    val confidence = label.confidence
    val index = label.index
}
ImageLabelingActivity.kt

for (ImageLabel label : labels) {
    String text = label.getText();
    float confidence = label.getConfidence();
    int index = label.getIndex();
}
ImageLabelingActivity.java

Wskazówki dotyczące poprawy skuteczności w czasie rzeczywistym

Jeśli chcesz oznaczać etykietami obrazy w aplikacji działającej w czasie rzeczywistym, postępuj zgodnie z tymi wytycznymi, aby uzyskać najlepszą liczbę klatek:

• Jeśli używasz interfejsu API Camera lub camera2, ograniczaj wywołania osoby oznaczającej obrazy. Jeśli w trakcie działania etykiety obrazów pojawi się nowa ramka wideo, upuść ją. Przykład znajdziesz w klasie VisionProcessorBase w przykładowej aplikacji z krótkim wprowadzeniem.
• Jeśli używasz interfejsu API CameraX, sprawdź, czy strategia dotycząca wstecznego obciążenia jest ustawiona na wartość domyślną ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Gwarantuje to, że w danym momencie do analizy będzie przesyłany tylko 1 obraz. Jeśli wtedy, gdy analizator jest zajęty, zostanie utworzonych więcej obrazów, zostaną one automatycznie usunięte i nie zostaną dodane do kolejki do dostarczenia. Po zamknięciu analizowanego obrazu za pomocą wywołania ImageProxy.close() dostarczany jest następny najnowszy obraz.
• Jeśli używasz danych wyjściowych narzędzia do etykietowania obrazów do nałożenia grafiki na obraz wejściowy, najpierw pobierz wynik z pakietu ML Kit, a następnie w jednym kroku wyrenderuj obraz i nakładkę. Wyświetla się ona tylko raz na każdą klatkę wejściową. Przykład znajdziesz w klasach CameraSourcePreview i GraphicOverlay w przykładowej aplikacji krótkiego wprowadzenia.
• Jeśli korzystasz z interfejsu Camera2 API, ró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.