Android'de resimleri özel bir modelle etiketleme

Bir görüntüdeki varlıkları tanımak ve etiketlemek için ML Kit'i kullanabilirsiniz. Bu API, çok çeşitli özel görüntü sınıflandırma modellerini destekler. Model uyumluluğu gereksinimleri, önceden eğitilmiş modellerin nerede bulunduğu ve kendi modellerinizi nasıl eğiteceğiniz hakkında bilgi edinmek için lütfen ML Kit ile özel modeller bölümüne bakın.

Resim etiketlemeyi özel modellerle entegre etmenin iki yolu vardır: ardışık düzeni uygulamanızın bir parçası olarak paketleyerek veya Google Play Hizmetleri'ne dayalı, paketlenmemiş bir ardışık düzen kullanarak. Grup halinde olmayan ardışık düzeni seçerseniz uygulamanız daha küçük olur. Ayrıntılar için aşağıdaki tabloya bakın.

GruplandırılmışGrup halinde olmayanlar
Kitaplık adıcom.google.mlkit:image-labeling-customcom.google.android.gms:play-services-mlkit-image-labeling-custom
UygulamaArdışık düzen, derleme sırasında uygulamanıza statik olarak bağlanır.Ardışık düzen, Google Play Hizmetleri üzerinden dinamik olarak indirilir.
Uygulama boyutuBoyut artışı yaklaşık 3,8 MB.Boyutu yaklaşık 200 KB artışı.
Başlatma süresiArdışık düzen hemen kullanılabilir.İlk kullanımdan önce ardışık düzenin indirilmesini beklemek gerekebilir.
API yaşam döngüsü aşamasıGenel Kullanım (GA)Beta

Özel bir modeli iki şekilde entegre edebilirsiniz: Modeli uygulamanızın öğe klasörüne yerleştirerek paketleyin veya Firebase'den dinamik olarak indirin. Aşağıdaki tabloda bu iki seçenek karşılaştırılmaktadır.

Gruplandırılmış Model Barındırılan Model
Model, uygulamanızın APK'sının bir parçası olduğundan boyutunu artırır. Model, APK'nızın bir parçası değil. Firebase Makine Öğrenimi'ne yüklenerek barındırılır.
Model, Android cihaz çevrimdışı olsa bile hemen kullanılabilir Model istek üzerine indirilir
Firebase projesine gerek yoktur Firebase projesi gereklidir
Modeli güncellemek için uygulamanızı yeniden yayınlamanız gerekir Uygulamanızı yeniden yayınlamadan model güncellemelerini aktarın
Yerleşik A/B testi yok Firebase Remote Config ile kolay A/B testi

Deneyin

Başlamadan önce

  1. Proje düzeyindeki build.gradle dosyanıza hem buildscript hem de allprojects bölümlerinize Google'ın Maven deposunu eklediğinizden emin olun.

  2. ML Kit Android kitaplıklarının bağımlılıklarını, modülünüzün uygulama düzeyindeki Gradle dosyasına (genellikle app/build.gradle dosyasıdır) ekleyin. İhtiyaçlarınıza göre aşağıdaki bağımlılıklardan birini seçin:

    Ardışık düzeni uygulamanızla paket haline getirmek için:

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

    Google Play Hizmetleri'nde ardışık düzeni kullanmak için:

    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. Google Play Hizmetleri'nde ardışık düzeni kullanmayı seçerseniz uygulamanızı, Play Store'dan yüklendikten sonra ardışık düzeni cihaza otomatik olarak indirecek şekilde yapılandırabilirsiniz. Bunu yapmak için uygulamanızın AndroidManifest.xml dosyasına aşağıdaki beyanı ekleyin:

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

    Ayrıca, ardışık düzen kullanılabilirliğini açıkça kontrol edebilir ve Google Play hizmetleri ModuleInstallClient API üzerinden indirme isteğinde bulunabilirsiniz.

    Yükleme zamanı ardışık düzen indirmelerini etkinleştirmezseniz veya açıkça indirme isteğinde bulunmazsanız etiketleyiciyi ilk kez çalıştırdığınızda ardışık düzen indirilir. İndirme işlemi tamamlanmadan önce gönderdiğiniz istekler hiçbir sonuç vermez.

  4. Firebase'den dinamik olarak bir model indirmek istiyorsanız linkFirebase bağımlılığını ekleyin:

    Bir modeli Firebase'den dinamik olarak indirmek için linkFirebase bağımlılığını ekleyin:

    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. Bir model indirmek istiyorsanız henüz yapmadıysanız Firebase'i Android projenize eklediğinizden emin olun. Modeli paketlediğinizde bu gerekli değildir.

