Panduan pengenalan gestur untuk Android

Tugas Pengenal Gestur MediaPipe memungkinkan Anda mengenali gestur tangan secara real time, dan memberikan hasil gestur tangan yang dikenali dan penanda tangan tangan yang terdeteksi. Petunjuk ini menunjukkan cara menggunakan Pengenal Gestur dengan aplikasi Android. Contoh kode yang dijelaskan dalam petunjuk ini tersedia di GitHub.

Anda dapat melihat cara kerja tugas ini dengan melihat demo web. Untuk mengetahui informasi selengkapnya terkait kemampuan, model, dan opsi konfigurasi. tugas ini, lihat Ringkasan.

Contoh kode

Kode contoh Tugas MediaPipe adalah implementasi sederhana dari Pengenal Gestur untuk Android. Contoh ini menggunakan kamera pada perangkat Android fisik untuk terus mendeteksi gerakan tangan, dan juga dapat menggunakan gambar dan video dari galeri perangkat untuk mendeteksi {i>gesture <i}secara statis.

Anda dapat menggunakan aplikasi ini sebagai titik awal untuk aplikasi Android Anda sendiri, atau merujuk ke sana saat memodifikasi aplikasi yang ada. Kode contoh Pengenal Gestur dihosting di GitHub.

Mendownload kode

Petunjuk berikut menunjukkan cara membuat salinan lokal dari contoh kode menggunakan alat command line git.

Untuk mendownload kode contoh:

1. Clone repositori git menggunakan perintah berikut:

   git clone https://github.com/google-ai-edge/mediapipe-samples
   

2. Secara opsional, konfigurasikan instance git Anda untuk menggunakan checkout sparse, jadi Anda hanya memiliki file untuk aplikasi contoh Pengenal Gestur:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/gesture_recognizer/android
   

Setelah membuat versi lokal dari kode contoh, Anda dapat mengimpor project ke Android Studio dan menjalankan aplikasi. Untuk mendapatkan petunjuk, lihat Panduan Penyiapan untuk Android.

Komponen utama

File berikut berisi kode penting untuk gestur tangan ini aplikasi contoh pengenalan:

• GestureRecognizerHelper.kt - Melakukan inisialisasi pengenal gestur serta menangani model dan delegasi pilihan.
• MainActivity.kt - Mengimplementasikan aplikasi, termasuk memanggil GestureRecognizerHelper dan GestureRecognizerResultsAdapter.
• GestureRecognizerResultsAdapter.kt - Menangani dan memformat hasil.

Penyiapan

Bagian ini menjelaskan langkah-langkah utama untuk menyiapkan lingkungan pengembangan dan kode project secara khusus untuk menggunakan Pengenal Gestur. Untuk informasi umum tentang menyiapkan lingkungan pengembangan untuk menggunakan tugas MediaPipe, termasuk persyaratan versi platform, lihat Panduan penyiapan untuk Android.

Dependensi

Tugas Pengenal Gestur menggunakan com.google.mediapipe:tasks-vision library. Tambahkan dependensi ini ke file build.gradle aplikasi Android Anda:

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

Model

Tugas Pengenal Gestur MediaPipe memerlukan paket model terlatih yang kompatibel dengan untuk melakukan tugas ini. Untuk mengetahui informasi selengkapnya tentang model terlatih yang tersedia untuk Pengenal Gestur, lihat ringkasan tugas bagian Model.

Pilih dan download model, lalu simpan dalam direktori project Anda:

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

Tentukan jalur model dalam parameter ModelAssetPath. Di kolom kode contoh, model ditentukan di dalam GestureRecognizerHelper.kt file:

baseOptionBuilder.setModelAssetPath(MP_RECOGNIZER_TASK)

Membuat tugas

Tugas Pengenal Gestur MediaPipe menggunakan fungsi createFromOptions() untuk menetapkan tugasnya. Fungsi createFromOptions() menerima nilai untuk opsi konfigurasi. Untuk informasi lebih lanjut tentang opsi konfigurasi, lihat Opsi konfigurasi.

Pengenal Gestur mendukung 3 jenis data input: gambar diam, file video, dan untuk streaming video live. Anda perlu menentukan mode berjalan yang sesuai dengan tipe data input Anda saat membuat tugas. Pilih tab yang sesuai dengan tipe data input Anda untuk melihat cara membuat tugas dan menjalankan inferensi.

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)
    

