Android için hareket tanıma rehberi

MediaPipe İşaret Tanımlayıcı görevi, el hareketlerini gerçek zamanlı olarak tanımanıza olanak tanır ve tanınan el hareketi sonuçlarını ve algılanan ellerin el yer işaretlerini sağlar. Bu talimatlarda, Android uygulamalarıyla Hareket Algılayıcı'nın nasıl kullanılacağı gösterilmektedir. Bu talimatlarda açıklanan kod örneğini GitHub'da bulabilirsiniz.

Bu görevi çalışırken görmek için web demosunu görüntüleyebilirsiniz. Bu görevin özellikleri, modelleri ve yapılandırma seçenekleri hakkında daha fazla bilgi için Genel bakış bölümüne bakın.

Kod örneği

MediaPipe Tasks örnek kodu, Android için bir Hareket Algılama uygulamasının basit bir uygulamasıdır. Bu örnekte, el hareketlerini sürekli olarak algılamak için fiziksel bir Android cihazdaki kamera kullanılır. Hareketleri statik olarak algılamak için cihaz galerisindeki resim ve videolar da kullanılabilir.

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

Kodu indirme

Aşağıdaki talimatlarda, git komut satırı aracını kullanarak örnek kodun yerel bir kopyasının nasıl oluşturulacağı gösterilmektedir.

Ö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 seyrek kontrol kullanacak şekilde yapılandırın. Böylece yalnızca Hareket Algılama örneği uygulamasının dosyalarına sahip olursunuz:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/gesture_recognizer/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 için Kurulum Kılavuzu'na bakın.

Temel bileşenler

Aşağıdaki dosyalar, bu el hareketi tanıma örnek uygulamasının önemli kodunu içerir:

• GestureRecognizerHelper.kt: Hareket tanımayı başlatır, modeli ve temsilci seçimini yönetir.
• MainActivity.kt: GestureRecognizerHelper ve GestureRecognizerResultsAdapter çağrıları da dahil olmak üzere uygulamayı uygular.
• GestureRecognizerResultsAdapter.kt: Sonuçları işler ve biçimlendirir.

Kurulum

Bu bölümde, geliştirme ortamınızı ve kod projelerinizi özellikle Hareket Tanımlayıcı'yı kullanacak şekilde ayarlamayla ilgili temel adımlar açıklanmaktadır. Platform sürümü gereksinimleri dahil olmak üzere, geliştirme ortamınızı MediaPipe görevlerini kullanmak için ayarlama hakkında genel bilgi için Android için kurulum kılavuzu başlıklı makaleyi inceleyin.

Bağımlılıklar

Hareket Tanımlayıcı görevi com.google.mediapipe:tasks-vision kitaplığını kullanır. Bu bağımlılık, Android uygulamanızın build.gradle dosyasına eklenmelidir:

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

Model

MediaPipe Hareket Tanımlayıcı görevi, bu görevle uyumlu bir eğitimli model paketi gerektirir. Hareket Tanımlayıcı için mevcut eğitimli modeller hakkında daha fazla bilgi edinmek istiyorsanız göreve genel bakıştaki Modeller bölümüne bakın.

Modeli seçip indirin ve proje dizininizde saklayın:

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

ModelAssetPath parametresinde modelin yolunu belirtin. Örnek kodda model, GestureRecognizerHelper.kt dosyasında tanımlanır:

baseOptionBuilder.setModelAssetPath(MP_RECOGNIZER_TASK)

Görevi oluşturun

MediaPipe Hareket Tanımlayıcı görevi, görevi ayarlamak için createFromOptions() işlevini kullanır. createFromOptions() işlevi, yapılandırma seçenekleri için değerleri kabul eder. Yapılandırma seçenekleri hakkında daha fazla bilgi için Yapılandırma seçenekleri başlıklı makaleyi inceleyin.

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

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    GestureRecognizer.GestureRecognizerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setRunningMode(RunningMode.IMAGE)

val options = optionsBuilder.build()
gestureRecognizer =
    GestureRecognizer.createFromOptions(context, options)
    

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    GestureRecognizer.GestureRecognizerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()
gestureRecognizer =
    GestureRecognizer.createFromOptions(context, options)
    

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    GestureRecognizer.GestureRecognizerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setResultListener(this::returnLivestreamResult)
        .setErrorListener(this::returnLivestreamError)
        .setRunningMode(RunningMode.LIVE_STREAM)

val options = optionsBuilder.build()
gestureRecognizer =
    GestureRecognizer.createFromOptions(context, options)
    

Hareket Tanımlayıcı ö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ız için uygun olmayabilir. Bu kodu, GestureRecognizerHelper.kt dosyasında setupGestureRecognizer() işlevinde görebilirsiniz.

Yapılandırma seçenekleri

Bu görevde, Android uygulamaları için aşağıdaki yapılandırma seçenekleri bulunur:

Verileri hazırlama

Hareket Tanımlayıcı, resimler, video dosyaları ve canlı yayın videolarıyla çalışır. Görev, yeniden boyutlandırma, döndürme ve değer normalleştirme dahil olmak üzere veri girişi ön işleme işlemlerini yönetir.

