Android'de özel bir sınıflandırma modeliyle nesneleri algılama, izleme ve sınıflandırma

Bir görüntüyü ML Kit'e ilettiğinizde bu cihaz, görüntüdeki her nesnenin konumuyla birlikte görüntüde beşe kadar nesne algılar. Video akışlarında nesneleri algılarken her nesnenin benzersiz bir kimliği vardır. Bu kimliği, nesneyi kareden kareye izlemek için kullanabilirsiniz.

Algılanan nesneleri sınıflandırmak için özel bir görüntü sınıflandırma modeli kullanabilirsiniz. Model uyumluluğu gereksinimleri, önceden eğitilmiş modellerin nerede bulunduğu ve kendi modellerinizi nasıl eğiteceğiniz hakkında yardım almak için lütfen ML Kit ile özel modeller bölümüne bakın.

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

Deneyin

• Paketlenmiş modelin örnek kullanımı için vision hızlı başlangıç uygulamasına ve barındırılan modelin örnek kullanımı için automl hızlı başlangıç uygulamasına göz atın.
• Bu API'nin uçtan uca uygulanması için Materyal Tasarım vitrin uygulamasına bakın.

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 ekleyin. Bu dosya genellikle app/build.gradle olur:

   Uygulamanızla bir model paketi sunmak için:

   dependencies {
     // ...
     // Object detection & tracking feature with custom bundled model
     implementation 'com.google.mlkit:object-detection-custom:17.0.1'
   }
   

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

   dependencies {
     // ...
     // Object detection & tracking feature with model downloaded
     // from firebase
     implementation 'com.google.mlkit:object-detection-custom:17.0.1'
     implementation 'com.google.mlkit:linkfirebase:17.0.0'
   }
   

3. 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 CustomRemoteModel nesnesi oluşturun ve modeli yayınlarken atadığınız adı belirtin:

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

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:

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

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.

2. Nesne algılayıcısını yapılandırın

Model kaynaklarınızı yapılandırdıktan sonra, bir CustomObjectDetectorOptions nesnesi kullanarak kullanım alanınız için nesne algılayıcıyı yapılandırın. Aşağıdaki ayarları değiştirebilirsiniz:

Nesne algılama ve izleme API'si aşağıdaki iki temel kullanım alanı için optimize edilmiştir:

• Kamera vizöründeki en belirgin nesnenin canlı olarak algılanması ve izlenmesi.
• Statik bir görüntüden birden fazla nesnenin algılanması.

API'yi bu kullanım alanları için yerel olarak paket haline getirilmiş bir modelle yapılandırmak için:

// Live detection and tracking
val customObjectDetectorOptions =
        CustomObjectDetectorOptions.Builder(localModel)
        .setDetectorMode(CustomObjectDetectorOptions.STREAM_MODE)
        .enableClassification()
        .setClassificationConfidenceThreshold(0.5f)
        .setMaxPerObjectLabelCount(3)
        .build()

// Multiple object detection in static images
val customObjectDetectorOptions =
        CustomObjectDetectorOptions.Builder(localModel)
        .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
        .enableMultipleObjects()
        .enableClassification()
        .setClassificationConfidenceThreshold(0.5f)
        .setMaxPerObjectLabelCount(3)
        .build()

val objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions)

// Live detection and tracking
CustomObjectDetectorOptions customObjectDetectorOptions =
        new CustomObjectDetectorOptions.Builder(localModel)
                .setDetectorMode(CustomObjectDetectorOptions.STREAM_MODE)
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();

// Multiple object detection in static images
CustomObjectDetectorOptions customObjectDetectorOptions =
        new CustomObjectDetectorOptions.Builder(localModel)
                .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableMultipleObjects()
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();

ObjectDetector objectDetector =
    ObjectDetection.getClient(customObjectDetectorOptions);

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.

