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

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Możesz używać ML Kit do rozpoznawania encji na obrazie i oznaczania ich etykietami. Ten interfejs API obsługuje szeroką gamę niestandardowych modeli klasyfikacji obrazów. Na stronie Modele niestandardowe z pakietem ML Kit znajdziesz wskazówki dotyczące zgodności modeli, miejsca wytrenowania modeli i trenowania własnych modeli.

Istnieją 2 sposoby integracji etykiet obrazów z modelami niestandardowymi: można połączyć potok w ramach aplikacji lub skorzystać z niepołączonego potoku zależnego od Usług Google Play. Jeśli wybierzesz niepogrupowany potok, aplikacja będzie mniejsza. Szczegółowe informacje znajdziesz w poniższej tabeli.

Łączenie w pakietyNiegrupowane
Nazwa bibliotekicom.google.mlkit:image-labeling-customcom.google.android.gms:play-services-mlkit-image-labeling-custom
WdrażaniePotok jest statycznie powiązany z aplikacją w momencie kompilacji.Potok jest pobierany dynamicznie przez Usługi Google Play.
Rozmiar aplikacjiZwiększenie rozmiaru o około 3,8 MB.Zwiększenie rozmiaru o około 200 KB.
Czas inicjowaniaPotok jest dostępny od razu.Może minąć trochę czasu, zanim potok zostanie pobrany.
Etap cyklu życia interfejsu APIOgólna dostępność (GA)Beta

Są 2 sposoby integracji modelu niestandardowego: pogrupuj model, umieszczając go w folderze zasobów aplikacji, lub dynamicznie pobierz go z Firebase. Poniższa tabela zawiera porównanie tych 2 opcji.

Połączony model Model hostowany
Model jest częścią pakietu APK aplikacji, który zwiększa jego rozmiar. Model nie jest częścią pakietu APK. Jest ona hostowana przez przesłanie danych do systemów uczących się Firebase.
Model jest dostępny od razu, nawet wtedy, gdy urządzenie z Androidem jest offline Model jest pobierany na żądanie
Nie potrzebuję projektu Firebase Wymaga projektu Firebase
Aby zaktualizować model, musisz ponownie opublikować aplikację Przekazywanie aktualizacji modelu bez ponownego publikowania aplikacji
Brak wbudowanych testów A/B Łatwe testowanie A/B za pomocą Zdalnej konfiguracji Firebase

Wypróbuj

Zanim zaczniesz

  1. W pliku build.gradle na poziomie projektu umieść repozytorium Google Maven w sekcjach buildscript i allprojects.

  2. Dodaj zależności bibliotek ML Kit na Androida do pliku Gradle na poziomie aplikacji, który zwykle wynosi app/build.gradle. Wybierz jedną z tych zależności w zależności od potrzeb:

    Aby połączyć pakiet z aplikacją:

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

    Aby użyć 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-beta4'
    }
    
  3. Jeśli zdecydujesz się używać potoku w Usługach Google Play, możesz skonfigurować aplikację tak, aby automatycznie pobierała ją na urządzenie po zainstalowaniu jej 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="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 go za pomocą interfejsu ModuleInstallClient API w Usługach Google Play.

    Jeśli nie włączysz pobierania potoku w czasie instalacji lub nie poprosisz o bezpośrednie pobieranie, potok zostanie pobrany przy pierwszym uruchomieniu etykiety. Wysyłanie żądań, które zakończyły się, zanim wyniki zostały ukończone, nie zwraca ż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.1'
      // Or use the dynamically downloaded pipeline in Google Play Services
      // implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta4'
      implementation 'com.google.mlkit:linkfirebase:17.0.0'
    }
    
  5. Jeśli chcesz pobrać model, dodaj Firebase do swojego projektu na Androida, jeśli jeszcze go nie masz. Nie jest to wymagane w pakiecie modelu.

1. Wczytaj model

Skonfiguruj źródło modelu lokalnego

Aby połączyć model z aplikacją:

  1. Skopiuj plik z modelem (kończący się zwykle na .tflite lub .lite) do folderu assets/ aplikacji. Możliwe, że trzeba będzie najpierw utworzyć folder, klikając prawym przyciskiem folder app/, a następnie klikając Nowy > Folder > Folder zasobów.

  2. Następnie dodaj te elementy do pliku build.gradle aplikacji, aby sprawdzić, czy Gradle nie kompresuje pliku modelu podczas jej tworzenia:

    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 hostowanego w Firebase

Aby używać modelu hostowanego zdalnie, utwórz obiekt RemoteModel przez usługę FirebaseModelSource, określając nazwę przypisaną do niego podczas publikowania:

Kotlin

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

Java

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

Następnie uruchom zadanie pobierania modelu, określając warunki, które mają umożliwiać pobieranie. Jeśli modelu nie ma na urządzeniu lub jest dostępna jego nowsza wersja, zadanie asynchronicznie pobierze go z Firebase:

Kotlin

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

Java

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 pobieranie w kodzie inicjowania, ale w dowolnym momencie możesz użyć modelu.

Konfigurowanie etykiet obrazów

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

Dostępne są te opcje:

Opcje
confidenceThreshold

