Web için hareket tanıma kılavuzu

MediaPipe Hareket Tanımlayıcı görevi, el hareketlerini gerçek zamanlı olarak tanımanızı sağlar ve algılanan el hareketi sonuçlarını ve algılanan ellerin el işaretlerini gösterir. Bu talimatlar Web ve JavaScript uygulamaları için Hareket Tanıyıcı'nın nasıl kullanılacağını gösterir.

Demoyu izleyerek bu görevi çalışırken görebilirsiniz. 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

Hareket Tanıyıcı için örnek kod, size referans olması açısından bu görevin JavaScript'te eksiksiz bir şekilde uygulanmasını sağlar. Bu kod, bu görevi test etmenize ve kendi hareket tanıma uygulamanızı oluşturmaya başlamanıza yardımcı olur. Yalnızca web tarayıcınızı kullanarak Hareket Tanıyıcı örnek kodunu görüntüleyebilir, çalıştırabilir ve düzenleyebilirsiniz.

Kurulum

Bu bölümde, Hareket Tanıma Aracı'nı kullanmak için özel olarak geliştirme ortamınızı ayarlamayla ilgili temel adımlar açıklanmaktadır. Platform sürümü gereksinimleri dahil olmak üzere web ve JavaScript geliştirme ortamınızı ayarlama hakkında genel bilgiler için Web kurulum kılavuzuna bakın.

JavaScript paketleri

Hareket Tanıyıcı kodu, MediaPipe @mediapipe/tasks-vision NPM paketi aracılığıyla kullanılabilir. Bu kitaplıkları, platform Kurulum kılavuzundaki talimatları uygulayarak bulup indirebilirsiniz.

Aşağıdaki komutu kullanarak gerekli paketleri AİOY üzerinden yükleyebilirsiniz:

npm install @mediapipe/tasks-vision

Görev kodunu bir içerik yayınlama ağı (CDN) hizmeti aracılığıyla içe aktarmak isterseniz HTML dosyanızdaki <head> etiketine aşağıdaki kodu ekleyin:

<!-- You can replace JSDeliver with another CDN if you prefer to -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.js"
    crossorigin="anonymous"></script>
</head>

Model

MediaPipe Hareket Tanıyıcı görevi, bu görevle uyumlu, eğitilmiş bir model gerektirir. Hareket Tanıyıcı için eğitilmiş modeller hakkında daha fazla bilgi almak üzere 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>/app/shared/models/

Görevi oluşturma

Çıkarımları çalıştırma görevi hazırlamak için Hareket Tanıyıcı createFrom...() işlevlerinden birini kullanın. createFromModelPath() işlevini, eğitilen model dosyasına giden göreli veya mutlak bir yolla kullanın. Modeliniz belleğe zaten yüklenmişse createFromModelBuffer() yöntemini kullanabilirsiniz.

Aşağıdaki kod örneği, görevi ayarlamak için createFromOptions() işlevinin kullanımını gösterir. createFromOptions işlevi, yapılandırma seçenekleriyle Hareket Tanıyıcı'yı özelleştirmenize olanak tanır. Yapılandırma seçenekleri hakkında daha fazla bilgi edinmek için Yapılandırma seçenekleri bölümüne bakın.

Aşağıdaki kod, görevin özel seçeneklerle nasıl oluşturulacağını ve yapılandırılacağını gösterir:

// Create task for image file processing:
const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm "
);
const gestureRecognizer = await GestureRecognizer.createFromOptions(vision, {
  baseOptions: {
    modelAssetPath: "https://storage.googleapis.com/mediapipe-tasks/gesture_recognizer/gesture_recognizer.task"
  },
  numHands: 2
});

Yapılandırma seçenekleri

