Android'de ML Kit ile nesneleri algılama ve izleme

ML Kit'i kullanarak art arda gelen video karelerindeki nesneleri algılayıp izleyebilirsiniz.

ML Kit'e bir resim gönderdiğinizde, görüntüdeki her nesnenin konumu ile birlikte görüntüde en fazla beş nesneyi algılar. Video akışlarında nesneleri algılarken her nesnenin, kareden kareye nesneyi izlemek için kullanabileceğiniz benzersiz bir kimliği vardır. İsteğe bağlı olarak, nesneleri geniş kategori açıklamalarıyla etiketleyen kaba nesne sınıflandırmasını da etkinleştirebilirsiniz.

Bu API, kullanılmadan önce indirilmesi gereken paketlenmemiş bir kitaplık kullanır. Daha fazla bilgi için bu kılavuza bakın.

Deneyin

• Bu API'nin örnek kullanımını görmek için örnek uygulamayı inceleyin.
• Bu API'nin uçtan uca uygulanması için Material Design showcase uygulamasına bakın.

Başlamadan önce

Bu API için Android API düzeyi 21 veya üzeri gerekir. Uygulamanızın derleme dosyasında minSdkVersion değerinin 21 veya daha yüksek olduğundan emin olun.

1. Proje düzeyindeki build.gradle dosyanızda, Google'ın Maven deposunu hem buildscript hem de allprojects bölümünüze eklediğinizden emin olun.
2. ML Kit Android kitaplıklarının bağımlılıkları, modülünüzün uygulama düzeyindeki Gradle dosyasına (genellikle app/build.gradle) eklenmelidir:

   dependencies {
     // ...
   
     implementation 'com.google.mlkit:object-detection:17.0.2'
   
   }

1. Nesne algılayıcıyı yapılandırma

Nesneleri algılamak ve izlemek için önce bir ObjectDetector örneği oluşturun ve isteğe bağlı olarak varsayılan ayarlardan değiştirmek istediğiniz tüm dedektör ayarlarını belirtin.

1. Nesne algılayıcıyı kullanım alanınız için bir ObjectDetectorOptions nesnesi ile yapılandırın. Aşağıdaki ayarları değiştirebilirsiniz:

   Nesne Algılayıcı Ayarları
   Algılama modu	STREAM_MODE (varsayılan) | SINGLE_IMAGE_MODE STREAM_MODE (varsayılan) değerinde, nesne algılayıcı düşük gecikmeli olarak çalışır ancak algılayıcının ilk birkaç çağrısında eksik sonuçlar (ör. belirtilmemiş sınırlayıcı kutular veya kategori etiketleri) verebilir. Ayrıca STREAM_MODE'te algılayıcı, nesnelere izleme kimlikleri atar. Bu kimlikleri, nesneleri kareler arasında izlemek için kullanabilirsiniz. Nesneleri izlemek istediğinizde veya düşük gecikmenin önemli olduğu durumlarda (ör. video akışlarını gerçek zamanlı olarak işlerken) bu modu kullanın. SINGLE_IMAGE_MODE işlevinde nesne algılayıcı, nesnenin sınırlayıcı kutusu belirlendikten sonra sonucu döndürür. Sınıflandırmayı da etkinleştirirseniz sonuç, sınırlayıcı kutu ve kategori etiketi mevcut olduktan sonra döndürülür. Bunun sonucunda, algılama gecikmesi muhtemelen daha yüksektir. Ayrıca SINGLE_IMAGE_MODE'te izleme kimlikleri atanmaz. Gecikme kritik değilse ve kısmi sonuçlarla uğraşmak istemiyorsanız bu modu kullanın.
   Birden fazla nesneyi algılama ve izleme	false (varsayılan) | true Beş adede kadar nesnenin mi yoksa yalnızca en belirgin nesnenin mi algılanıp izleneceğini belirler (varsayılan).
   Nesneleri sınıflandırma	false (varsayılan) | true Algılanan nesnelerin kaba kategorilere sınıflandırılıp sınıflandırılmayacağı. Nesne algılayıcı etkinleştirildiğinde nesneleri aşağıdaki kategorilere sınıflandırır: moda ürünleri, gıda, ev ürünleri, yerler ve bitkiler.

   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ı algılanması ve izlenmesi.
   • Statik bir resimde birden fazla nesnenin algılanması.

   API'yi bu kullanım alanları için yapılandırmak üzere:

   Kotlin

   // Live detection and tracking
   val options = ObjectDetectorOptions.Builder()
           .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
           .enableClassification()  // Optional
           .build()
   
   // Multiple object detection in static images
   val options = ObjectDetectorOptions.Builder()
           .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
           .enableMultipleObjects()
           .enableClassification()  // Optional
           .build()

   Java

   // Live detection and tracking
   ObjectDetectorOptions options =
           new ObjectDetectorOptions.Builder()
                   .setDetectorMode(ObjectDetectorOptions.STREAM_MODE)
                   .enableClassification()  // Optional
                   .build();
   
   // Multiple object detection in static images
   ObjectDetectorOptions options =
           new ObjectDetectorOptions.Builder()
                   .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
                   .enableMultipleObjects()
                   .enableClassification()  // Optional
                   .build();

