Android için resim yerleştirme rehberi

MediaPipe Görüntü Yerleştirme görevi, iki görüntünün benzerliğini karşılaştırmak gibi makine öğrenimiyle ilgili görüntü işleme görevlerini gerçekleştirmek için görüntü verilerini sayısal bir temsile dönüştürmenizi sağlar. Bu talimatlar Android uygulamalarıyla Image Embedder'ın nasıl kullanılacağını gösterir.

Bu görevin özellikleri, modelleri ve yapılandırma seçenekleri hakkında daha fazla bilgi için Genel Bakış'a bakın.

Kod örneği

MediaPipe Tasks örnek kodu, Android için Görüntü Yerleştirme uygulamasının basit bir uygulamasıdır. Örnekte, resimleri sürekli olarak yerleştirmek için fiziksel bir Android cihazın kamerası kullanılmaktadır. Ayrıca, yerleştirme aracı, cihazda depolanan resim dosyalarında da çalıştırılabilir.

Uygulamayı kendi Android uygulamanız için başlangıç noktası olarak kullanabilir veya mevcut bir uygulamayı değiştirirken referans olarak kullanabilirsiniz. Resim Yerleştirme örnek kodu GitHub'da barındırılır.

Kodu indirme

Aşağıdaki talimatlar, git komut satırı aracını kullanarak örnek kodun yerel bir kopyasını nasıl oluşturacağınızı göstermektedir.

Örnek kodu indirmek için:

  1. Aşağıdaki komutu kullanarak git deposunu klonlayın:
    git clone https://github.com/google-ai-edge/mediapipe-samples
    
  2. İsteğe bağlı olarak, git örneğinizi az ödeme yöntemini kullanacak şekilde yapılandırın. Böylece, yalnızca Image Embedder örnek uygulamasının dosyalarına sahip olursunuz:
    cd mediapipe
    git sparse-checkout init --cone
    git sparse-checkout set examples/image_embedder/android
    

Örnek kodun yerel bir sürümünü oluşturduktan sonra projeyi Android Studio'ya aktarabilir ve uygulamayı çalıştırabilirsiniz. Talimatlar için Android Kurulum Kılavuzu'na bakın.

Temel bileşenler

Aşağıdaki dosyalar, bu resim yerleştirme örnek uygulaması için önemli kodu içerir:

Kurulum

Bu bölümde, geliştirme ortamınızı kurmayla ilgili temel adımlar ve Görüntü Yerleştirme'yi kullanmak için proje kodlama açıklanmaktadır. Platform sürümü gereksinimleri de dahil olmak üzere, MediaPipe görevlerini kullanmak amacıyla geliştirme ortamınızı ayarlama hakkında genel bilgiler için Android için kurulum kılavuzuna bakın.

Bağımlılıklar

Resim Yerleştirici, com.google.mediapipe:tasks-vision kitaplığını kullanır. Bu bağımlılığı, Android uygulaması geliştirme projenizin build.gradle dosyasına ekleyin. Gerekli bağımlılıkları aşağıdaki kodla içe aktarın:

dependencies {
    ...
    implementation 'com.google.mediapipe:tasks-vision:latest.release'
}

Model

MediaPipe Görüntü Yerleştirme görevi, bu görevle uyumlu, eğitilmiş bir model gerektirir. Resim Yerleştirme için eğitilmiş modeller hakkında daha fazla bilgi almak isterseniz göreve genel bakış Modeller bölümüne bakın.

Modeli seçip indirin ve ardından proje dizininizde depolayın:

<dev-project-root>/src/main/assets

ModelAssetPath parametresinde modelin yolunu belirtin. Örnek kodda model, ImageEmbedderHelper.kt dosyasındaki setupImageEmbedder() işlevinde tanımlanır:

Modelin kullandığı yolu belirtmek için BaseOptions.Builder.setModelAssetPath() yöntemini kullanın. Bu yöntem, bir sonraki bölümde yer alan kod örneğinde ele alınmaktadır.

Görevi oluşturma

Görevi oluşturmak için createFromOptions işlevini kullanabilirsiniz. createFromOptions işlevi, yerleştirici seçeneklerini ayarlamak için gereken yapılandırma seçeneklerini kabul eder. Yapılandırma seçenekleri hakkında daha fazla bilgi için Yapılandırmaya Genel Bakış bölümüne bakın.

