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:
- Aşağıdaki komutu kullanarak git deposunu klonlayın:
git clone https://github.com/google-ai-edge/mediapipe-samples
- İ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.
Resim
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)
Video
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)
Canlı yayın
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:
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 |
numHands |
El işareti dedektörü tarafından algılanan maksimum el sayısı. | Any integer > 0 |
1 |
minHandDetectionConfidence |
El algılamasının, avuç içi algılama modelinde başarılı olarak değerlendirilebilmesi için gereken minimum güven puanı. | 0.0 - 1.0 |
0.5 |
minHandPresenceConfidence |
El önemli nokta algılama modelindeki el varlığı puanı için minimum güven puanı. Video modunda ve Canlı yayın modunda, el belirgin işaret modelindeki el varlığı güven puanı bu eşiğin altındaysa El İşaretçisi avuç içi algılama modelini tetikler. Aksi takdirde, sonraki önemli nokta algılamaları için ellerin konumunu basit bir el izleme algoritması belirler. | 0.0 - 1.0 |
0.5 |
minTrackingConfidence |
Elle izlemenin başarılı olarak kabul edilmesi için gereken minimum güven puanı. Bu, geçerli çerçevede ve son karede bulunan eller arasındaki sınırlayıcı kutu IoU eşiğidir. El İşaretçisi'nin Video ve Akış modunda izleme başarısız olursa El İşaretçisi el algılamayı tetikler. Aksi halde, el algılaması atlanır. | 0.0 - 1.0 |
0.5 |
resultListener |
Sonuç işleyiciyi, el işaretçisi canlı yayın modundayken algılama sonuçlarını eşzamansız olarak alacak şekilde ayarlar.
Yalnızca çalıştırma modu LIVE_STREAM olarak ayarlandığında geçerlidir |
Yok | Yok |
errorListener |
İsteğe bağlı bir hata işleyici ayarlar. | Yok | Yok |
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.
Resim
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()
Video
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()
Canlı yayın
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:
Resim
val result = handLandmarker?.detect(mpImage)
Video
val timestampMs = i * inferenceIntervalMs handLandmarker?.detectForVideo(mpImage, timestampMs) ?.let { detectionResult -> resultList.add(detectionResult) }
Canlı yayın
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
vez
koordinatlarından oluşan 21 önemli nokta vardır.x
vey
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
vez
öğ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.