Tugas MediaPipe Image Embedder memungkinkan Anda mengonversi data gambar menjadi representasi numerik untuk menyelesaikan tugas pemrosesan gambar terkait ML, seperti membandingkan kemiripan dua gambar. Petunjuk ini menunjukkan cara menggunakan Penyemat Gambar dengan aplikasi Android.
Untuk mengetahui informasi selengkapnya tentang kemampuan, model, dan opsi konfigurasi tugas ini, lihat Ringkasan.
Contoh kode
Kode contoh Tugas MediaPipe adalah implementasi sederhana aplikasi Penyemat Gambar untuk Android. Contoh ini menggunakan kamera pada perangkat Android fisik untuk menanamkan gambar secara terus-menerus, dan juga dapat menjalankan penyemat pada file gambar yang disimpan di perangkat.
Anda dapat menggunakan aplikasi sebagai titik awal untuk aplikasi Android Anda sendiri, atau merujuk ke aplikasi tersebut saat memodifikasi aplikasi yang sudah ada. Kode contoh Image Embedder dihosting di GitHub.
Mendownload kode
Petunjuk berikut menunjukkan cara membuat salinan lokal dari kode contoh menggunakan alat command line git.
Untuk mendownload kode contoh:
- Clone repositori git menggunakan perintah berikut:
git clone https://github.com/google-ai-edge/mediapipe-samples
- Secara opsional, konfigurasikan instance git untuk menggunakan checkout sparse sehingga Anda hanya memiliki
file untuk aplikasi contoh Penyemat Gambar:
cd mediapipe git sparse-checkout init --cone git sparse-checkout set examples/image_embedder/android
Setelah membuat versi lokal dari kode contoh, Anda dapat mengimpor project ke Android Studio dan menjalankan aplikasi. Untuk mengetahui petunjuknya, lihat Panduan Penyiapan untuk Android.
Komponen utama
File berikut berisi kode penting untuk aplikasi contoh penyemat gambar ini:
- ImageEmbedderHelper.kt: Melakukan inisialisasi penyemat gambar dan menangani pemilihan model dan delegasi.
- MainActivity.kt: Mengimplementasikan aplikasi dan menyusun komponen antarmuka pengguna.
Penyiapan
Bagian ini menjelaskan langkah-langkah utama untuk menyiapkan lingkungan pengembangan dan membuat kode project agar dapat menggunakan Image Embedder. Guna mengetahui informasi umum tentang cara menyiapkan lingkungan pengembangan untuk menggunakan tugas MediaPipe, termasuk persyaratan versi platform, lihat Panduan penyiapan untuk Android.
Dependensi
Penyemat Gambar menggunakan library com.google.mediapipe:tasks-vision
. Tambahkan dependensi
ini ke file build.gradle
project pengembangan aplikasi Android Anda.
Impor dependensi yang diperlukan dengan kode berikut:
dependencies {
...
implementation 'com.google.mediapipe:tasks-vision:latest.release'
}
Model
Tugas MediaPipe Image Embedder memerlukan model terlatih yang kompatibel dengan tugas ini. Untuk mengetahui informasi selengkapnya tentang model terlatih yang tersedia untuk Penyemat Gambar, lihat bagian Model ringkasan tugas.
Pilih dan download model, lalu simpan dalam direktori project:
<dev-project-root>/src/main/assets
Tentukan jalur model dalam parameter ModelAssetPath
. Dalam
kode contoh, model ditetapkan dalam fungsi setupImageEmbedder()
di file
ImageEmbedderHelper.kt:
Gunakan metode BaseOptions.Builder.setModelAssetPath()
untuk menentukan jalur yang digunakan oleh model. Metode ini dirujuk dalam contoh kode di bagian
berikutnya.
Membuat tugas
Anda dapat menggunakan fungsi createFromOptions
untuk membuat tugas. Fungsi
createFromOptions
menerima opsi konfigurasi untuk menetapkan opsi
penyemat. Untuk informasi selengkapnya tentang opsi konfigurasi, lihat Ringkasan Konfigurasi.
Tugas Penyemat Gambar mendukung 3 jenis data input: gambar diam, file video, dan streaming video live. Anda perlu menentukan mode berjalan yang sesuai dengan jenis data input saat membuat tugas. Pilih tab yang sesuai dengan jenis data input Anda untuk melihat cara membuat tugas dan menjalankan inferensi.
Gambar
ImageEmbedderOptions options = ImageEmbedderOptions.builder() .setBaseOptions( BaseOptions.builder().setModelAssetPath("model.tflite").build()) .setQuantize(true) .setRunningMode(RunningMode.IMAGE) .build(); imageEmbedder = ImageEmbedder.createFromOptions(context, options);
Video
ImageEmbedderOptions options = ImageEmbedderOptions.builder() .setBaseOptions( BaseOptions.builder().setModelAssetPath("model.tflite").build()) .setQuantize(true) .setRunningMode(RunningMode.VIDEO) .build(); imageEmbedder = ImageEmbedder.createFromOptions(context, options);
Live stream
ImageEmbedderOptions options = ImageEmbedderOptions.builder() .setBaseOptions( BaseOptions.builder().setModelAssetPath("model.tflite").build()) .setQuantize(true) .setRunningMode(RunningMode.LIVE_STREAM) .setResultListener((result, inputImage) -> { // Process the embedding result here. }) .build(); imageEmbedder = ImageEmbedder.createFromOptions(context, options);
Contoh implementasi kode memungkinkan pengguna beralih antarmode
pemrosesan. Pendekatan ini membuat kode pembuatan tugas lebih rumit dan mungkin tidak
sesuai untuk kasus penggunaan Anda. Anda dapat melihat kode ini dalam
fungsi setupImageEmbedder()
di
file
ImageEmbedderHelper.kt.
Opsi konfigurasi
Tugas ini memiliki opsi konfigurasi berikut untuk aplikasi Android:
Nama Opsi | Deskripsi | Rentang Nilai | Nilai Default |
---|---|---|---|
runningMode |
Menetapkan mode berjalan untuk tugas. Ada tiga
mode: IMAGE: Mode untuk input gambar tunggal. VIDEO: Mode untuk frame video yang didekode. LIVE_STREAM: Mode untuk livestream data input, seperti dari kamera. Dalam mode ini, resultListener harus dipanggil untuk menyiapkan pemroses yang menerima hasil secara asinkron. |
{IMAGE, VIDEO, LIVE_STREAM } |
IMAGE |
l2_normalize |
Apakah akan menormalisasi vektor fitur yang ditampilkan dengan norma L2. Gunakan opsi ini hanya jika model belum berisi TFLite Op L2_NORMALIZATION native. Dalam kebanyakan kasus, hal ini sudah terjadi dan normalisasi L2 dicapai melalui inferensi TFLite tanpa memerlukan opsi ini. | Boolean |
False |
quantize |
Apakah embedding yang ditampilkan harus dikuantisasi ke byte melalui kuantisasi skalar. Embedding secara implisit diasumsikan sebagai norma satuan dan oleh karena itu, setiap dimensi dijamin memiliki nilai dalam [-1.0, 1.0]. Gunakan opsi l2_normalize jika tidak demikian. | Boolean |
False |
resultListener |
Menetapkan pemroses hasil untuk menerima hasil embedding
secara asinkron saat Penyemat Gambar berada dalam mode
live stream. Hanya dapat digunakan saat mode lari disetel ke LIVE_STREAM |
T/A | Tidak ditetapkan |
errorListener |
Menetapkan pemroses error opsional. | T/A | Tidak ditetapkan |
Menyiapkan data
Image Embedder berfungsi dengan gambar, file video, dan video live stream. Tugas ini menangani prapemrosesan input data, termasuk pengubahan ukuran, rotasi, dan normalisasi nilai.
Anda harus mengonversi gambar atau frame input menjadi
objek com.google.mediapipe.framework.image.MPImage
sebelum meneruskannya ke
tugas Image Embedder.
Gambar
import com.google.mediapipe.framework.image.BitmapImageBuilder; import com.google.mediapipe.framework.image.MPImage; // Load an image on the user’s device as a Bitmap object using BitmapFactory. // Convert an Android’s Bitmap object to a MediaPipe’s Image object. Image mpImage = new BitmapImageBuilder(bitmap).build();
Video
import com.google.mediapipe.framework.image.BitmapImageBuilder; import com.google.mediapipe.framework.image.MPImage; // Load a video file on the user's device using MediaMetadataRetriever // From the video’s metadata, load the METADATA_KEY_DURATION and // METADATA_KEY_VIDEO_FRAME_COUNT value. You’ll need them // to calculate the timestamp of each frame later. // Loop through the video and load each frame as a Bitmap object. // Convert the Android’s Bitmap object to a MediaPipe’s Image object. Image mpImage = new BitmapImageBuilder(frame).build();
Live stream
import com.google.mediapipe.framework.image.MediaImageBuilder; import com.google.mediapipe.framework.image.MPImage; // Create a CameraX’s ImageAnalysis to continuously receive frames // from the device’s camera. Configure it to output frames in RGBA_8888 // format to match with what is required by the model. // For each Android’s ImageProxy object received from the ImageAnalysis, // extract the encapsulated Android’s Image object and convert it to // a MediaPipe’s Image object. android.media.Image mediaImage = imageProxy.getImage() Image mpImage = new MediaImageBuilder(mediaImage).build();
Dalam kode contoh, persiapan data ditangani di file ImageEmbedderHelper.kt.
Menjalankan tugas
Anda dapat memanggil fungsi embed
yang sesuai dengan mode yang berjalan untuk memicu
inferensi. Image Embedder API menampilkan vektor embedding untuk gambar
input atau frame.
Gambar
ImageEmbedderResult embedderResult = imageEmbedder.embed(image);
Video
// Calculate the timestamp in milliseconds of the current frame. long frame_timestamp_ms = 1000 * video_duration * frame_index / frame_count; // Run inference on the frame. ImageEmbedderResult embedderResult = imageEmbedder.embedForVideo(image, frameTimestampMs);
Live stream
// Run inference on the frame. The embedding results will be available // via the `resultListener` provided in the `ImageEmbedderOptions` when // the image embedder was created. imageEmbedder.embedAsync(image, frameTimestampMs);
Perhatikan hal berikut:
- Saat berjalan dalam mode video atau mode live stream, Anda juga harus memberikan stempel waktu frame input ke tugas Penyemat Gambar.
- Saat berjalan dalam mode gambar atau video, tugas Penyemat Gambar akan memblokir thread saat ini hingga selesai memproses gambar atau bingkai input. Untuk menghindari pemblokiran thread saat ini, jalankan pemrosesan di thread latar belakang.
- Saat dijalankan dalam mode live stream, tugas Penyemat Gambar tidak memblokir
thread saat ini, tetapi langsung ditampilkan. Metode ini akan memanggil pemroses hasilnya dengan hasil deteksi setiap kali selesai memproses frame input. Jika fungsi
embedAsync
dipanggil saat tugas Image Embedder sedang sibuk memproses frame lain, tugas tersebut akan mengabaikan frame input baru.
Dalam kode contoh, fungsi embed
ditentukan dalam file
ImageEmbedderHelper.kt.
Menangani dan menampilkan hasil
Setelah menjalankan inferensi, tugas Image Embedder akan menampilkan objek ImageEmbedderResult
yang berisi daftar embedding (floating point atau
terkuantisasi skalar) untuk gambar input.
Berikut ini contoh data output dari tugas ini:
ImageEmbedderResult:
Embedding #0 (sole embedding head):
float_embedding: {0.0, 0.0, ..., 0.0, 1.0, 0.0, 0.0, 2.0}
head_index: 0
Hasil ini diperoleh dengan menyematkan gambar berikut:
Anda dapat membandingkan kesamaan dua embedding menggunakan fungsi ImageEmbedder.cosineSimilarity
. Lihat kode berikut sebagai contoh.
// Compute cosine similarity.
double similarity = ImageEmbedder.cosineSimilarity(
result.embeddingResult().embeddings().get(0),
otherResult.embeddingResult().embeddings().get(0));