Görüntü Yerleştirme görevi 3 giriş veri türünü destekler: sabit resimler, video dosyaları ve canlı video akışları. Görevi oluştururken giriş verisi türünüze karşılık gelen çalışma modunu belirtmeniz gerekir. Görevi nasıl oluşturacağınızı ve çıkarımı nasıl yapacağınızı görmek için giriş verisi türünüze karşılık gelen sekmeyi seçin.

Resim

ImageEmbedderOptions options =
  ImageEmbedderOptions.builder()
    .setBaseOptions(
      BaseOptions.builder().setModelAssetPath("model.tflite").build())
    .setQuantize(true)
    .setRunningMode(RunningMode.IMAGE)
    .build();
imageEmbedder = ImageEmbedder.createFromOptions(context, options);
    

Video

ImageEmbedderOptions options =
  ImageEmbedderOptions.builder()
    .setBaseOptions(
      BaseOptions.builder().setModelAssetPath("model.tflite").build())
    .setQuantize(true)
    .setRunningMode(RunningMode.VIDEO)
    .build();
imageEmbedder = ImageEmbedder.createFromOptions(context, options);
    

Canlı yayın

ImageEmbedderOptions options =
  ImageEmbedderOptions.builder()
    .setBaseOptions(
      BaseOptions.builder().setModelAssetPath("model.tflite").build())
    .setQuantize(true)
    .setRunningMode(RunningMode.LIVE_STREAM)
    .setResultListener((result, inputImage) -> {
         // Process the embedding result here.
    })
    .build();
imageEmbedder = ImageEmbedder.createFromOptions(context, options);
    

Örnek kod uygulaması, kullanıcının işleme modları arasında geçiş yapmasına olanak tanır. Bu yaklaşım, görev oluşturma kodunu daha karmaşık hale getirir ve kullanım alanınıza uygun olmayabilir. Bu kodu, ImageEmbedderHelper.kt dosyasındaki setupImageEmbedder() işlevinde görebilirsiniz.

Yapılandırma seçenekleri

Bu görev, Android uygulamaları için aşağıdaki yapılandırma seçeneklerine sahiptir:

Seçenek Adı Açıklama Değer Aralığı Varsayılan Değer
runningMode Görevin çalışma modunu ayarlar. Üç mod vardır:

RESİM: Tek resimli girişler için mod.

VİDEO: Bir videonun kodu çözülmüş karelerine yönelik mod.

LIVE_STREAM: Kamera gibi giriş verilerini içeren bir canlı yayın modu. Bu modda, sonuçları eşzamansız olarak almak üzere bir işleyici ayarlamak için resultListener çağrılmalıdır.
{IMAGE, VIDEO, LIVE_STREAM} IMAGE
l2_normalize Döndürülen özellik vektörünün L2 normuyla normalleştirilip normalleştirilmeyeceği. Bu seçeneği yalnızca modelde zaten yerel bir L2_NORMALIZATION TFLite Op bulunmuyorsa kullanın. Çoğu durumda bu zaten mevcuttur ve L2 normalleştirmesi, bu seçeneğe gerek olmadan TFLite çıkarımıyla yapılır. Boolean False
quantize Döndürülen yerleştirmenin skalar niceleme kullanılarak baytlara dönüştürülüp ölçülmeyeceği. Yerleştirmelerin açıkça birim norm olduğu varsayılır. Bu nedenle her boyut için [-1,0, 1,0] değerinde bir değer olması garanti edilir. Bu mümkün değilse l2_normalize seçeneğini kullanın. Boolean False
resultListener Sonuç işleyiciyi, Resim Yerleştirme canlı yayın modundayken yerleştirme sonuçlarını eşzamansız olarak alacak şekilde ayarlar. Yalnızca çalıştırma modu LIVE_STREAM olarak ayarlandığında kullanılabilir Yok Belirlenmedi
errorListener İsteğe bağlı bir hata işleyici ayarlar. Yok Belirlenmedi

Verileri hazırlama

Görüntü Yerleştirme; görüntüler, video dosyası ve canlı video yayını ile çalışır. Görev; yeniden boyutlandırma, döndürme ve değer normalleştirmesi dahil olmak üzere, veri girişinin ön işlemesini yönetir.

