Web için hareket tanıma kılavuzu

MediaPipe Gesture Recognizer görevi, elle yapılan hareketleri gerçek zamanlı olarak tanımanıza olanak tanır. Ayrıca, tanınan elle yapılan hareket sonuçlarını ve algılanan ellerin el işaretlerini sağlar. Bu talimatlarda, web ve JavaScript uygulamaları için Hareket Tanıyıcı'nın nasıl kullanılacağı gösterilmektedir.

Bu görevin nasıl çalıştığını görmek için demoyu inceleyebilirsiniz. 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

Gesture Recognizer'ın örnek kodu, bu görevin JavaScript'te eksiksiz bir uygulamasını referans olarak sunar. 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 Gesture Recognizer örneğini görüntüleyebilir, çalıştırabilir ve düzenleyebilirsiniz.

Kurulum

Bu bölümde, geliştirme ortamınızı özellikle Hareket Tanıyıcı'yı kullanacak şekilde ayarlamayla ilgili temel adımlar açıklanmaktadır. Platform sürümü gereksinimleri de dahil olmak üzere web ve JavaScript geliştirme ortamınızı ayarlama hakkında genel bilgi için Web için kurulum kılavuzu'na bakın.

JavaScript paketleri

Gesture Recognizer kodu, MediaPipe @mediapipe/tasks-vision NPM paketi aracılığıyla kullanılabilir. Bu kitaplıkları, platform kurulum kılavuzundaki talimatları uygulayarak bulup indirebilirsiniz.

Gerekli paketleri NPM aracılığıyla aşağıdaki komutu kullanarak yükleyebilirsiniz:

npm install @mediapipe/tasks-vision

Görev kodunu bir içerik yayınlama ağı (CDN) hizmeti üzerinden içe aktarmak istiyorsanız 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.mjs"
    crossorigin="anonymous"></script>
</head>

Model

MediaPipe Gesture Recognizer görevi, bu görevle uyumlu eğitilmiş bir model gerektirir. İşaret Tanıyıcı için kullanılabilen eğitilmiş modeller hakkında daha fazla bilgi edinmek için görev genel bakışındaki Modeller bölümüne bakın.

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

<dev-project-root>/app/shared/models/

Görevi oluşturma

Görevleri çıkarım çalıştırmaya hazırlamak için Gesture Recognizer createFrom...() işlevlerinden birini kullanın. createFromModelPath() işlevini, eğitilmiş model dosyasına ait göreli veya mutlak bir yolla kullanın. Modeliniz zaten belleğe yüklendiyse createFromModelBuffer() yöntemini kullanabilirsiniz.

Aşağıdaki kod örneğinde, görevi ayarlamak için createFromOptions() işlevinin nasıl kullanılacağı gösterilmektedir. 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 için Yapılandırma seçenekleri başlıklı makaleyi inceleyin.

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

// 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 için mod.

