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

ML Kit'i kullanarak birbirini takip eden video karelerindeki nesneleri algılayıp takip edebilirsiniz.

ML Kit'e bir resim ilettiğinizde, resimdeki en fazla beş nesneyi ve her nesnenin resimdeki konumunu algılar. Video akışlarındaki nesneler algılanırken her nesnenin benzersiz bir kimliği olur. Bu kimliği kullanarak nesneyi kareden kareye takip edebilirsiniz. İsterseniz nesneleri geniş kategori açıklamalarıyla etiketleyen kaba nesne sınıflandırmasını da etkinleştirebilirsiniz.

Deneyin

• Bu API'nin örnek kullanımını görmek için örnek uygulamayı deneyin.
• Bu API'nin uçtan uca uygulanması için Materyal Tasarım tanıtım uygulamasına bakın.

Başlamadan önce

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

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

1. Nesne tespit etmeyi yapılandırma

Nesneleri algılamak ve izlemek için önce bir ObjectDetector örneği oluşturun ve isteğe bağlı olarak, varsayılandan değiştirmek istediğiniz algılayıcı ayarlarını belirtin.

1. Nesne algılayıcıyı, kullanım alanınız için bir ObjectDetectorOptions nesnesiyle 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) modunda nesne algılayıcı düşük gecikmeyle ç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) üretebilir. Ayrıca STREAM_MODE, algılayıcı nesnelere izleme kimlikleri atar. Bu kimlikleri kullanarak nesneleri kareler arasında izleyebilirsiniz. Nesneleri takip etmek istediğinizde veya video akışlarını gerçek zamanlı olarak işlerken olduğu gibi düşük gecikme süresinin önemli olduğu durumlarda bu modu kullanın. SINGLE_IMAGE_MODE modelinde nesne algılayıcı, nesnenin sınırlayıcı kutusu belirlendikten sonra sonucu döndürür. Sınıflandırmayı da etkinleştirirseniz sınırlayıcı kutu ve kategori etiketi kullanılabilir olduğunda sonucu döndürür. Bu nedenle, algılama gecikmesi daha yüksek olabilir. Ayrıca SINGLE_IMAGE_MODE'da 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 En fazla beş nesnenin mi yoksa yalnızca en belirgin nesnenin mi (varsayılan) algılanıp izleneceğini belirler.
   Nesneleri sınıflandırma	false (varsayılan) | true Algılanan nesnelerin genel kategorilere göre sınıflandırılıp sınıflandırılmayacağı. Etkinleştirildiğinde nesne algılayıcı, nesneleri şu kategorilere ayırır: moda ürünleri, yiyecek, ev eşyaları, yerler ve bitkiler.

   Nesne tespit etme ve izleme API'si, şu 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 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ği alın:

   Kotlin

   val objectDetector = ObjectDetection.getClient(options)

   Java

   ObjectDetector objectDetector = ObjectDetection.getClient(options);

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

Nesne algılayıcı doğrudan bir Bitmap, NV21 ByteBuffer veya YUV_420_888 media.Image üzerinden çalışır. Bu kaynaklardan birine doğrudan erişiminiz varsa InputImage oluşturmak için bu kaynakları kullanmanız önerilir. Başka kaynaklardan InputImage oluşturursanız dönüşümü sizin için dahili olarak gerçekleştiririz ve bu işlem daha az verimli olabilir.

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

Farklı kaynaklardan InputImage nesnesi oluşturabilirsiniz. Bu kaynakları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 görüntü yakaladığınızda) media.Image nesnesini ve görüntünün dönüşünü InputImage.fromMediaImage() değerine iletin.

CameraX kitaplığını kullanıyorsanı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
          // ...
        }
    }
}

Görüntünün dönüş derecesini veren bir kamera kitaplığı kullanmıyorsanız bu değeri cihazın dönüş derecesinden ve cihazdaki kamera sensörünün yönünden 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;
}

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

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

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

Dosya URI'si kullanma

Bir dosya URI'sinden InputImage nesnesi oluşturmak için uygulama bağlamını ve dosya URI'sini InputImage.fromFilePath() yöntemine iletin. Bu, kullanıcının galeri uygulamasından bir resim seçmesini istemek için ACTION_GET_CONTENT intent'ini kullandığınızda yararlı olur.

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 nesnesinden InputImage nesnesi oluşturmak için önce media.Image girişi için daha önce açıklandığı şekilde resim döndürme derecesini hesaplayın. Ardından, arabellek veya diziyle birlikte resmin yüksekliği, genişliği, renk kodlama biçimi ve dönüş derecesini 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

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

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

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

Resim, dönüş dereceleriyle birlikte bir Bitmap nesnesiyle temsil edilir.

3. Resmi işleme

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

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

4. Algılanan nesneler hakkında bilgi edinme

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

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

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

// 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 sağlama

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

• Nesne tespit etmenin başarılı olması, nesnenin görsel karmaşıklığına bağlıdır. Az sayıda görsel özelliğe sahip nesnelerin algılanabilmesi için resmin daha büyük bir bölümünü kaplaması gerekebilir. Kullanıcılara, algılamak istediğiniz nesne türleriyle iyi çalışan girişleri yakalama konusunda rehberlik sağlamanız gerekir.
• Sınıflandırma kullanırken desteklenen kategorilere tam olarak uymayan nesneleri algılamak istiyorsanız bilinmeyen nesneler için özel bir 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.