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

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

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

مُجمَّعةغير مجمعة
اسم المكتبةcom.google.mlkit:image-labeling-customcom.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

جرّبه الآن

قبل البدء

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

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