אפשר להשתמש ב-ML Kit כדי לזהות ישויות בתמונה ולתייג אותן. ממשק ה-API הזה תומך במגוון רחב של מודלים לסיווג תמונות בהתאמה אישית. במאמר מודלים בהתאמה אישית עם ML Kit תוכלו למצוא הנחיות לגבי דרישות התאימות למודלים, איפה אפשר למצוא מודלים שעברו אימון מקדים ואיך לאמן מודלים משלכם.
יש שתי דרכים לשלב תוויות לתמונות במודלים בהתאמה אישית: צירוף של צינור עיבוד הנתונים כחלק מהאפליקציה או שימוש בצינור עיבוד נתונים לא מקובע שתלוי ב-Google Play Services. אם בוחרים את צינור עיבוד הנתונים הלא מקובצות, האפליקציה תהיה קטנה יותר. הפרטים מופיעים בטבלה שבהמשך.
בחבילה | לא מקובצים | |
---|---|---|
שם הספרייה | com.google.mlkit:image-labeling-custom | com.google.android.gms:play-services-mlkit-image-labeling-custom |
הטמעה | צינור עיבוד הנתונים מקושר באופן סטטי לאפליקציה בזמן ה-build. | מתבצעת הורדה דינמית של צינור עיבוד הנתונים דרך Google Play Services. |
גודל האפליקציה | הגדלה של כ-3.8MB. | הגדלה של כ-200KB. |
שעת האתחול | צינור עיבוד הנתונים זמין באופן מיידי. | יכול להיות שתצטרכו לחכות להורדת צינור עיבוד הנתונים לפני השימוש הראשון. |
שלב במחזור החיים של ה-API | זמינות לכלל המשתמשים (GA) | בטא |
יש שתי דרכים לשלב מודל מותאם אישית: לקבץ את המודל על ידי הוספתו לתיקיית הנכסים של האפליקציה, או להוריד אותו באופן דינמי מ-Firebase. הטבלה הבאה משווה בין שתי האפשרויות.
מודל בחבילה | מודל מתארח |
---|---|
המודל הוא חלק מ-APK של האפליקציה, ולכן הוא גדל. | המודל אינו חלק מה-APK שלך. כדי לארח את המשחק, אתם צריכים להעלות אותו ל-Firebase Machine Learning. |
הדגם זמין באופן מיידי, גם כשמכשיר Android במצב אופליין | המערכת מורידה את המודל על פי דרישה |
אין צורך בפרויקט Firebase | נדרש פרויקט Firebase |
כדי לעדכן את המודל, צריך לפרסם מחדש את האפליקציה | דחיפת עדכוני מודל מבלי לפרסם מחדש את האפליקציה |
אין בדיקות A/B מובנות | בדיקות A/B פשוטות עם הגדרת תצורה מרחוק ב-Firebase |
אני רוצה לנסות
- אפשר לעיין באפליקציית Vision למתחילים כדי לראות שימוש לדוגמה במודל הכלול, ובאפליקציה למתחילים של Automl כדי לראות דוגמה לשימוש במודל המתארח.
לפני שמתחילים
בקובץ
build.gradle
ברמת הפרויקט, חשוב לכלול את מאגר Maven של Google בקטעbuildscript
וגם בקטעallprojects
.מוסיפים את יחסי התלות של ספריות ML Kit ל-Android לקובץ ההדרגתיות ברמת האפליקציה של המודול, שהוא בדרך כלל
app/build.gradle
. תוכלו לבחור באחד מיחסי התלות הבאים בהתאם לצרכים שלכם:כדי לאחד את צינור עיבוד הנתונים עם האפליקציה:
dependencies { // ... // Use this dependency to bundle the pipeline with your app implementation 'com.google.mlkit:image-labeling-custom:17.0.2' }
כדי להשתמש בצינור עיבוד הנתונים ב-Google Play Services:
dependencies { // ... // Use this dependency to use the dynamically downloaded pipeline in Google Play Services implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta5' }
אם תבחרו להשתמש בצינור עיבוד הנתונים ב-Google Play Services, תוכלו להגדיר שהאפליקציה תוריד את צינור עיבוד הנתונים למכשיר באופן אוטומטי לאחר התקנת האפליקציה מחנות Play. כדי לעשות זאת, צריך להוסיף את ההצהרה הבאה לקובץ
AndroidManifest.xml
של האפליקציה:<application ...> ... <meta-data android:name="com.google.mlkit.vision.DEPENDENCIES" android:value="custom_ica" /> <!-- To use multiple downloads: android:value="custom_ica,download2,download3" --> </application>
אפשר גם לבדוק במפורש את הזמינות של צינור עיבוד הנתונים ולבקש הורדה דרך ModuleInstallClient API של Google Play Services.
אם לא תפעילו הורדות של צינורות בזמן ההתקנה או תבקשו הורדה מפורשת, תתבצע הורדה של צינור עיבוד הנתונים בפעם הראשונה שתפעילו את המתייג. בקשות שמבצעים לפני סיום ההורדה לא מניבות תוצאות.
כדי להוריד באופן דינמי מודל מ-Firebase, מוסיפים את התלות
linkFirebase
:כדי להוריד באופן דינמי מודל מ-Firebase, צריך להוסיף את התלות
linkFirebase
:dependencies { // ... // Image labeling feature with model downloaded from Firebase implementation 'com.google.mlkit:image-labeling-custom:17.0.2' // Or use the dynamically downloaded pipeline in Google Play Services // implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta5' implementation 'com.google.mlkit:linkfirebase:17.0.0' }
אם אתם רוצים להוריד מודל, הקפידו להוסיף את Firebase לפרויקט Android שלכם, אם עדיין לא עשיתם זאת. אין צורך לעשות זאת כשמקבצים את המודל.
1. טעינת המודל
הגדרת מקור של מודל מקומי
כדי לקבץ את המודל עם האפליקציה שלך:
מעתיקים את קובץ המודל (בדרך כלל מסתיים ב-
.tflite
או.lite
) לתיקייהassets/
של האפליקציה. (יכול להיות שקודם תצטרכו ליצור את התיקייה על ידי לחיצה ימנית על התיקייהapp/
, ולאחר מכן לחיצה על New > Folder > Assets Folder).לאחר מכן, צריך להוסיף את הקוד הבא לקובץ
build.gradle
של האפליקציה כדי לוודא ש-Gradle לא תדחס את קובץ המודל כשמפתחים את האפליקציה:android { // ... aaptOptions { noCompress "tflite" // or noCompress "lite" } }
קובץ המודל ייכלל בחבילת האפליקציה ויהיה זמין ל-ML Kit כנכס גולמי.
יוצרים אובייקט
LocalModel
, ומציינים את הנתיב לקובץ המודל:Kotlin
val localModel = LocalModel.Builder() .setAssetFilePath("model.tflite") // or .setAbsoluteFilePath(absolute file path to model file) // or .setUri(URI to model file) .build()
Java
LocalModel localModel = new LocalModel.Builder() .setAssetFilePath("model.tflite") // or .setAbsoluteFilePath(absolute file path to model file) // or .setUri(URI to model file) .build();
הגדרת מקור מודל שמתארח ב-Firebase
כדי להשתמש במודל באירוח מרחוק, צריך ליצור אובייקט RemoteModel
על ידי FirebaseModelSource
, ולציין את השם שהקציתם למודל כשפרסמתם אותו:
Kotlin
// Specify the name you assigned in the Firebase console. val remoteModel = CustomRemoteModel .Builder(FirebaseModelSource.Builder("your_model_name").build()) .build()
Java
// Specify the name you assigned in the Firebase console. CustomRemoteModel remoteModel = new CustomRemoteModel .Builder(new FirebaseModelSource.Builder("your_model_name").build()) .build();
לאחר מכן, מתחילים את המשימה של הורדת המודל, ומציינים את התנאים שבהם רוצים לאפשר הורדה. אם המודל לא נמצא במכשיר, או אם יש גרסה חדשה יותר של המודל, המשימה תוריד את המודל באופן אסינכרוני מ-Firebase:
Kotlin
val downloadConditions = DownloadConditions.Builder() .requireWifi() .build() RemoteModelManager.getInstance().download(remoteModel, downloadConditions) .addOnSuccessListener { // Success. }
Java
DownloadConditions downloadConditions = new DownloadConditions.Builder() .requireWifi() .build(); RemoteModelManager.getInstance().download(remoteModel, downloadConditions) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(@NonNull Task task) { // Success. } });
אפליקציות רבות מתחילות את משימת ההורדה בקוד האתחול שלהן, אבל תוכלו לעשות זאת בכל שלב לפני שתצטרכו להשתמש במודל.
הגדרת מתייג התמונות
אחרי שמגדירים את מקורות המודל, צריך ליצור אובייקט ImageLabeler
מאחד מהם.
אלו האפשרויות הזמינות:
אפשרויות | |
---|---|
confidenceThreshold
|
ציון מהימנות מינימלי של תוויות שזוהו. אם המדיניות לא מוגדרת, המערכת תשתמש בכל סף סיווג שצוין במטא-נתונים של המודל. אם המודל לא מכיל מטא-נתונים או אם המטא-נתונים לא מציינים סף מסווג, ייעשה שימוש בסף ברירת מחדל של 0.0. |
maxResultCount
|
מספר התוויות המקסימלי להחזרה. אם המדיניות לא מוגדרת, המערכת תשתמש בערך ברירת המחדל 10. |
אם יש לכם רק מודל בחבילה מקומית, פשוט יוצרים מתייג מהאובייקט LocalModel
:
Kotlin
val customImageLabelerOptions = CustomImageLabelerOptions.Builder(localModel) .setConfidenceThreshold(0.5f) .setMaxResultCount(5) .build() val labeler = ImageLabeling.getClient(customImageLabelerOptions)
Java
CustomImageLabelerOptions customImageLabelerOptions = new CustomImageLabelerOptions.Builder(localModel) .setConfidenceThreshold(0.5f) .setMaxResultCount(5) .build(); ImageLabeler labeler = ImageLabeling.getClient(customImageLabelerOptions);
אם יש לכם מודל באירוח מרוחק, תצטרכו לבדוק שהוא הורד לפני שמריצים אותו. אפשר לבדוק את הסטטוס של משימת הורדת המודל באמצעות ה-method isModelDownloaded()
של מנהל המודלים.
צריך לוודא זאת רק לפני הרצת המתייג, אבל אם יש לכם גם מודל באירוח מרחוק וגם מודל בחבילה מקומית, כדאי לבצע את הבדיקה הזו כשיוצרים את מתייג התמונות: אם הוא הורד מהמודל המרוחק, או מהמודל המקומי, כדאי ליצור מתייג מהמודל המרוחק.
Kotlin
RemoteModelManager.getInstance().isModelDownloaded(remoteModel) .addOnSuccessListener { isDownloaded -> val optionsBuilder = if (isDownloaded) { CustomImageLabelerOptions.Builder(remoteModel) } else { CustomImageLabelerOptions.Builder(localModel) } val options = optionsBuilder .setConfidenceThreshold(0.5f) .setMaxResultCount(5) .build() val labeler = ImageLabeling.getClient(options) }
Java
RemoteModelManager.getInstance().isModelDownloaded(remoteModel) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(Boolean isDownloaded) { CustomImageLabelerOptions.Builder optionsBuilder; if (isDownloaded) { optionsBuilder = new CustomImageLabelerOptions.Builder(remoteModel); } else { optionsBuilder = new CustomImageLabelerOptions.Builder(localModel); } CustomImageLabelerOptions options = optionsBuilder .setConfidenceThreshold(0.5f) .setMaxResultCount(5) .build(); ImageLabeler labeler = ImageLabeling.getClient(options); } });
אם יש לכם רק מודל שמתארח מרחוק, צריך להשבית את הפונקציונליות שקשורה למודל – למשל הצגת באפור או הסתרה של חלק מממשק המשתמש – עד שמוודאים שהמודל הורד. לשם כך, אפשר לצרף מאזין ל-method download()
של מנהל המודלים:
Kotlin
RemoteModelManager.getInstance().download(remoteModel, conditions) .addOnSuccessListener { // Download complete. Depending on your app, you could enable the ML // feature, or switch from the local model to the remote model, etc. }
Java
RemoteModelManager.getInstance().download(remoteModel, conditions) .addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(Void v) { // Download complete. Depending on your app, you could enable // the ML feature, or switch from the local model to the remote // model, etc. } });
2. הכנת התמונה לקלט
לאחר מכן, לכל תמונה שרוצים להוסיף לה תווית, יוצרים אובייקטInputImage
מהתמונה. מתייג התמונות פועל מהר יותר כשמשתמשים ב-Bitmap
או, אם משתמשים ב-camera2 API, ב-YUV_420_888 media.Image
מומלץ כשהדבר אפשרי.
ניתן ליצור אובייקט InputImage
ממקורות שונים, והסבר על כל אחד מהם מוסבר בהמשך.
באמצעות media.Image
כדי ליצור אובייקט InputImage
מאובייקט media.Image
, למשל כשמצלמים תמונה
ממצלמת של מכשיר, צריך להעביר את האובייקט media.Image
ואת
סיבוב התמונה אל InputImage.fromMediaImage()
.
אם אתם משתמשים בספריית
CameraX, המחלקות OnImageCapturedListener
ו-ImageAnalysis.Analyzer
תחשבות את ערך הסיבוב בשבילכם.
Kotlin
private class YourImageAnalyzer : ImageAnalysis.Analyzer { override fun analyze(imageProxy: ImageProxy) { val mediaImage = imageProxy.image if (mediaImage != null) { val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees) // Pass image to an ML Kit Vision API // ... } } }
Java
private class YourAnalyzer implements ImageAnalysis.Analyzer { @Override public void analyze(ImageProxy imageProxy) { Image mediaImage = imageProxy.getImage(); if (mediaImage != null) { InputImage image = InputImage.fromMediaImage(mediaImage, imageProxy.getImageInfo().getRotationDegrees()); // Pass image to an ML Kit Vision API // ... } } }
אם אין לך ספריית מצלמה שמספקת את מידת הסיבוב של התמונה, אפשר לחשב אותה לפי מידת הסיבוב של המכשיר ולפי הכיוון של חיישן המצלמה במכשיר:
Kotlin
private val ORIENTATIONS = SparseIntArray() init { ORIENTATIONS.append(Surface.ROTATION_0, 0) ORIENTATIONS.append(Surface.ROTATION_90, 90) ORIENTATIONS.append(Surface.ROTATION_180, 180) ORIENTATIONS.append(Surface.ROTATION_270, 270) } /** * Get the angle by which an image must be rotated given the device's current * orientation. */ @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP) @Throws(CameraAccessException::class) private fun getRotationCompensation(cameraId: String, activity: Activity, isFrontFacing: Boolean): Int { // Get the device's current rotation relative to its "native" orientation. // Then, from the ORIENTATIONS table, look up the angle the image must be // rotated to compensate for the device's rotation. val deviceRotation = activity.windowManager.defaultDisplay.rotation var rotationCompensation = ORIENTATIONS.get(deviceRotation) // Get the device's sensor orientation. val cameraManager = activity.getSystemService(CAMERA_SERVICE) as CameraManager val sensorOrientation = cameraManager .getCameraCharacteristics(cameraId) .get(CameraCharacteristics.SENSOR_ORIENTATION)!! if (isFrontFacing) { rotationCompensation = (sensorOrientation + rotationCompensation) % 360 } else { // back-facing rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360 } return rotationCompensation }
Java
private static final SparseIntArray ORIENTATIONS = new SparseIntArray(); static { ORIENTATIONS.append(Surface.ROTATION_0, 0); ORIENTATIONS.append(Surface.ROTATION_90, 90); ORIENTATIONS.append(Surface.ROTATION_180, 180); ORIENTATIONS.append(Surface.ROTATION_270, 270); } /** * Get the angle by which an image must be rotated given the device's current * orientation. */ @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP) private int getRotationCompensation(String cameraId, Activity activity, boolean isFrontFacing) throws CameraAccessException { // Get the device's current rotation relative to its "native" orientation. // Then, from the ORIENTATIONS table, look up the angle the image must be // rotated to compensate for the device's rotation. int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation(); int rotationCompensation = ORIENTATIONS.get(deviceRotation); // Get the device's sensor orientation. CameraManager cameraManager = (CameraManager) activity.getSystemService(CAMERA_SERVICE); int sensorOrientation = cameraManager .getCameraCharacteristics(cameraId) .get(CameraCharacteristics.SENSOR_ORIENTATION); if (isFrontFacing) { rotationCompensation = (sensorOrientation + rotationCompensation) % 360; } else { // back-facing rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360; } return rotationCompensation; }
לאחר מכן, מעבירים את האובייקט media.Image
ואת
ערך מעלה הסיבוב לערך InputImage.fromMediaImage()
:
Kotlin
val image = InputImage.fromMediaImage(mediaImage, rotation)
Java
InputImage image = InputImage.fromMediaImage(mediaImage, rotation);
שימוש ב-URI של קובץ
כדי ליצור אובייקט InputImage
מ-URI של קובץ, יש להעביר את ההקשר של האפליקציה ואת ה-URI של הקובץ אל
InputImage.fromFilePath()
. המדיניות הזו שימושית כשמשתמשים
ב-Intent של ACTION_GET_CONTENT
כדי לבקש מהמשתמש לבחור תמונה מאפליקציית הגלריה.
Kotlin
val image: InputImage try { image = InputImage.fromFilePath(context, uri) } catch (e: IOException) { e.printStackTrace() }
Java
InputImage image; try { image = InputImage.fromFilePath(context, uri); } catch (IOException e) { e.printStackTrace(); }
נעשה שימוש ב-ByteBuffer
או ב-ByteArray
כדי ליצור אובייקט InputImage
מ-ByteBuffer
או מ-ByteArray
, קודם צריך לחשב את המעלות
של סיבוב התמונה כפי שתואר קודם עבור קלט media.Image
.
לאחר מכן, יוצרים את האובייקט InputImage
עם המאגר או המערך, יחד עם הגובה, הרוחב, פורמט קידוד הצבע ומידת הסיבוב של התמונה:
Kotlin
val image = InputImage.fromByteBuffer( byteBuffer, /* image width */ 480, /* image height */ 360, rotationDegrees, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 ) // Or: val image = InputImage.fromByteArray( byteArray, /* image width */ 480, /* image height */ 360, rotationDegrees, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 )
Java
InputImage image = InputImage.fromByteBuffer(byteBuffer, /* image width */ 480, /* image height */ 360, rotationDegrees, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 ); // Or: InputImage image = InputImage.fromByteArray( byteArray, /* image width */480, /* image height */360, rotation, InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12 );
באמצעות Bitmap
כדי ליצור אובייקט InputImage
מאובייקט Bitmap
, צריך בהצהרה הבאה:
Kotlin
val image = InputImage.fromBitmap(bitmap, 0)
Java
InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);
התמונה מיוצגת על ידי אובייקט Bitmap
יחד עם מעלות סיבוב.
3. הפעלת מתייג התמונות
כדי להוסיף תוויות לאובייקטים בתמונה, צריך להעביר את האובייקט image
ל-method process()
של ImageLabeler
.
Kotlin
labeler.process(image) .addOnSuccessListener { labels -> // Task completed successfully // ... } .addOnFailureListener { e -> // Task failed with an exception // ... }
Java
labeler.process(image) .addOnSuccessListener(new OnSuccessListener<List<ImageLabel>>() { @Override public void onSuccess(List<ImageLabel> labels) { // Task completed successfully // ... } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { // Task failed with an exception // ... } });
4. קבלת מידע על ישויות עם תוויות
אם הפעולה להוספת תוויות לתמונה מצליחה, רשימה של אובייקטים מסוגImageLabel
מועברת לרכיב ה-listener. כל אובייקט ImageLabel
מייצג משהו שתויג בתמונה. אפשר לקבל את תיאור הטקסט של כל תווית (אם הם זמינים במטא-נתונים של קובץ המודל של TensorFlow Lite), את ציון המהימנות ואת האינדקס. לדוגמה:
Kotlin
for (label in labels) { val text = label.text val confidence = label.confidence val index = label.index }
Java
for (ImageLabel label : labels) { String text = label.getText(); float confidence = label.getConfidence(); int index = label.getIndex(); }
טיפים לשיפור הביצועים בזמן אמת
אם רוצים לתייג תמונות באפליקציה בזמן אמת, כדאי לפעול לפי ההנחיות הבאות כדי להשיג את קצב הפריימים הטוב ביותר:
- אם משתמשים ב-API
Camera
אוcamera2
, אפשר לווסת קריאות למתייג התמונות. אם מתפנה פריים חדש של וידאו בזמן שמתייג התמונות פועל, משחררים את המסגרת. כדי לראות דוגמה, אפשר לעיין בשיעורVisionProcessorBase
באפליקציה לדוגמה למתחילים. - אם אתם משתמשים ב-
CameraX
API, עליכם לוודא ששיטת הלחיצה החוזרת מוגדרת לערך ברירת המחדל שלהImageAnalysis.STRATEGY_KEEP_ONLY_LATEST
. האפשרות הזו מבטיחה שרק תמונה אחת תישלח לניתוח בכל פעם. אם מופקות תמונות נוספות בזמן שהמנתח עמוס, הן יושמטו באופן אוטומטי ולא ימתינו בתור למשלוח. לאחר סגירת התמונה שנכללת בניתוח על ידי קריאה ל-ImageProxy.close(), תישלח התמונה האחרונה הבאה. - אם משתמשים בפלט של מתייג התמונות כדי ליצור שכבת-על של גרפיקה בתמונת הקלט, קודם צריך לקבל את התוצאה מ-ML Kit, ואז לעבד את התמונה ואת שכבת-העל בשלב אחד. הפעולה הזו מעבדת את התצוגה על פני המסך
פעם אחת בלבד לכל מסגרת קלט. כדי לראות דוגמה, אפשר לעיין בכיתות
CameraSourcePreview
ו-GraphicOverlay
באפליקציה לדוגמה של 'מדריך למתחילים'. - אם משתמשים ב- Camera2 API, צריך לצלם תמונות בפורמט
ImageFormat.YUV_420_888
. אם משתמשים בגרסה הקודמת של Camera API, צריך לצלם תמונות בפורמטImageFormat.NV21
.