2. ObjectDetector örneğini alın:

   Kotlin

   val objectDetector = ObjectDetection.getClient(options)

   Java

   ObjectDetector objectDetector = ObjectDetection.getClient(options);

2. Giriş resmini hazırlama

Nesneleri algılamak ve izlemek için resimleri ObjectDetectorörneğinin process() yöntemine iletin.

Nesne algılayıcı doğrudan Bitmap, NV21 ByteBuffer veya YUV_420_888 media.Image üzerinden çalışır. Bunlardan birine doğrudan erişiminiz varsa bu kaynaklardan InputImage oluşturmanız önerilir. Diğer kaynaklardan bir InputImage oluşturursanız dönüşümü sizin için dahili olarak biz yönetiriz ve bu işlem daha az verimli olabilir.

Bir sekanstaki her video veya resim karesi için aşağıdakileri yapın:

Farklı kaynaklardan InputImage nesnesi oluşturabilirsiniz. Bunların her biri aşağıda açıklanmıştır.

media.Image kullanma

Bir media.Image nesnesinden InputImage nesnesi oluşturmak için (ör. bir cihazın kamerasından resim çekerken) media.Image nesnesini ve resmin dönme açısını InputImage.fromMediaImage()'e iletin.

CameraX kitaplığını kullanıyorsanı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önme derecesini gösteren bir kamera kitaplığı kullanmıyorsanız bunu cihazın dönme derecesinden ve cihazdaki kamera sensörünün yöneliminden 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
}
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;
}

Ardından, media.Image nesnesini ve dönüş derecesi değerini InputImage.fromMediaImage()'e iletin:

Kotlin

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

Java

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

Dosya URI'si kullanma

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

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

ByteBuffer veya ByteArray kullanma

ByteBuffer veya ByteArray öğesinden InputImage nesnesi oluşturmak için önce media.Image girişi için daha önce açıklandığı gibi görüntünün döndürme derecesini hesaplayın. Ardından, resmin yüksekliği, genişliği, renk kodlama biçimi ve döndürme derecesiyle birlikte arabelleği veya diziyi kullanarak 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
)
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

Bitmap kullanma

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

Kotlin

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

Java

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

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

3. Resmi işleme

Resmi process() yöntemine iletin:

Kotlin

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

Java

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