Algılayıcıyı ç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ü algılayıcıyı örneklendirmek için bu kontrolün yapılması mantıklı olabilir: İndirilmişse uzak modelden, aksi takdirde yerel modelden bir algılayıcı oluşturun.

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
    .addOnSuccessListener { isDownloaded ->
    val optionsBuilder =
        if (isDownloaded) {
            CustomObjectDetectorOptions.Builder(remoteModel)
        } else {
            CustomObjectDetectorOptions.Builder(localModel)
        }
    val customObjectDetectorOptions = optionsBuilder
            .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
            .enableClassification()
            .setClassificationConfidenceThreshold(0.5f)
            .setMaxPerObjectLabelCount(3)
            .build()
    val objectDetector =
        ObjectDetection.getClient(customObjectDetectorOptions)
}

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
    .addOnSuccessListener(new OnSuccessListener() {
        @Override
        public void onSuccess(Boolean isDownloaded) {
            CustomObjectDetectorOptions.Builder optionsBuilder;
            if (isDownloaded) {
                optionsBuilder = new CustomObjectDetectorOptions.Builder(remoteModel);
            } else {
                optionsBuilder = new CustomObjectDetectorOptions.Builder(localModel);
            }
            CustomObjectDetectorOptions customObjectDetectorOptions = optionsBuilder
                .setDetectorMode(CustomObjectDetectorOptions.SINGLE_IMAGE_MODE)
                .enableClassification()
                .setClassificationConfidenceThreshold(0.5f)
                .setMaxPerObjectLabelCount(3)
                .build();
            ObjectDetector objectDetector =
                ObjectDetection.getClient(customObjectDetectorOptions);
        }
});

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:

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

3. Giriş görüntüsünü hazırlama

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.

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

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:

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

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

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

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.

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

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:

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

Bitmap kullanma

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

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

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

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

4. Nesne algılayıcıyı çalıştırın

objectDetector
    .process(image)
    .addOnFailureListener(e -> {...})
    .addOnSuccessListener(results -> {
        for (detectedObject in results) {
          // ...
        }
    });

objectDetector
    .process(image)
    .addOnFailureListener(e -> {...})
    .addOnSuccessListener(results -> {
        for (DetectedObject detectedObject : results) {
          // ...
        }
    });

5. Etiketli nesneler hakkında bilgi alma

process() çağrısı başarılı olursa başarılı dinleyiciye bir DetectedObject listesi iletilir.

Her DetectedObject aşağıdaki özellikleri içerir:

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (detectedObject in results) {
    val boundingBox = detectedObject.boundingBox
    val trackingId = detectedObject.trackingId
    for (label in detectedObject.labels) {
      val text = label.text
      val index = label.index
      val confidence = label.confidence
    }
}

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (DetectedObject detectedObject : results) {
  Rect boundingBox = detectedObject.getBoundingBox();
  Integer trackingId = detectedObject.getTrackingId();
  for (Label label : detectedObject.getLabels()) {
    String text = label.getText();
    int index = label.getIndex();
    float confidence = label.getConfidence();
  }
}

Mükemmel bir kullanıcı deneyimi sağlama

En iyi kullanıcı deneyimi için uygulamanızda aşağıdaki yönergeleri uygulayın:

• Nesnenin başarılı bir şekilde algılanması, nesnenin görsel karmaşıklığına bağlıdır. Az sayıda görsel özelliğe sahip nesnelerin algılanmaları için resmin daha büyük bir bölümünü kaplamaları gerekebilir. Kullanıcılara, algılamak istediğiniz nesne türlerinde iyi çalışan girdileri yakalama konusunda yol göstermeniz gerekir.
• Sınıflandırma kullanırken, desteklenen kategorilere düzgün bir şekilde girmeyen nesneleri algılamak isterseniz bilinmeyen nesneler için özel işlem uygulayın.

Ayrıca, ML Kiti Materyal Tasarım vitrin uygulamasına ve Materyal Tasarım Makine öğrenimi destekli özellikler için kalıplar koleksiyonuna göz atın.

Performansı artırma

• Çoğu cihaz yeterli kare hızı üretemeyeceğinden gerçek zamanlı bir uygulamada akış modunu kullanırken birden fazla nesne algılamayı kullanmayın.

• Camera veya camera2 API kullanıyorsanız algılayıcıya yapılan çağrıları kısıtlayın. Algılayıcı ç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.
• Algılayıcının çıkışını giriş görüntüsünün üzerine grafik yerleştirmek için kullanırsanız önce sonucu ML Kit'ten alın, ardından görüntüyü tek bir adımda oluşturun ve 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.