VIDEO: Bir videonun veya bir kameradan gelen giriş verilerinin canlı yayınındaki kod çözülmüş kareler için mod.		 {IMAGE, VIDEO} IMAGE
num_hands GestureRecognizer ile en fazla sayıda el algılanabilir. Any integer > 0 1
min_hand_detection_confidence El algılamanın avuç içi algılama modelinde başarılı olarak kabul edilmesi için gereken minimum güven puanı. 0.0 - 1.0 0.5
min_hand_presence_confidence El işareti algılama modelinde el varlığı puanının minimum güven puanı. Hareket Tanıma Aracı'nın Video modunda ve Canlı yayın modunda, el belirgin işaret modelinden alınan el varlığı güven puanı bu eşiğin altındaysa avuç içi algılama modeli tetiklenir. Aksi takdirde, sonraki işaret noktası algılama için ellerin konumunu belirlemek üzere basit bir el takibi algoritması kullanılır. 0.0 - 1.0 0.5
min_tracking_confidence El takibinin başarılı kabul edilmesi için gereken minimum güven puanı. Bu, geçerli kare ile son karedeki eller arasındaki sınırlayıcı kutu IoU eşiğidir. Hareket Tanıyıcı'nın Video modunda ve Yayın modunda izleme başarısız olursa Hareket Tanıyıcı, el algılamayı tetikler. Aksi takdirde el algılama atlanır. 0.0 - 1.0 0.5
canned_gestures_classifier_options Hazır hareket 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ın yerel ayarı: TFLite Model Metadata aracılığıyla belirtilen görünen adlar için kullanılacak yerel ayar (varsa).
  • Maksimum sonuç sayısı: Döndürülecek en yüksek puanlı sınıflandırma sonuçlarının maksimum sayısı. Sayı < 0 ise mevcut tüm sonuçlar döndürülür.
  • Puan eşiği: 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 kümede olmayan sınıflandırma sonuçları filtrelenir. Reddetme listesiyle karşılıklı olarak hariç tutulur.
  • Kategori ret listesi: Kategori adlarının ret listesi. Boş değilse kategorisi bu kümede olan sınıflandırma sonuçları filtrelenir. İzin verilenler listesiyle birlikte kullanılamaz.
    		•
    • Görünen adların yerel ayarı: any string
    • Maksimum sonuç sayısı: 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ın yerel ayarı: "en"
    • Maksimum sonuç sayısı: -1
    • Puan eşiği: 0
    • Kategori izin verilenler listesi: boş
    • Kategori ret listesi: boş
    custom_gestures_classifier_options Özel hareket sınıflandırıcı davranışını yapılandırma seçenekleri.
  • Görünen adların yerel ayarı: TFLite Model Metadata aracılığıyla belirtilen görünen adlar için kullanılacak yerel ayar (varsa).
  • Maksimum sonuç sayısı: Döndürülecek en yüksek puanlı sınıflandırma sonuçlarının maksimum sayısı. Sayı < 0 ise mevcut tüm sonuçlar döndürülür.
  • Puan eşiği: 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 kümede olmayan sınıflandırma sonuçları filtrelenir. Reddetme listesiyle karşılıklı olarak hariç tutulur.
  • Kategori ret listesi: Kategori adlarının ret listesi. Boş değilse kategorisi bu kümede olan sınıflandırma sonuçları filtrelenir. İzin verilenler listesiyle birlikte kullanılamaz.
    		•
    • Görünen adların yerel ayarı: any string
    • Maksimum sonuç sayısı: 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ın yerel ayarı: "en"
    • Maksimum sonuç sayısı: -1
    • Puan eşiği: 0
    • Kategori izin verilenler listesi: boş
    • Kategori ret listesi: boş

    Verileri hazırlama

    Hareket Tanıyıcı, ana makine tarayıcısı tarafından desteklenen tüm biçimlerdeki resimlerde hareketleri tanıyabilir. Görev, yeniden boyutlandırma, döndürme ve değer normalleştirme dahil olmak üzere veri girişi ön işlemesini de gerçekleştirir. Videolardaki hareketleri tanımak için API'yi kullanarak her seferinde bir kareyi hızlıca işleyebilir ve 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() (çalıştırma modu 'image' ile) ve recognizeForVideo() (çalıştırma modu 'video' ile) yöntemlerini kullanır. Görev, verileri işler, el hareketlerini tanımaya çalışır ve sonuçları bildirir.

    Aşağıdaki kodda, görevi işleme modelini kullanarak işlemenin nasıl yürütüleceği gösterilmektedir:

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

    Gesture Recognizer 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. Bir cihazın kamerasından alınan video karelerindeki hareketleri tanırsanız her tanıma işlemi ana iş parçacığını engeller. recognize() ve recognizeForVideo() yöntemlerini başka bir iş parçacığında çalıştıracak web işçileri uygulayarak bunu önleyebilirsiniz.

    Hareket Tanıma görevi çalıştırmanın daha kapsamlı bir uygulaması için örneğe 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 sonucu nesnesi oluşturur. Sonuç nesnesi, resim koordinatlarında el işaretlerini, dünya koordinatlarında el işaretlerini, elin kullanımını(sol/sağ el) ve algılanan ellerin el hareketleri kategorilerini içerir.

    Aşağıda bu görevden elde edilen çıkış verilerine bir örnek verilmiştir:

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

    • El Tercihi

      El tercihi, algılanan ellerin sol mu 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 işareti vardır. x ve y koordinatları, sırasıyla resim genişliği ve yüksekliği ile [0.0, 1.0] aralığında normalleştirilir. z koordinatı, bilekteki derinliğin başlangıç noktası olduğu yer işareti derinliğini gösterir. Değer ne kadar küçük olursa önemli nokta kameraya o kadar yakın olur. z öğesinin büyüklüğü, yaklaşık olarak x ile aynı ölçeği kullanır.

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

      21 el işareti de dünya koordinatlarında gösterilir. Her işaret noktası, x, y ve z'den oluşur. Bunlar, başlangıç noktası elin geometrik merkezi olan, metre cinsinden gerçek dünya 3D koordinatlarını 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ştirilmiş hali gösterilmektedir:

    Başparmağı yukarı işareti yapan bir elin, el iskeleti yapısı haritası çıkarılmış hâli

    Hareket tanıma görevi oluşturma işleminin daha kapsamlı bir uygulaması için örneğe bakın.