يمكنك استخدام حزمة تعلّم الآلة للتعرّف على الكيانات في صورة وتصنيفها. تتيح واجهة برمجة التطبيقات هذه استخدام مجموعة كبيرة من نماذج تصنيف الصور المخصّصة. من فضلك يمكنك الاطّلاع على النماذج المخصّصة باستخدام حزمة تعلُّم الآلة للحصول على إرشادات حول ومتطلبات توافق النماذج، ومكان العثور على النماذج المُدرَّبة مسبقًا، وكيفية تدريب نماذجك الخاصة.
هناك طريقتان لدمج تصنيف الصور مع النماذج المخصّصة: وهما التجميع كجزء من تطبيقك، أو باستخدام مسار غير مجمّع يعتمد على على "خدمات Google Play" إذا اخترت المسار غير المجمّع، فسيتم أصغر. انظر الجدول ادناه للتعرُّف على التفاصيل.
مُجمَّعة | غير مجمعة | |
---|---|---|
اسم المكتبة | com.google.mlkit:image-labeling-custom | com.google.android.gms:play-services-mlkit-image-labeling-custom |
التنفيذ | يكون مسار التنفيذ مرتبطًا بشكلٍ ثابت بتطبيقك في وقت الإصدار. | يتم تنزيل مسار التعلّم ديناميكيًا من خلال "خدمات Google Play". |
حجم التطبيق | زيادة الحجم بمقدار 3.8 ميغابايت تقريبًا | زيادة في الحجم بمقدار 200 كيلوبايت تقريبًا. |
وقت الإعداد | تتوفر الأنابيب على الفور. | قد تضطر إلى الانتظار حتى يتم تنزيل مسار العملية قبل الاستخدام لأول مرة. |
مرحلة دورة حياة واجهة برمجة التطبيقات | مدى التوفّر للجمهور العام (GA) | إصدار تجريبي |
هناك طريقتان لدمج نموذج مخصّص: تجميع النموذج حسب وضعه داخل مجلد مواد العرض في التطبيق أو تنزيله ديناميكيًا من Firebase. يقارن الجدول التالي بين هذين الخيارين.
نموذج مجمعة | النموذج المستضاف |
---|---|
هذا النموذج هو جزء من حزمة APK الخاصة بتطبيقك، ما يؤدي إلى زيادة حجمه. | النموذج ليس جزءًا من حزمة APK. تتم استضافته عن طريق التحميل إلى تعلُّم الآلة من Firebase: |
يتوفّر الطراز على الفور، حتى في حال عدم اتصال جهاز Android بالإنترنت. | يتم تنزيل النموذج عند الطلب. |
لا حاجة إلى مشروع على Firebase | يتطلب توفُّر مشروع في Firebase |
يجب إعادة نشر تطبيقك لتحديث النموذج. | نشر تحديثات النموذج بدون إعادة نشر التطبيق |
ما مِن اختبار A/B مدمج. | اختبار A/B سهل باستخدام ميزة الإعداد عن بُعد في Firebase |
جرّبه الآن
- الاطّلاع على تطبيق Vision Quickstart للحصول على مثال على استخدام النموذج المجمّع تشغيل تطبيق Quickstart تلقائيًا مثال على استخدام النموذج المستضاف.
قبل البدء
في ملف
build.gradle
على مستوى المشروع، تأكَّد من تضمين مستودع Maven التابع لشركة Google في كل منbuildscript
أقسامallprojects
أضِف ملحقات مكتبات ML Kit على Android إلى ملف Gradle على مستوى التطبيق، ويكون عادةً
app/build.gradle
. اختَر أحد الخيارات التالية: التبعيات التالية بناءً على احتياجاتك:لإنشاء حزمة مع تطبيقك:
dependencies { // ... // Use this dependency to bundle the pipeline with your app implementation 'com.google.mlkit:image-labeling-custom:17.0.3' }
بالنسبة إلى استخدام مسار التنفيذ في "خدمات Google Play":
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"، يمكنك: اضبط تطبيقك لتنزيل مسار التعلّم تلقائيًا إلى الجهاز بعد تم تثبيت تطبيقك من "متجر 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"
في حال عدم تفعيل عمليات تنزيل مسار وقت التثبيت أو طلب تنزيل فاضح، ويتم تنزيل المسار في أول مرة تقوم فيها بتشغيل أداة التصنيف. الطلبات التي تقدّمها قبل اكتمال التنزيل لا ينتج عنها أي نتائج.
أضِف الاعتمادية
linkFirebase
إذا أردت تنزيل ملف النموذج من Firebase:لتنزيل نموذج من Firebase ديناميكيًا، أضِف
linkFirebase
. التبعية:dependencies { // ... // Image labeling feature with model downloaded from Firebase implementation 'com.google.mlkit:image-labeling-custom:17.0.3' // 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/
، ثم النقر على جديد > مجلد > مجلد مواد العرض).بعد ذلك، أضِف ما يلي إلى ملف
build.gradle
الخاص بتطبيقك للتأكّد من ذلك. لا تضغط Gradle ملف النموذج عند إنشاء التطبيق:android { // ... aaptOptions { noCompress "tflite" // or noCompress "lite" } }
سيتم تضمين ملف النموذج في حزمة التطبيق وسيكون متاحًا في مجموعة أدوات تعلُّم الآلة. كمادة عرض أولية
أنشِئ عنصر
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);
فإذا كان لديك نموذج مستضاف عن بُعد، فعليك التحقق من أنه
تم تنزيله قبل تشغيله. يمكنك التحقّق من حالة تنزيل النموذج
باستخدام طريقة 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); } });
وإذا كان لديك نموذج مستضاف عن بُعد فقط، يجب إيقاف النموذج المرتبط بالنموذج
وظائف - على سبيل المثال، الظهور باللون الرمادي أو إخفاء جزء من واجهة المستخدم - حتى
التأكد من تنزيل النموذج. يمكنك إجراء ذلك من خلال إرفاق مستمع
إلى طريقة 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()
يكون ذلك مفيدًا عندما
يجب استخدام هدف 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
إلى ImageLabeler
طريقة process()
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
.
يتم تمرير الكائنات إلى مستمع النجاح. ويمثل كل عنصر 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(); }
نصائح لتحسين الأداء في الوقت الفعلي
إذا أردت تصنيف الصور في تطبيق في الوقت الفعلي، فاتبع هذه الإرشادات اللازمة لتحقيق أفضل عدد من اللقطات في الثانية:
- إذا كنت تستخدم
Camera
أوcamera2
واجهة برمجة التطبيقات، التحكم في المكالمات الموجهة إلى أداة تصنيف الصور. إذا ظهر فيديو جديد يصبح الإطار متاحًا أثناء تشغيل أداة تصنيف الصور، أفلِت الإطار. يمكنك الاطّلاع على صف واحد (VisionProcessorBase
) في نموذج تطبيق Quickstart كمثال. - في حال استخدام
CameraX
API: تأكَّد من ضبط استراتيجية الضغط العكسي على قيمتها التلقائيةImageAnalysis.STRATEGY_KEEP_ONLY_LATEST
وهذا يضمن تسليم صورة واحدة فقط للتحليل في كل مرة. إذا كانت المزيد من الصور يتم إنتاجها عندما يكون المحلل مشغولاً، فسيتم إسقاطها تلقائيًا ولن يتم وضعها في قائمة الانتظار التسليم. بمجرد إغلاق الصورة التي يتم تحليلها عن طريق استدعاء ImageProxy.Close()، سيتم تسليم الصورة التالية الأحدث. - إذا كنت تستخدم مخرجات أداة تصنيف الصور لتراكب الرسومات على
الصورة المدخلة، والحصول أولاً على النتيجة من ML Kit، ثم عرض الصورة
وتراكبها في خطوة واحدة. يتم عرض هذا المحتوى على سطح الشاشة.
مرة واحدة فقط لكل إطار إدخال يمكنك الاطّلاع على
CameraSourcePreview
وGraphicOverlay
صفًا في نموذج تطبيق Quickstart كمثال. - في حال استخدام واجهة برمجة التطبيقات Camera2 API، يمكنك التقاط الصور في
تنسيق
ImageFormat.YUV_420_888
إذا كنت تستخدم واجهة برمجة التطبيقات للكاميرا القديمة، يمكنك التقاط الصور في تنسيقImageFormat.NV21