تصنيف الصور باستخدام نموذج مخصص على Android

يمكنك استخدام حزمة تعلّم الآلة للتعرّف على الكيانات في صورة وتصنيفها. تتيح واجهة برمجة التطبيقات هذه استخدام مجموعة كبيرة من نماذج تصنيف الصور المخصّصة. من فضلك يمكنك الاطّلاع على النماذج المخصّصة باستخدام حزمة تعلُّم الآلة للحصول على إرشادات حول ومتطلبات توافق النماذج، ومكان العثور على النماذج المُدرَّبة مسبقًا، وكيفية تدريب نماذجك الخاصة.

هناك طريقتان لدمج تصنيف الصور مع النماذج المخصّصة: وهما التجميع كجزء من تطبيقك، أو باستخدام مسار غير مجمّع يعتمد على على "خدمات Google Play" إذا اخترت المسار غير المجمّع، فسيتم أصغر. انظر الجدول ادناه للتعرُّف على التفاصيل.

هناك طريقتان لدمج نموذج مخصّص: تجميع النموذج حسب وضعه داخل مجلد مواد العرض في التطبيق أو تنزيله ديناميكيًا من Firebase. يقارن الجدول التالي بين هذين الخيارين.

جرّبه الآن

• الاطّلاع على تطبيق Vision Quickstart للحصول على مثال على استخدام النموذج المجمّع تشغيل تطبيق Quickstart تلقائيًا مثال على استخدام النموذج المستضاف.

قبل البدء

1. في ملف build.gradle على مستوى المشروع، تأكَّد من تضمين مستودع Maven التابع لشركة Google في كل من buildscript أقسام allprojects

2. أضِف ملحقات مكتبات 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'
   }
   

3. إذا اخترت استخدام مسار التعلّم في "خدمات 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"

   في حال عدم تفعيل عمليات تنزيل مسار وقت التثبيت أو طلب تنزيل فاضح، ويتم تنزيل المسار في أول مرة تقوم فيها بتشغيل أداة التصنيف. الطلبات التي تقدّمها قبل اكتمال التنزيل لا ينتج عنها أي نتائج.

4. أضِف الاعتمادية 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'
   }
   

5. إذا كنت تريد تنزيل نموذج، تأكد من إضافة Firebase إلى مشروع Android إذا لم تكن قد قمت بذلك بالفعل. هذه العملية غير مطلوبة عند دمج النموذج.

1. تحميل النموذج

إعداد مصدر نموذج محلي

لتجميع النموذج مع التطبيق:

1. انسخ ملف النموذج (الذي ينتهي عادةً بالأرقام .tflite أو .lite) إلى ملف تطبيقك. المجلد "assets/". (قد تحتاج إلى إنشاء المجلد أولاً عن طريق النقر بزر الماوس الأيمن على المجلد app/، ثم النقر على جديد > مجلد > مجلد مواد العرض).

2. بعد ذلك، أضِف ما يلي إلى ملف build.gradle الخاص بتطبيقك للتأكّد من ذلك. لا تضغط Gradle ملف النموذج عند إنشاء التطبيق:

   android {
       // ...
       aaptOptions {
           noCompress "tflite"
           // or noCompress "lite"
       }
   }
   

   سيتم تضمين ملف النموذج في حزمة التطبيق وسيكون متاحًا في مجموعة أدوات تعلُّم الآلة. كمادة عرض أولية

3. أنشِئ عنصر 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، مع تحديد الاسم الذي حدّدته للنموذج عند نشرته:

// Specify the name you assigned in the Firebase console.
val remoteModel =
    CustomRemoteModel
        .Builder(FirebaseModelSource.Builder("your_model_name").build())
        .build()

// Specify the name you assigned in the Firebase console.
CustomRemoteModel remoteModel =
    new CustomRemoteModel
        .Builder(new FirebaseModelSource.Builder("your_model_name").build())
        .build();

بعد ذلك، ابدأ مهمة تنزيل النموذج، مع تحديد الشروط التي الذي تريد السماح بتنزيله إذا لم يكن الطراز موجودًا على الجهاز، أو إذا كان طرازًا أحدث إتاحة إصدار معين من النموذج، فإن المهمة ستنزّل بشكل غير متزامن النموذج من Firebase:

val downloadConditions = DownloadConditions.Builder()
    .requireWifi()
    .build()
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
    .addOnSuccessListener {
        // Success.
    }

DownloadConditions downloadConditions = new DownloadConditions.Builder()
        .requireWifi()
        .build();
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
        .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(@NonNull Task task) {
                // Success.
            }
        });

تبدأ العديد من التطبيقات مهمة التنزيل في رمز التهيئة الخاص بها، ولكن يمكنك القيام بذلك في أي وقت قبل أن تحتاج إلى استخدام النموذج.

ضبط أداة تصنيف الصور

