Android için el ile önemli noktaları algılama rehberi

MediaPipe El İşaretçisi görevi, bir görüntüdeki ellerin önemli noktalarını algılamanızı sağlar. Bu talimatlar, El İşaretçisi'nin Android uygulamalarıyla nasıl kullanılacağını gösterir. Bu talimatlarda açıklanan kod örneğine GitHub'dan ulaşabilirsiniz.

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 bir El İşaretçisi uygulamasının basit bir uygulamasıdır. Örnekte, el ile ilgili önemli noktaları sürekli olarak algılamak için fiziksel bir Android cihazın kamerası kullanılır. Ayrıca el ile ilgili önemli noktaları statik olarak algılamak için de cihaz galerisindeki resim ve videolar kullanılabilir.

Uygulamayı kendi Android uygulamanız için başlangıç noktası olarak kullanabilir veya mevcut bir uygulamayı değiştirirken referans olarak kullanabilirsiniz. Hand İşaretleyici ö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ırarak yalnızca El İşaretçisi örnek uygulamasına ait dosyalara sahip olacaksınız:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/hand_landmarker/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 işareti algılama örneği uygulaması için önemli kodu içerir:

• HandLandmarkerHelper.kt: El önemli nokta algılayıcısını başlatır, modeli ve yetkiyi seçme işlemini gerçekleştirir.
• MainActivity.kt - HandLandmarkerHelper yöntemini çağırmak da dahil olmak üzere uygulamayı uygular.

Kurulum

Bu bölümde, geliştirme ortamınızı kurmanın temel adımları açıklanmaktadır. Projelerinizi özellikle El İşaretçisi'ni kullanacak şekilde kodlayın. 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

El İşaretçisi görevi, com.google.mediapipe:tasks-vision kitaplığını kullanır. Bu bağımlılığı Android uygulamanızın build.gradle dosyasına ekleyin:

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

Model

MediaPipe El İşaretçisi görevi, bu görevle uyumlu, eğitilmiş bir model paketi gerektirir. El İşaretçisi için eğitilmiş modeller hakkında daha fazla bilgi almak için göreve genel bakış Modeller bölümüne bakın.

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

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

ModelAssetPath parametresinde modelin yolunu belirtin. Örnek kodda, model HandLandmarkerHelper.kt dosyasında tanımlanmıştır:

baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)

Görevi oluşturma

MediaPipe El İşaretçisi 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 edinmek için Yapılandırma seçenekleri bölümüne bakın.

El İşaretçisi 3 giriş veri türünü destekler: hareketsiz resimler, video dosyaları ve canlı yayın. 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ımda bulunacağınızı görmek için girdiğiniz veri türüne karşılık gelen sekmeyi seçin.

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

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.IMAGE)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)
    

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

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)
    

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

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setResultListener(this::returnLivestreamResult)
        .setErrorListener(this::returnLivestreamError)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)
    

El İşaretçisi örnek kod uygulaması, kullanıcının işleme modları arasında geçiş yapmasını sağlar. Bu yaklaşım, görev oluşturma kodunu daha karmaşık hale getirir ve sizin kullanım alanınıza uygun olmayabilir. Bu kodu HandLandmarkerHelper.kt dosyasındaki setupHandLandmarker() 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:

Verileri hazırlama

El İşaretçisi resimler, 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.

Aşağıdaki kod, verilerin işlenmek üzere nasıl aktarılacağını gösterir. Bu örnekler resimler, video dosyaları ve canlı video akışlarındaki verilerin nasıl işleneceğine dair ayrıntılar içerir.

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

El İşaretçisi örnek kodunda, veri hazırlığı HandLandmarkerHelper.kt dosyası içinde gerçekleştirilir.

Görevi çalıştırma

Çalıştığınız veri türüne bağlı olarak, ilgili veri türüne özel HandLandmarker.detect...() yöntemini kullanın. Ayrı resimler için detect(), video dosyalarındaki kareler için detectForVideo() ve video akışları için detectAsync() kullanın. Bir video akışında algılama işlemi yaparken kullanıcı arayüzü iş parçacığının engellenmesini önlemek için algılamaları ayrı bir iş parçacığında çalıştırdığınızdan emin olun.

Aşağıdaki kod örneklerinde El İşaretçisi'nin bu farklı veri modlarında nasıl çalıştırılacağına ilişkin basit örnekler gösterilmektedir:

val result = handLandmarker?.detect(mpImage)
    

val timestampMs = i * inferenceIntervalMs

handLandmarker?.detectForVideo(mpImage, timestampMs)
    ?.let { detectionResult ->
        resultList.add(detectionResult)
    }
    

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

handLandmarker?.detectAsync(mpImage, frameTime)
    

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

• Video modunda veya canlı yayın modunda çalışırken El İşaretçisi görevine giriş karesinin zaman damgasını da sağlamanız gerekir.
• Resim veya video modunda çalışırken, El İşaretçisi görevi giriş resmini veya çerçevesini işlemeyi bitirene kadar mevcut iş parçacığını engeller. Kullanıcı arayüzünün engellenmesini önlemek için işlemeyi bir arka plan iş parçacığında yürütün.
• Canlı yayın modunda çalışırken İşaretçi İşaretçi 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. El İşaretçisi görevi başka bir kareyi işlemekle meşgulken algılama işlevi çağrılırsa görev yeni giriş çerçevesini yoksayar.

El İşaretçisi örnek kodunda, detect, detectForVideo ve detectAsync işlevleri HandLandmarkerHelper.kt dosyasında tanımlanmıştır.

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

El İşaretçisi, her algılama çalıştırması için bir el işaretçisi sonuç nesnesi oluşturur. Sonuç nesnesi, resim koordinatlarında el yer işaretleri, dünya koordinatlarındaki el işaretleri ve algılanan ellerin el tercihini(sol/sağ el) içerir.

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

HandLandmarkerResult çıkışı üç bileşen içerir. Her bileşen bir dizidir. Bu dizide her öğe, algılanan tek bir el için aşağıdaki sonuçları içerir:

• Uygun Olduğu El

  El bilgisi, algılanan ellerin sol el mi yoksa sağ el mi olduğunu belirtir.

• Önemli noktalar

  Her biri x, y ve z koordinatlarından oluşan 21 önemli nokta vardır. x ve y koordinatları, sırasıyla resim genişliği ve yüksekliğine göre [0,0, 1,0] olacak şekilde normalleştirilir. z koordinatı, önemli nokta derinliğini temsil eder. Bilekteki derinlik ise başlangıç noktasıdır. Değer ne kadar küçükse nokta kameraya o kadar yakın olur. z ölçeğinin büyüklüğü, x ile yaklaşık olarak aynı ölçeği kullanır.

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

  21 önemli nokta, dünya koordinatlarında da gösterilir. Her önemli nokta, x, y ve z öğelerinden oluşur. Bu noktalar, başlangıç noktası elin geometrik merkezinde olmak üzere gerçek dünyadaki 3D koordinatları metre cinsinden temsil eder.

HandLandmarkerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  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 resimde, görev çıkışının görseli gösterilmektedir:

El İşaretçisi örnek kodu, görevden döndürülen sonuçların nasıl görüntüleneceğini gösterir. Daha fazla bilgi için OverlayView sınıfına bakın.