Giriş görüntüsünü veya çerçevesini Görüntü Yerleştirme görevine iletmeden önce bir com.google.mediapipe.framework.image.MPImage nesnesine dönüştürmeniz gerekir.

Resim

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load an image on the user’s device as a Bitmap object using BitmapFactory.

// Convert an Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(bitmap).build();
    

Video

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load a video file on the user's device using MediaMetadataRetriever

// From the video’s metadata, load the METADATA_KEY_DURATION and
// METADATA_KEY_VIDEO_FRAME_COUNT value. You’ll need them
// to calculate the timestamp of each frame later.

// Loop through the video and load each frame as a Bitmap object.

// Convert the Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(frame).build();
    

Canlı yayın

import com.google.mediapipe.framework.image.MediaImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Create a CameraX’s ImageAnalysis to continuously receive frames
// from the device’s camera. Configure it to output frames in RGBA_8888
// format to match with what is required by the model.

// For each Android’s ImageProxy object received from the ImageAnalysis,
// extract the encapsulated Android’s Image object and convert it to
// a MediaPipe’s Image object.
android.media.Image mediaImage = imageProxy.getImage()
Image mpImage = new MediaImageBuilder(mediaImage).build();
    

Örnek kodda, veri hazırlama işlemi ImageEmbedderHelper.kt dosyası içinde gerçekleştirilir.

Görevi çalıştırma

Çıkarımları tetiklemek için koşu modunuza karşılık gelen embed işlevini çağırabilirsiniz. Image Embedder API, giriş görüntüsü veya çerçevesi için yerleştirme vektörlerini döndürür.

Resim

ImageEmbedderResult embedderResult = imageEmbedder.embed(image);
    

Video

// Calculate the timestamp in milliseconds of the current frame.
long frame_timestamp_ms = 1000 * video_duration * frame_index / frame_count;

// Run inference on the frame.
ImageEmbedderResult embedderResult =
    imageEmbedder.embedForVideo(image, frameTimestampMs);
    

Canlı yayın


// Run inference on the frame. The embedding results will be available
// via the `resultListener` provided in the `ImageEmbedderOptions` when
// the image embedder was created.
imageEmbedder.embedAsync(image, frameTimestampMs);
    

Aşağıdakileri göz önünde bulundurun:

  • Video modunda veya canlı yayın modunda çalışırken Görüntü Yerleştirme görevine giriş karesinin zaman damgasını da sağlamanız gerekir.
  • Resim veya video modunda çalışırken, Görüntü Yerleştirme görevi giriş görüntüsünü veya çerçevesini işlemeyi bitirene kadar mevcut iş parçacığını engeller. Geçerli iş parçacığını engellemekten kaçınmak için işlemeyi bir arka plan iş parçacığında yürütün.
  • Canlı yayın modunda çalışırken Resim Yerleştirme görevi mevcut ileti dizisini engellemez ancak hemen geri döner. Bir giriş karesini işlemeyi her tamamladığında algılama sonucuyla birlikte sonuç işleyicisini çağırır. Resim Yerleştirme görevi başka bir kareyi işlemekle meşgulken embedAsync işlevi çağrılırsa görev yeni giriş çerçevesini yoksayar.

Örnek kodda, embed işlevi ImageEmbedderHelper.kt dosyasında tanımlanmıştır.

Sonuçları işleme ve görüntüleme

Çıkarım çalıştırıldığında, Görüntü Yerleştirme görevi, giriş görüntüsü için yerleştirmelerin listesini (kayan nokta veya skaler ölçülmüş) içeren bir ImageEmbedderResult nesnesi döndürür.

Aşağıda, bu görevden alınan çıkış verilerinin bir örneği gösterilmektedir:

ImageEmbedderResult:
  Embedding #0 (sole embedding head):
    float_embedding: {0.0, 0.0, ..., 0.0, 1.0, 0.0, 0.0, 2.0}
    head_index: 0

Bu sonuç, aşağıdaki resim yerleştirilerek elde edilmiştir:

ImageEmbedder.cosineSimilarity işlevini kullanarak iki yerleştirmenin benzerliğini karşılaştırabilirsiniz. Örnek için aşağıdaki koda bakın.

// Compute cosine similarity.
double similarity = ImageEmbedder.cosineSimilarity(
  result.embeddingResult().embeddings().get(0),
  otherResult.embeddingResult().embeddings().get(0));