بعد ضبط مصادر النموذج، يمكنك إنشاء عنصر ImageLabeler من واحد منها.

تتوفّر الخيارات التالية:

وإذا كان لديك نموذج مجمّع محليًا فقط، ما عليك سوى إنشاء مصنِّف من كائن LocalModel:

val customImageLabelerOptions = CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.5f)
    .setMaxResultCount(5)
    .build()
val labeler = ImageLabeling.getClient(customImageLabelerOptions)

CustomImageLabelerOptions customImageLabelerOptions =
        new CustomImageLabelerOptions.Builder(localModel)
            .setConfidenceThreshold(0.5f)
            .setMaxResultCount(5)
            .build();
ImageLabeler labeler = ImageLabeling.getClient(customImageLabelerOptions);

فإذا كان لديك نموذج مستضاف عن بُعد، فعليك التحقق من أنه تم تنزيله قبل تشغيله. يمكنك التحقّق من حالة تنزيل النموذج باستخدام طريقة isModelDownloaded() لمدير النموذج.

وما عليك سوى تأكيد ذلك قبل تشغيل المُصنِّف، إذا لكل من نموذج مُستضاف عن بُعد ونموذج مُجمع محليًا، فقد تجعل إجراء هذا الفحص عند إنشاء مثيل مصنف الصور: إنشاء من النموذج البعيد إذا تم تنزيله، ومن النموذج المحلي نموذج بخلاف ذلك.

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

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() لمدير النموذج:

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.
    }

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 من مصادر مختلفة، في ما يلي شرح لكل منها.

يتم استخدام media.Image

لإنشاء InputImage كائن من كائن media.Image، مثلاً عند التقاط صورة من كاميرا الجهاز، يُرجى تمرير الكائن media.Image تدوير إلى InputImage.fromMediaImage().

إذا كنت تستخدم CameraX وOnImageCapturedListener تحتسب صفوف ImageAnalysis.Analyzer قيمة عرض الإعلانات بالتناوب. لك.

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
            // ...
        }
    }
}

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
          // ...
        }
    }
}

إذا كنت لا تستخدم مكتبة كاميرا تمنحك درجة تدوير الصورة، يمكنك يمكنه حسابه من خلال درجة دوران الجهاز واتجاه الكاميرا. جهاز الاستشعار في الجهاز:

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
}
MLKitVisionImage.kt

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

val image = InputImage.fromMediaImage(mediaImage, rotation)
MLKitVisionImage.kt

InputImage image = InputImage.fromMediaImage(mediaImage, rotation);

استخدام معرف موارد منتظم (URI) لملف

لإنشاء InputImage من معرف موارد منتظم (URI) لملف، فمرر سياق التطبيق ومعرف الموارد المنتظم (URI) للملف إلى InputImage.fromFilePath() يكون ذلك مفيدًا عندما يجب استخدام هدف ACTION_GET_CONTENT لتطلب من المستخدم الاختيار. صورة من تطبيق المعرض الخاص به.

val image: InputImage
try {
    image = InputImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}
MLKitVisionImage.kt

InputImage image;
try {
    image = InputImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}

يتم استخدام ByteBuffer أو ByteArray

لإنشاء InputImage كائن من ByteBuffer أو ByteArray، احسب الصورة أولاً درجة التدوير كما هو موضح سابقًا لإدخال media.Image. بعد ذلك، يمكنك إنشاء الكائن InputImage باستخدام المخزن المؤقت أو المصفوفة بالإضافة إلى الارتفاع والعرض وتنسيق ترميز الألوان ودرجة التدوير:

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java

يتم استخدام Bitmap

لإنشاء InputImage من كائن Bitmap، قدِّم التعريف التالي:

val image = InputImage.fromBitmap(bitmap, 0)
MLKitVisionImage.kt

InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);
MLKitVisionImage.java

يتم تمثيل الصورة بواسطة كائن Bitmap مع درجات التدوير.

3- تشغيل أداة تصنيف الصور

لتصنيف عناصر في صورة، مرِّر كائن image إلى ImageLabeler طريقة process()

labeler.process(image)
        .addOnSuccessListener { labels ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }
ImageLabelingActivity.kt

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
                // ...
            }
        });
ImageLabelingActivity.java

4. الحصول على معلومات عن الكيانات المصنّفة

for (label in labels) {
    val text = label.text
    val confidence = label.confidence
    val index = label.index
}
ImageLabelingActivity.kt

for (ImageLabel label : labels) {
    String text = label.getText();
    float confidence = label.getConfidence();
    int index = label.getIndex();
}
ImageLabelingActivity.java

نصائح لتحسين الأداء في الوقت الفعلي

إذا أردت تصنيف الصور في تطبيق في الوقت الفعلي، فاتبع هذه الإرشادات اللازمة لتحقيق أفضل عدد من اللقطات في الثانية:

• إذا كنت تستخدم 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