Implementasi kode contoh Pengenal Gestur memungkinkan pengguna beralih antar mode pemrosesan. Pendekatan ini membuat kode pembuatan tugas lebih rumit dan mungkin tidak sesuai untuk kasus penggunaan Anda. Anda dapat melihat kode ini di fungsi setupGestureRecognizer() dalam GestureRecognizerHelper.kt .

Opsi konfigurasi

Tugas ini memiliki opsi konfigurasi berikut untuk aplikasi Android:

Menyiapkan data

Pengenal Gestur berfungsi dengan gambar, file video, dan video live stream. Tugas menangani pra-pemrosesan input data, termasuk mengubah ukuran, rotasi, dan nilai proses normalisasi.

Kode berikut menunjukkan cara menyerahkan data untuk diproses. Tes contoh mencakup detail tentang cara menangani data dari gambar, file video, dan streaming video.

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

Di kolom Kode contoh Pengenal Gestur, persiapan data ditangani di GestureRecognizerHelper.kt .

Menjalankan tugas

Pengenal Gestur menggunakan recognize, recognizeForVideo, dan recognizeAsync fungsi untuk memicu inferensi. Untuk pengenalan {i>gesture, <i}melibatkan pra-pemrosesan data input, mendeteksi tangan dalam gambar, mendeteksi tangan {i>landmark<i}, dan mengenali {i>gesture <i}tangan dari {i>landmark<i}.

Kode berikut menunjukkan cara mengeksekusi pemrosesan dengan model tugas. Sampel ini mencakup detail tentang cara menangani data dari gambar, {i>file<i} video, dan streaming video live.

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)
    

Perhatikan hal berikut:

• Saat dalam mode video atau mode live stream, Anda juga harus memberikan stempel waktu {i>frame<i} input ke tugas Pengenal Gestur.
• Saat dijalankan dalam mode gambar atau video, tugas Pengenal Gestur akan memblokir utas saat ini hingga selesai memproses gambar input atau {i>frame<i}. Untuk menghindari pemblokiran antarmuka pengguna, jalankan pemrosesan dalam di thread latar belakang.
• Saat berjalan dalam mode live stream, tugas Pengenal Gestur tidak akan diblokir thread saat ini tetapi langsung kembali. Fungsi ini akan memanggil hasilnya pemroses dengan hasil pengenalan setiap kali ia selesai memproses {i>frame<i} input. Jika fungsi pengenalan dipanggil saat Pengenal Gestur sedang sibuk memproses {i>frame<i} lain, tugas akan mengabaikan {i>frame<i} input baru.

Di kolom Kode contoh Pengenal Gestur, recognize, recognizeForVideo, dan Fungsi recognizeAsync ditentukan di GestureRecognizerHelper.kt .

Menangani dan menampilkan hasil

Pengenal Gestur menghasilkan objek hasil deteksi gestur untuk setiap pengenalan objek. Objek hasil berisi penanda tangan dalam koordinat gambar, penanda tangan dalam koordinat dunia, tangan kiri(tangan kiri/kanan), dan tangan kategori {i>gesture <i}dari tangan yang terdeteksi.

Berikut ini contoh data output dari tugas ini:

GestureRecognizerResult yang dihasilkan berisi empat komponen, dan setiap komponen adalah array, dengan setiap elemen berisi hasil yang terdeteksi dari satu tangan yang terdeteksi.

• Kecenderungan penggunaan tangan

  Kecenderungan penggunaan tangan mewakili apakah tangan yang terdeteksi adalah tangan kiri atau kanan.

• Gestur

  Kategori gestur yang dikenali dari tangan yang terdeteksi.

• Tempat terkenal

  Ada 21 penanda tangan, masing-masing terdiri dari koordinat x, y, dan z. Tujuan Koordinat x dan y dinormalkan ke [0,0, 1,0] berdasarkan lebar gambar dan tinggi masing-masing. Koordinat z mewakili kedalaman tempat terkenal, dengan kedalaman di pergelangan tangan menjadi asalnya. Semakin kecil nilainya, maka penanda ke kamera. Besarnya z menggunakan skala yang kurang lebih sama dengan x.

• Landmark Dunia

  Landmark 21 tangan juga ditampilkan dalam koordinat dunia. Setiap tempat terkenal terdiri dari x, y, dan z, yang mewakili koordinat 3D dunia nyata di meter dengan titik asal di pusat geometris tangan.

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)

Gambar berikut menunjukkan visualisasi output tugas:

Di kolom Kode contoh Pengenal Gestur, class GestureRecognizerResultsAdapter dalam GestureRecognizerResultsAdapter.kt yang menangani hasilnya.