1. Modeli yükleme

Yerel model kaynağını yapılandırma

Modeli uygulamanızla birlikte gruplandırmak için:

  1. Model dosyasını (genellikle .tflite veya .lite ile biter) uygulamanızın assets/ klasörüne kopyalayın. (Önce app/ klasörünü sağ tıklayıp ardından Yeni > Klasör > Öğeler Klasörü'nü tıklayarak klasörü oluşturmanız gerekebilir.)

  2. Ardından, Gradle'ın uygulamayı oluştururken model dosyasını sıkıştırmadığından emin olmak için aşağıdakileri uygulamanızın build.gradle dosyasına ekleyin:

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

    Model dosyası, uygulama paketine dahil edilir ve ML Kit'in kullanımına ham öğe olarak eklenir.

  3. Model dosyasının yolunu belirterek LocalModel nesnesi oluşturun:

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

Firebase tarafından barındırılan bir model kaynağını yapılandırma

Uzaktan barındırılan modeli kullanmak için FirebaseModelSource ile bir RemoteModel nesnesi oluşturun ve modeli yayınlarken atadığınız adı belirtin:

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

Ardından, indirme işlemine izin vermek istediğiniz koşulları belirterek model indirme görevini başlatın. Model cihazda yoksa veya modelin daha yeni bir sürümü varsa görev, modeli Firebase'den eşzamansız olarak indirir:

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

Birçok uygulama, indirme görevini başlatma kodunda başlatır ancak modeli kullanmanız gerekmeden istediğiniz zaman bu işlemi gerçekleştirebilirsiniz.

Resim etiketleyiciyi yapılandırma

Model kaynaklarınızı yapılandırdıktan sonra, bunlardan bir ImageLabeler nesnesi oluşturun.

Aşağıdaki seçenekler kullanılabilir:

Seçenekler
confidenceThreshold

Algılanan etiketlerin minimum güven puanı. Ayarlanmazsa modelin meta verileri tarafından belirtilen herhangi bir sınıflandırıcı eşiği kullanılır. Model herhangi bir meta veri içermiyorsa veya meta veriler bir sınıflandırıcı eşiği belirtmiyorsa varsayılan eşik olan 0, 0 kullanılır.

maxResultCount

Döndürülecek maksimum etiket sayısı. Ayarlanmazsa varsayılan değer olan 10 kullanılır.

Yalnızca yerel olarak paketlenmiş bir modeliniz varsa LocalModel nesnenizden bir etiketleyici oluşturmanız yeterlidir:

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

Uzaktan barındırılan bir modeliniz varsa çalıştırmadan önce modelin indirilip indirilmediğini kontrol etmeniz gerekir. Model yöneticisinin isModelDownloaded() yöntemini kullanarak model indirme görevinin durumunu kontrol edebilirsiniz.

Etiketleyiciyi çalıştırmadan önce bunu doğrulamanız gerekse de hem uzaktan barındırılan bir modeliniz hem de yerel olarak paketlenmiş bir modeliniz varsa görüntü etiketleyiciyi örneklendirmek için bu kontrolün yapılması mantıklı olabilir: İndirilmişse uzak modelden, aksi takdirde yerel modelden bir etiketleyici oluşturun.

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

Yalnızca uzaktan barındırılan bir modeliniz varsa modelin indirildiğini onaylayana kadar modelle ilgili işlevleri (örneğin, devre dışı bırakma veya kullanıcı arayüzünüzün bir bölümünü gizleme) devre dışı bırakmanız gerekir. Bunu, model yöneticisinin download() yöntemine işleyici ekleyerek yapabilirsiniz:

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. Giriş görüntüsünü hazırlama

Ardından, etiketlemek istediğiniz her görüntü için resminizden bir InputImage nesnesi oluşturun. Görüntü etiketleyici, Bitmap veya Camera2 API'si kullanıyorsanız YUV_420_888 media.Image (mümkünse önerilir.) kullandığınızda en hızlı şekilde çalışır.

Farklı kaynaklardan bir InputImage nesnesi oluşturabilirsiniz. Her biri aşağıda açıklanmıştır.

media.Image kullanma

media.Image nesnesinden InputImage nesnesi oluşturmak için (örneğin, bir cihazın kamerasından görüntü yakaladığınızda) media.Image nesnesini ve resmin dönüşünü InputImage.fromMediaImage() parametresine geçirin.

KameraX kitaplığını kullanırsanız OnImageCapturedListener ve ImageAnalysis.Analyzer sınıfları, rotasyon değerini sizin için hesaplar.

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

Resmin dönüş derecesini veren bir kamera kitaplığı kullanmıyorsanız bunu cihazın dönüş derecesinden ve cihazdaki kamera sensörünün yönüne göre hesaplayabilirsiniz:

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

Daha sonra, media.Image nesnesini ve döndürme derecesi değerini InputImage.fromMediaImage() öğesine geçirin:

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)