Aşağıdaki kod, verilerin işlenmek üzere nasıl aktarılacağını gösterir. Bu örneklerde, resimlerden, video dosyalarından ve canlı video yayınlarından elde edilen verilerin nasıl işleneceğine dair ayrıntılar yer alır.

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

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(image).build()
    

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

val argb8888Frame =
    if (frame.config == Bitmap.Config.ARGB_8888) frame
    else frame.copy(Bitmap.Config.ARGB_8888, false)

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(argb8888Frame).build()
    

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

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(rotatedBitmap).build()
    

Hareket Tanımlayıcı örnek kodunda veri hazırlama işlemi GestureRecognizerHelper.kt dosyasında gerçekleştirilir.

Görevi çalıştırma

Hareket Tanımlayıcı, çıkarım tetiklemek için recognize, recognizeForVideo ve recognizeAsync işlevlerini kullanır. Hareket algılama için giriş verilerini ön işleme, resimdeki elleri, el önemli noktalarını algılama ve önemli noktalardan el hareketini tanıma işlemleri yapılır.

Aşağıdaki kodda, işleme işleminin görev modeliyle nasıl yürütüleceği gösterilmektedir. Bu örneklerde, resimlerden, video dosyalarından ve canlı video yayınlarından elde edilen verilerin nasıl işleneceğine dair ayrıntılar yer alır.

val result = gestureRecognizer?.recognize(mpImage)
    

val timestampMs = i * inferenceIntervalMs

gestureRecognizer?.recognizeForVideo(mpImage, timestampMs)
    ?.let { recognizerResult ->
        resultList.add(recognizerResult)
    }
    

val mpImage = BitmapImageBuilder(rotatedBitmap).build()
val frameTime = SystemClock.uptimeMillis()

gestureRecognizer?.recognizeAsync(mpImage, frameTime)
    

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

• Video modunda veya canlı yayın modunda çalışırken, jest algılayıcı görevine giriş karesinin zaman damgasını da sağlamanız gerekir.
• Hareket Tanımlayıcı görevi, resim veya video modunda çalışırken giriş resmini ya da kareyi işlemeyi tamamlayana kadar mevcut iş parçacığını engeller. Kullanıcı arayüzünün engellenmesini önlemek için işlemeyi arka plan iş parçacığında yürütün.
• Hareket Algılama görevi, canlı yayın modunda çalışırken geçerli iş parçacığını engellemez ancak hemen döndürülür. Her giriş karesini işlemeyi tamamladığında sonuç dinleyicisini tanıma sonucuyla çağırır. Hareket Tanımlayıcı görevi başka bir kareyi işlerken tanıma işlevi çağrılırsa görev yeni giriş karesini yoksayar.

Hareket Tanımlayıcı örnek kodunda recognize, recognizeForVideo ve recognizeAsync işlevleri GestureRecognizerHelper.kt dosyasında tanımlanır.

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

Hareket Tanımlayıcı, her tanıma çalıştırması için bir hareket algılama sonucu nesnesi oluşturur. Sonuç nesnesi, resim koordinatlarında el yer işaretlerini, dünya koordinatlarında el yer işaretlerini, el hakimiyetini(sol/sağ el) ve algılanan ellerin el hareketi kategorilerini içerir.

Aşağıda, bu görevin çıkış verilerine örnek verilmiştir:

Elde edilen GestureRecognizerResult dört bileşen içerir. Her bileşen bir dizidir ve her öğe, algılanan tek bir elin algılanan sonucunu içerir.

• El tercihi

  El tercihi, algılanan ellerin sol el mi yoksa sağ el mi olduğunu gösterir.

• Hareketler

  Algılanan ellerin tanınan hareket kategorileri.

• Önemli noktalar

  Her biri x, y ve z koordinatlarından oluşan 21 el yer işareti vardır. x ve y koordinatları, sırasıyla resim genişliği ve yüksekliğine göre [0,0; 1,0] aralığında normalleştirilir. z koordinatı, bilekteki derinliğin orijin olduğu yer işareti derinliğini temsil eder. Değer ne kadar küçükse yer işareti kameraya o kadar yakındır. z büyüklüğü, x ile yaklaşık olarak aynı ölçeği kullanır.

• Dünyanın Sınırları

  21 el yer işareti de dünya koordinatlarında sunulur. Her önemli nokta, x, y ve z değerlerinden oluşur. Bu değerler, orijini elin geometrik merkezinde olan, gerçek dünyadaki 3D koordinatları metre cinsinden temsil eder.

GestureRecognizerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Gestures:
    Categories #0:
      score        : 0.76893
      categoryName : Thumb_Up
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : -3.41E-7
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
    ... (21 landmarks for a hand)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
    ... (21 world landmarks for a hand)

Aşağıdaki resimlerde görev çıktısının görselleştirmesi gösterilmektedir:

Hareket Tanımlayıcı örnek kodunda, GestureRecognizerResultsAdapter.kt dosyasında bulunan GestureRecognizerResultsAdapter sınıfı sonuçları işler.