Minimalny wskaźnik ufności wykrytych etykiet. Jeśli jej nie skonfigurujesz, używany będzie próg klasyfikatora określony przez metadane modelu. Jeśli model nie zawiera żadnych metadanych lub nie określa progu klasyfikatora, zostanie użyty domyślny próg 0,0.

maxResultCount

Maksymalna liczba etykiet do zwrócenia. Jeśli zasada nie została skonfigurowana, używana jest wartość domyślna, czyli 10.

Jeśli masz tylko model połączony lokalnie, utwórz etykietę z obiektu LocalModel:

Kotlin

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

Java

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ć, korzystając z metody isModelDownloaded() w menedżerze modeli.

Choć musisz tylko potwierdzić te informacje przed uruchomieniem modułu do oznaczania etykietami, jeśli masz model hostowany zdalnie i lokalnie dołączony, możesz spróbować sprawdzić to podczas tworzenia instancji etykiety obrazu: utwórz etykietę z modelu zdalnego (jeśli została pobrana) oraz z modelu lokalnego.

Kotlin

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

Java

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 funkcje związane z modelem, takie jak wyszarzony lub ukryty w interfejsie, dopóki nie potwierdzisz, że model został pobrany. Aby to zrobić, dołącz odbiornik do metody download() menedżera modeli:

Kotlin

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

Java

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

Następnie dla każdego obrazu, który chcesz oznaczyć etykietą, utwórz obiekt InputImage z obrazu. Etykieta obrazu działa najszybciej, gdy używasz interfejsu Bitmap lub interfejsu API aparatu2, np. YUV_420_888media.Image, które są zalecane, o ile jest to możliwe.

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

Korzystanie z: 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 InputImage.fromMediaImage().

Jeśli używasz biblioteki Aparat X, klasy OnImageCapturedListener i ImageAnalysis.Analyzer obliczają 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 używasz biblioteki zdjęć, która zapewnia kąt obrotu zdjęcia, możesz obliczyć ją na podstawie stopnia obrotu urządzenia i orientacji czujnika aparatu w urządzeniu.

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ść stopni obrotu do InputImage.fromMediaImage():

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)

Java

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

Używanie identyfikatora URI pliku

Aby utworzyć obiekt InputImage z identyfikatora URI pliku, przekaż kontekst aplikacji i identyfikator URI pliku do InputImage.fromFilePath(). Jest to przydatne, gdy użyjesz intencji ACTION_GET_CONTENT, aby poprosić użytkownika o wybranie obrazu z 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();
}

Korzystanie z ByteBuffer lub ByteArray

Aby utworzyć obiekt InputImage z ByteBuffer lub ByteArray, najpierw oblicz stopień obrotu obrazu, jak opisano wcześniej w przypadku danych wejściowych media.Image. Następnie utwórz obiekt InputImage z buforem lub tablicą wraz z wysokością, szerokością, formatem kolorów i stopniem rotacji:

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

Korzystanie z: 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 wraz ze stopniami obrotu.

3. Uruchamianie etykietowania obrazów

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

Kotlin

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

Java

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

4. Uzyskaj informacje o elementach oznaczonych etykietami

Jeśli operacja dodawania etykiet do obrazu zakończy się powodzeniem, do odbiornika zostanie przekazana lista ImageLabel obiektów. Każdy obiekt ImageLabel reprezentuje element oznaczony etykietą na obrazie. Możesz pobrać opis każdej etykiety (jeśli jest dostępna w metadanych pliku modelu TensorFlow Lite), wskaźnik ufności i indeks. Przykład:

Kotlin

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

Java

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

Wskazówki dotyczące zwiększania skuteczności w czasie rzeczywistym

Jeśli chcesz dodawać etykiety do obrazów w aplikacji w czasie rzeczywistym, postępuj zgodnie z tymi wskazówkami, aby uzyskać najlepszą liczbę klatek:

  • Jeśli używasz interfejsu API Camera lub camera2, ograniczaj wywołania do etykiet obrazów. Jeśli w trakcie działania etykiety filmu będzie dostępna nowa ramka, puść ją. Przykład znajdziesz w klasie VisionProcessorBase w przykładowej aplikacji krótkiego wprowadzenia.
  • Jeśli korzystasz z interfejsu API CameraX, sprawdź, czy strategia pushpress ma ustawioną wartość domyślną ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Gwarantuje to, że w danym momencie do analizy zostanie wysłany tylko 1 obraz. Jeśli analizator jest zajęty, więcej obrazów jest usuwanych, a następnie usuwanych automatycznie i nie znajdujących się w kolejce w celu dostarczenia. Gdy analizowany obraz zostanie zamknięty, wywołany jest obiekt ImageProxy.close(). Pojawi się następny obraz.
  • Jeśli używasz danych wyjściowych etykiety obrazu w celu nakładania grafiki na obraz wejściowy, najpierw pobierz wynik z ML Kit, a następnie wyrenderuj obraz i nakładkę w jednym kroku. Renderuje się na wyświetlaczu tylko raz dla każdej klatki wejściowej. Przykład znajdziesz w klasach CameraSourcePreview i GraphicOverlay w przykładowej aplikacji krótkiego wprowadzenia.
  • Jeśli używasz interfejsu Camera2 API, zrób zdjęcia w formacie ImageFormat.YUV_420_888. Jeśli używasz starszego interfejsu API aparatu, zrób zdjęcia w formacie ImageFormat.NV21.