Java

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

Dosya URI'si kullanma

Dosya URI'sinden bir InputImage nesnesi oluşturmak için uygulama bağlamını ve dosya URI'sini InputImage.fromFilePath() öğesine iletin. Bu, kullanıcıdan galeri uygulamasından bir resim seçmesini istemek için bir ACTION_GET_CONTENT amacı kullandığınızda faydalıdır.

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

ByteBuffer veya ByteArray kullanma

ByteBuffer veya ByteArray kaynağından InputImage nesnesi oluşturmak için önce resim döndürme derecesini, daha önce media.Image girişi için açıklandığı gibi hesaplayın. Ardından, resmin yüksekliği, genişliği, renk kodlama biçimi ve döndürme derecesiyle birlikte arabellek veya diziyi içeren InputImage nesnesini oluşturun:

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

Bitmap kullanma

Bitmap nesnesinden InputImage nesnesi oluşturmak için aşağıdaki beyanı yapın:

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)

Java

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

Resim, döndürme dereceleriyle birlikte bir Bitmap nesnesiyle temsil edilir.

3. Görüntü etiketleyiciyi çalıştırma

Bir görüntüdeki nesneleri etiketlemek için image nesnesini ImageLabeler process() yöntemine geçirin.

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. Etiketli varlıklar hakkında bilgi edinme

Görüntü etiketleme işlemi başarılı olursa başarılı işleyiciye ImageLabel nesne listesi iletilir. Her ImageLabel nesnesi, resimde etiketlenmiş bir öğeyi temsil eder. Her etiketin metin açıklamasını (TensorFlow Lite model dosyasının meta verilerinde varsa), güven puanını ve dizini alabilirsiniz. Örneğin:

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

Gerçek zamanlı performansı iyileştirmeye yönelik ipuçları

Resimleri gerçek zamanlı bir uygulamada etiketlemek istiyorsanız en iyi kare hızlarını elde etmek için şu yönergeleri uygulayın:

  • Camera veya camera2 API kullanıyorsanız görüntü etiketleyiciye yapılan çağrıları kısıtlayın. Resim etiketleyici çalışırken yeni bir video karesi kullanılabilir hale gelirse kareyi bırakın. Örnek için hızlı başlangıç örnek uygulamasındaki VisionProcessorBase sınıfına bakın.
  • CameraX API'yi kullanıyorsanız geri basınç stratejisinin varsayılan değere ( ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST) ayarlandığından emin olun. Bu, analiz için tek seferde yalnızca bir resmin teslim edileceğini garanti eder. Analiz aracı meşgulken daha fazla görüntü oluşturulursa bu resimler otomatik olarak bırakılır ve gönderim için sıraya alınmaz. Analiz edilen resim, ImageProxy.close() çağrısı yapılarak kapatıldıktan sonra bir sonraki en son resim gönderilir.
  • Görüntü etiketleyicinin çıktısını kullanarak giriş görüntüsünün üzerine grafik bindirirseniz önce ML Kit'ten sonucu alın, ardından görüntüyü oluşturun ve tek bir adımda yer paylaşımlı yapın. Bu işlem, her giriş karesi için görüntü yüzeyinde yalnızca bir kez oluşturulur. Örnek için hızlı başlangıç örnek uygulamasındaki CameraSourcePreview ve GraphicOverlay sınıflarına bakın.
  • Camera2 API'yi kullanıyorsanız görüntüleri ImageFormat.YUV_420_888 biçiminde yakalayın. Eski Camera API'yi kullanıyorsanız görüntüleri ImageFormat.NV21 biçiminde yakalayın.