Bu görev, Web 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. İki mod vardır: RESİM: Tek resim girişleri modu. VİDEO: Bir videonun kodu çözülmüş kareleri veya kamera gibi giriş verilerinin canlı yayınındaki mod.	{`IMAGE, VIDEO`}	`IMAGE`
`num_hands`	`GestureRecognizer`, maksimum el sayısını algılayabilir.	`Any integer > 0`	`1`
`min_hand_detection_confidence`	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`
`min_hand_presence_confidence`	El önemli nokta algılama modelinde el varlığının minimum güven puanı. Hareket Tanıma Aracı'nın Video ve Canlı yayın modunda, el önemli nokta modelindeki el varlığı güven puanı bu eşiğin altındaysa avuç içi algılama modelini tetikler. Aksi takdirde, daha sonraki önemli nokta tespiti için ellerin konumunu belirlemek üzere hafif bir el takip algoritması kullanılır.	`0.0 - 1.0`	`0.5`
`min_tracking_confidence`	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. Hareket Tanıyıcı'nın Video ve Yayın modunda, izleme başarısız olursa Hareket Tanıyıcı el algılamayı tetikler. Aksi halde, el algılama özelliği atlanır.	`0.0 - 1.0`	`0.5`
`canned_gestures_classifier_options`	Hazır hareketler sınıflandırıcı davranışını yapılandırma seçenekleri. Hazır hareketler: `["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"]` Görünen adlar yerel ayarı: Varsa TFLite Model Meta Verileri aracılığıyla belirtilen görünen adlar için kullanılacak yerel ayar. Maksimum sonuç: Döndürülecek en yüksek puanlı sınıflandırma sonuçlarının maksimum sayısı. < 0 ise mevcut tüm sonuçlar döndürülür. Puan eşiği: Altına düşen sonuçların reddedildiği puan. 0 olarak ayarlanırsa mevcut tüm sonuçlar döndürülür. Kategori izin verilenler listesi: Kategori adlarının izin verilenler listesi. Boş değilse kategorisi bu grupta bulunmayan sınıflandırma sonuçları filtrelenir. Reddetme listesi ile birlikte kullanılamaz. Kategori ret listesi: Kategori adlarının ret listesi. Boş değilse kategorisi bu grupta yer alan sınıflandırma sonuçları filtrelenir. İzin verilenler listesi ile birlikte kullanılamaz.	Görünen adlar yerel ayarı: `any string` Maksimum sonuçlar: `any integer` Puan eşiği: `0.0-1.0` Kategori izin verilenler listesi: `vector of strings` Kategori ret listesi: `vector of strings`	Görünen adlar yerel ayarı: `"en"` Maksimum sonuçlar: `-1` Puan eşiği: `0` Kategori izin verilenler listesi: boş Kategori ret listesi: boş
`custom_gestures_classifier_options`	Özel hareketler sınıflandırıcı davranışını yapılandırma seçenekleri. Görünen adlar yerel ayarı: Varsa TFLite Model Meta Verileri aracılığıyla belirtilen görünen adlar için kullanılacak yerel ayar. Maksimum sonuç: Döndürülecek en yüksek puanlı sınıflandırma sonuçlarının maksimum sayısı. < 0 ise mevcut tüm sonuçlar döndürülür. Puan eşiği: Altına düşen sonuçların reddedildiği puan. 0 olarak ayarlanırsa mevcut tüm sonuçlar döndürülür. Kategori izin verilenler listesi: Kategori adlarının izin verilenler listesi. Boş değilse kategorisi bu grupta bulunmayan sınıflandırma sonuçları filtrelenir. Reddetme listesi ile birlikte kullanılamaz. Kategori ret listesi: Kategori adlarının ret listesi. Boş değilse kategorisi bu grupta yer alan sınıflandırma sonuçları filtrelenir. İzin verilenler listesi ile birlikte kullanılamaz.	Görünen adlar yerel ayarı: `any string` Maksimum sonuçlar: `any integer` Puan eşiği: `0.0-1.0` Kategori izin verilenler listesi: `vector of strings` Kategori ret listesi: `vector of strings`	Görünen adlar yerel ayarı: `"en"` Maksimum sonuçlar: `-1` Puan eşiği: `0` Kategori izin verilenler listesi: boş Kategori ret listesi: boş

Verileri hazırlama

Hareket Tanıma Aracı, ana makine tarayıcısının desteklediği herhangi bir biçimdeki resimlerdeki hareketleri tanıyabilir. Görev; yeniden boyutlandırma, döndürme ve değer normalleştirmesi dahil olmak üzere, veri girişi ön işlemesini de yönetir. Videolarda hareketleri tanımak için API'yi kullanarak tek seferde bir kareyi hızlı bir şekilde işleyebilirsiniz. Hareketlerin videoda ne zaman gerçekleştiğini belirlemek için karenin zaman damgasını kullanabilirsiniz.

Görevi çalıştırma

Hareket Tanıyıcı, çıkarımları tetiklemek için recognize() (koşu moduyla 'image') ve recognizeForVideo() (koşu moduyla 'video') yöntemlerini kullanır. Görev, verileri işler, el hareketlerini tanımaya çalışır ve ardından sonuçları bildirir.

Aşağıdaki kod, işlemenin görev modeliyle nasıl yürütüldüğünü gösterir:

Resim

const image = document.getElementById("image") as HTMLImageElement;
const gestureRecognitionResult = gestureRecognizer.recognize(image);

Video

await gestureRecognizer.setOptions({ runningMode: "video" });

let lastVideoTime = -1;
function renderLoop(): void {
  const video = document.getElementById("video");

  if (video.currentTime !== lastVideoTime) {
    const gestureRecognitionResult = gestureRecognizer.recognizeForVideo(video);
    processResult(gestureRecognitionResult);
    lastVideoTime = video.currentTime;
  }

  requestAnimationFrame(() => {
    renderLoop();
  });
}

Hareket Tanıyıcı recognize() ve recognizeForVideo() yöntemlerine yapılan çağrılar eşzamanlı olarak çalışır ve kullanıcı arayüzü iş parçacığını engeller. Video karelerindeki hareketleri cihazınızın kamerasından tanırsanız her tanıma, ana iş parçacığını engeller. recognize() ve recognizeForVideo() yöntemlerini başka bir iş parçacığında çalıştıracak web çalışanları uygulayarak bunu önleyebilirsiniz.

Bir Hareket Tanıyıcı görevi çalıştırmanın daha kapsamlı bir uygulaması için kod örneğine bakın.

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

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

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

Sonuçta elde edilen GestureRecognizerResult, dört bileşen içerir ve her bileşen bir dizidir. Bu dizide her öğe, algılanan tek bir elin algılanan sonucunu içerir.

Uygun Olduğu El

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

Algılanan ellerin tanınan hareket kategorileri.
Ö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.

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ıyıcı görevi oluşturmayla ilgili daha kapsamlı bir uygulama için kod örneğine bakın.