Not: CameraX API'yi kullanıyorsanız kullanmayı bitirdiğinizde ImageProxy'i kapattığınızdan emin olun (ör. process yönteminden döndürülen Task'e bir OnCompleteListener ekleyerek). Örnek için hızlı başlangıç kılavuzundaki VisionProcessorBase sınıfına bakın.

4. Algılanan nesneler hakkında bilgi alma

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

Not: Akış modunda, nesne algılayıcının ilk nesneyi algılamadan önce cihaz performansına bağlı olarak 30 veya daha fazla kare işlemesi gerekebilir.

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

Sınırlayıcı kutu	Nesnenin resimdeki konumunu belirten bir Rect.
İzleme Kimliği	Nesneyi resimlerde tanımlayan bir tam sayı. SINGLE_IMAGE_MODE'da null.
Etiketler	Etiket açıklaması Etiketin metin açıklaması. PredefinedCategory içinde tanımlanan dize sabitlerinden biri olmalıdır. Etiket dizini Sınıflandırıcı tarafından desteklenen tüm etiketler arasında etiketin dizini. PredefinedCategory içinde tanımlanan tam sayı sabitlerinden biri olmalıdır. Etiket güvenilirliği Nesne sınıflandırmasının güven değeri.

Kotlin

for (detectedObject in detectedObjects) {
    val boundingBox = detectedObject.boundingBox
    val trackingId = detectedObject.trackingId
    for (label in detectedObject.labels) {
        val text = label.text
        if (PredefinedCategory.FOOD == text) {
            ...
        }
        val index = label.index
        if (PredefinedCategory.FOOD_INDEX == index) {
            ...
        }
        val confidence = label.confidence
    }
}

Java

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

Mükemmel bir kullanıcı deneyimi sunma

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

• Nesne algılamanın başarısı, nesnenin görsel karmaşıklığına bağlıdır. Az sayıda görsel özelliğe sahip nesnelerin algılanması için görüntünün daha büyük bir kısmını kaplaması gerekebilir. Kullanıcılara, algılamak istediğiniz nesne türleriyle iyi çalışan girişler yakalama konusunda yol göstermeniz gerekir.
• Sınıflandırmayı kullanırken desteklenen kategorilere tam olarak uymayan nesneleri algılamak istiyorsanız bilinmeyen nesneler için özel işlem uygulayın.

Ayrıca ML Kit 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

Nesne algılamayı gerçek zamanlı bir uygulamada kullanmak istiyorsanız en iyi kare hızlarını elde etmek için aşağıdaki yönergeleri uygulayın:

• Gerçek zamanlı bir uygulamada akış modunu kullandığınızda çoğu cihaz yeterli kare hızları üretemeyeceğinden birden fazla nesne algılama özelliğini kullanmayın.

• İhtiyacınız yoksa sınıflandırmayı devre dışı bırakın.

• Camera veya camera2 API'sini kullanıyorsanız algılayıcıya yapılan çağrıları sınırlayı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ıç kılavuzu örnek uygulamasındaki VisionProcessorBase sınıfına bakın.
• CameraX API'sini kullanıyorsanız geri basınç stratejisinin varsayılan değerine ayarlandığından emin olun ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Bu sayede, aynı anda analiz için yalnızca bir resim gönderilir. Analizör meşgulken daha fazla görüntü oluşturulursa bu görüntüler otomatik olarak bırakılır ve yayınlama için sıraya alınmaz. Analiz edilen resim, ImageProxy.close() çağrısı yapılarak kapatıldıktan sonra bir sonraki en yeni resim yayınlanır.
• Giriş resmine grafik yerleştirmek için algılayıcının çıkışını kullanıyorsanız önce ML Kit'ten sonucu alın, ardından resmi ve yer paylaşımını tek bir adımda oluşturun. Bu, her giriş karesi için ekran yüzeyinde yalnızca bir kez oluşturulur. Örnek olarak, hızlı başlangıç kılavuzundaki örnek uygulamadaki CameraSourcePreview ve GraphicOverlay sınıflarına bakın.
• Camera2 API'yi kullanıyorsanız resimleri ImageFormat.YUV_420_888 biçiminde kaydedin. Eski Camera API'yi kullanıyorsanız resimleri ImageFormat.NV21 biçiminde çekin.