تصنيف الصور باستخدام تعلُّم الآلة من Firebase على نظام Android

توضّح هذه الصفحة إصدارًا قديمًا من عملية تصنيف العناصر التي تم التعرّف عليها في صورة باستخدام Firebase ML Vision SDK المتوقّفة نهائيًا. كحلّ بديل، يمكنك استدعاء واجهات برمجة التطبيقات Cloud Vision باستخدام Firebase Auth و"الدوال القابلة للاستدعاء" للسماح فقط للمستخدمين الذين سجّلوا الدخول إلى تطبيقك بالوصول إلى واجهة برمجة التطبيقات.

يمكنك استخدام Firebase ML لتصنيف العناصر التي تم التعرّف عليها في صورة. يمكنك الاطّلاع على النظرة العامة للحصول على معلومات حول ميزات واجهة برمجة التطبيقات هذه.

يخضع استخدام واجهات برمجة التطبيقات Cloud Vision API إلى اتفاقية ترخيص Google Cloud Platform والبنود الخاصة بالخدمة، ويتم تحصيل الرسوم وفقًا لذلك. للحصول على معلومات عن الفوترة، يُرجى الاطّلاع على صفحة الأسعار.

هل تبحث عن ميزة تصنيف الصور على الجهاز فقط؟ جرِّب مكتبة ML Kit المستقلة.

قبل البدء

1. إذا لم يسبق لك إجراء ذلك، أضِف Firebase إلى مشروع Android.
2. في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف الاعتمادية لمكتبة Firebase ML Vision لنظام التشغيل Android. ننصحك باستخدام Firebase Android BoM للتحكّم في إصدارات المكتبة.

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:34.0.0"))
   
       // Add the dependency for the Firebase ML Vision library
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation 'com.google.firebase:firebase-ml-vision'
   }

   باستخدام Firebase Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase Android.

   (بديل)  أضِف تبعيات مكتبة Firebase بدون استخدام BoM

   إذا اخترت عدم استخدام Firebase BoM، عليك تحديد إصدار كل مكتبة من مكتبات Firebase في سطر التبعية الخاص بها.

   يُرجى العِلم أنّه في حال استخدام مكتبات Firebase BoMمتعدّدة في تطبيقك، ننصحك بشدة باستخدام BoM لإدارة إصدارات المكتبات، ما يضمن توافق جميع الإصدارات.

   dependencies {
       // Add the dependency for the Firebase ML Vision library
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation 'com.google.firebase:firebase-ml-vision:24.1.0'
   }

3. إذا لم يسبق لك تفعيل واجهات برمجة التطبيقات المستنِدة إلى السحابة الإلكترونية لمشروعك، عليك إجراء ذلك الآن:

   1. افتح Firebase ML صفحة واجهات برمجة التطبيقات في وحدة تحكّم Firebase.

   2. إذا لم يسبق لك ترقية مشروعك إلى خطة أسعار Blaze بنظام الدفع حسب الاستخدام، انقر على ترقية لإجراء ذلك. (لن يُطلب منك الترقية إلا إذا لم يكن مشروعك مشتركًا في خطة أسعار Blaze).

      يمكن للمشاريع التي تستخدم خطة التسعير Blaze فقط استخدام واجهات برمجة التطبيقات المستندة إلى السحابة الإلكترونية.

   3. إذا لم تكن واجهات برمجة التطبيقات المستندة إلى السحابة الإلكترونية مفعّلة، انقر على تفعيل واجهات برمجة التطبيقات المستندة إلى السحابة الإلكترونية.
   قبل نشر تطبيق يستخدم إحدى واجهات Cloud API في مرحلة الإنتاج، عليك اتّخاذ بعض الخطوات الإضافية لمنع تأثير الوصول غير المصرّح به إلى واجهة برمجة التطبيقات والحدّ منه.

أنت الآن جاهز لتصنيف الصور.

1. إعداد الصورة المدخَلة

أنشئ عنصر FirebaseVisionImage من صورتك. تعمل أداة تصنيف الصور بأسرع ما يمكن عند استخدام Bitmap أو media.Image بتنسيق JPEG في حال استخدام Camera2 API، وننصح باستخدامها عند الإمكان.

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

  إذا كنت تستخدم مكتبة CameraX، سيحسب لك الفئتان OnImageCapturedListener وImageAnalysis.Analyzer قيمة الدوران، لذلك ما عليك سوى تحويل الدوران إلى أحد الثوابت ROTATION_ في Firebase ML قبل استدعاء FirebaseVisionImage.fromMediaImage():

  Kotlin

  private class YourImageAnalyzer : ImageAnalysis.Analyzer {
      private fun degreesToFirebaseRotation(degrees: Int): Int = when(degrees) {
          0 -> FirebaseVisionImageMetadata.ROTATION_0
          90 -> FirebaseVisionImageMetadata.ROTATION_90
          180 -> FirebaseVisionImageMetadata.ROTATION_180
          270 -> FirebaseVisionImageMetadata.ROTATION_270
          else -> throw Exception("Rotation must be 0, 90, 180, or 270.")
      }
  
      override fun analyze(imageProxy: ImageProxy?, degrees: Int) {
          val mediaImage = imageProxy?.image
          val imageRotation = degreesToFirebaseRotation(degrees)
          if (mediaImage != null) {
              val image = FirebaseVisionImage.fromMediaImage(mediaImage, imageRotation)
              // Pass image to an ML Vision API
              // ...
          }
      }
  }

  Java

  private class YourAnalyzer implements ImageAnalysis.Analyzer {
  
      private int degreesToFirebaseRotation(int degrees) {
          switch (degrees) {
              case 0:
                  return FirebaseVisionImageMetadata.ROTATION_0;
              case 90:
                  return FirebaseVisionImageMetadata.ROTATION_90;
              case 180:
                  return FirebaseVisionImageMetadata.ROTATION_180;
              case 270:
                  return FirebaseVisionImageMetadata.ROTATION_270;
              default:
                  throw new IllegalArgumentException(
                          "Rotation must be 0, 90, 180, or 270.");
          }
      }
  
      @Override
      public void analyze(ImageProxy imageProxy, int degrees) {
          if (imageProxy == null || imageProxy.getImage() == null) {
              return;
          }
          Image mediaImage = imageProxy.getImage();
          int rotation = degreesToFirebaseRotation(degrees);
          FirebaseVisionImage image =
                  FirebaseVisionImage.fromMediaImage(mediaImage, rotation);
          // Pass image to an ML Vision API
          // ...
      }
  }

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

  Kotlin

  private val ORIENTATIONS = SparseIntArray()
  
  init {
      ORIENTATIONS.append(Surface.ROTATION_0, 90)
      ORIENTATIONS.append(Surface.ROTATION_90, 0)
      ORIENTATIONS.append(Surface.ROTATION_180, 270)
      ORIENTATIONS.append(Surface.ROTATION_270, 180)
  }
  /**
   * 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, context: Context): 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)
  
      // On most devices, the sensor orientation is 90 degrees, but for some
      // devices it is 270 degrees. For devices with a sensor orientation of
      // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
      val cameraManager = context.getSystemService(CAMERA_SERVICE) as CameraManager
      val sensorOrientation = cameraManager
          .getCameraCharacteristics(cameraId)
          .get(CameraCharacteristics.SENSOR_ORIENTATION)!!
      rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360
  
      // Return the corresponding FirebaseVisionImageMetadata rotation value.
      val result: Int
      when (rotationCompensation) {
          0 -> result = FirebaseVisionImageMetadata.ROTATION_0
          90 -> result = FirebaseVisionImageMetadata.ROTATION_90
          180 -> result = FirebaseVisionImageMetadata.ROTATION_180
          270 -> result = FirebaseVisionImageMetadata.ROTATION_270
          else -> {
              result = FirebaseVisionImageMetadata.ROTATION_0
              Log.e(TAG, "Bad rotation value: $rotationCompensation")
          }
      }
      return result
  }
  VisionImage.kt

  Java

  private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
  static {
      ORIENTATIONS.append(Surface.ROTATION_0, 90);
      ORIENTATIONS.append(Surface.ROTATION_90, 0);
      ORIENTATIONS.append(Surface.ROTATION_180, 270);
      ORIENTATIONS.append(Surface.ROTATION_270, 180);
  }
  
  /**
   * 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, Context context)
          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);
  
      // On most devices, the sensor orientation is 90 degrees, but for some
      // devices it is 270 degrees. For devices with a sensor orientation of
      // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
      CameraManager cameraManager = (CameraManager) context.getSystemService(CAMERA_SERVICE);
      int sensorOrientation = cameraManager
              .getCameraCharacteristics(cameraId)
              .get(CameraCharacteristics.SENSOR_ORIENTATION);
      rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360;
  
      // Return the corresponding FirebaseVisionImageMetadata rotation value.
      int result;
      switch (rotationCompensation) {
          case 0:
              result = FirebaseVisionImageMetadata.ROTATION_0;
              break;
          case 90:
              result = FirebaseVisionImageMetadata.ROTATION_90;
              break;
          case 180:
              result = FirebaseVisionImageMetadata.ROTATION_180;
              break;
          case 270:
              result = FirebaseVisionImageMetadata.ROTATION_270;
              break;
          default:
              result = FirebaseVisionImageMetadata.ROTATION_0;
              Log.e(TAG, "Bad rotation value: " + rotationCompensation);
      }
      return result;
  }
  VisionImage.java

  بعد ذلك، مرِّر العنصر media.Image وقيمة التدوير إلى FirebaseVisionImage.fromMediaImage():

  Kotlin

  val image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation)
  VisionImage.kt

  Java

  FirebaseVisionImage image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation);
  VisionImage.java

• لإنشاء عنصر FirebaseVisionImage من معرّف موارد منتظم (URI) لملف، مرِّر سياق التطبيق ومعرّف الموارد المنتظم (URI) للملف إلى FirebaseVisionImage.fromFilePath(). ويكون ذلك مفيدًا عند استخدام ACTION_GET_CONTENT intent لطلب أن يختار المستخدم صورة من تطبيق المعرض.

  Kotlin

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

  Java

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

• لإنشاء عنصر FirebaseVisionImage من ByteBuffer أو مصفوفة بايت، عليك أولاً حساب درجة دوران الصورة كما هو موضّح أعلاه بالنسبة إلى الإدخال media.Image.

  بعد ذلك، أنشئ عنصر FirebaseVisionImageMetadata يحتوي على ارتفاع الصورة وعرضها وتنسيق ترميز الألوان وزاوية الدوران:

  Kotlin

  val metadata = FirebaseVisionImageMetadata.Builder()
      .setWidth(480) // 480x360 is typically sufficient for
      .setHeight(360) // image recognition
      .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
      .setRotation(rotation)
      .build()
  VisionImage.kt

  Java

  FirebaseVisionImageMetadata metadata = new FirebaseVisionImageMetadata.Builder()
          .setWidth(480)   // 480x360 is typically sufficient for
          .setHeight(360)  // image recognition
          .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
          .setRotation(rotation)
          .build();
  VisionImage.java

  استخدِم المخزن المؤقت أو المصفوفة وكائن البيانات الوصفية لإنشاء كائن FirebaseVisionImage:

  Kotlin

  val image = FirebaseVisionImage.fromByteBuffer(buffer, metadata)
  // Or: val image = FirebaseVisionImage.fromByteArray(byteArray, metadata)
  VisionImage.kt

  Java

  FirebaseVisionImage image = FirebaseVisionImage.fromByteBuffer(buffer, metadata);
  // Or: FirebaseVisionImage image = FirebaseVisionImage.fromByteArray(byteArray, metadata);
  VisionImage.java

• لإنشاء كائن FirebaseVisionImage من كائن Bitmap، اتّبِع الخطوات التالية:

  Kotlin

  val image = FirebaseVisionImage.fromBitmap(bitmap)
  VisionImage.kt

  Java

  FirebaseVisionImage image = FirebaseVisionImage.fromBitmap(bitmap);
  VisionImage.java

  يجب أن تكون الصورة الممثّلة بالكائن Bitmap في الوضع العمودي، بدون الحاجة إلى تدوير إضافي.

2- ضبط أداة تصنيف الصور وتشغيلها

لتصنيف العناصر في صورة، مرِّر العنصر FirebaseVisionImage إلى طريقة processImage في FirebaseVisionImageLabeler.

1. أولاً، احصل على نسخة من FirebaseVisionImageLabeler.

   Kotlin

   val labeler = FirebaseVision.getInstance().getCloudImageLabeler()
   
   // Or, to set the minimum confidence required:
   // val options = FirebaseVisionCloudImageLabelerOptions.Builder()
   //     .setConfidenceThreshold(0.7f)
   //     .build()
   // val labeler = FirebaseVision.getInstance().getCloudImageLabeler(options)
   

   Java

   FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
       .getCloudImageLabeler();
   
   // Or, to set the minimum confidence required:
   // FirebaseVisionCloudImageLabelerOptions options =
   //     new FirebaseVisionCloudImageLabelerOptions.Builder()
   //         .setConfidenceThreshold(0.7f)
   //         .build();
   // FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
   //     .getCloudImageLabeler(options);
   

2. بعد ذلك، مرِّر الصورة إلى طريقة processImage():

   Kotlin

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

   Java

   labeler.processImage(image)
       .addOnSuccessListener(new OnSuccessListener<List<FirebaseVisionImageLabel>>() {
         @Override
         public void onSuccess(List<FirebaseVisionImageLabel> labels) {
           // Task completed successfully
           // ...
         }
       })
       .addOnFailureListener(new OnFailureListener() {
         @Override
         public void onFailure(@NonNull Exception e) {
           // Task failed with an exception
           // ...
         }
       });
   

3- الحصول على معلومات عن العناصر المصنَّفة

في حال نجاح عملية تصنيف الصور، سيتم تمرير قائمة بعناصر FirebaseVisionImageLabel إلى أداة معالجة النجاح. يمثّل كل كائن FirebaseVisionImageLabel شيئًا تم تصنيفه في الصورة. يمكنك الحصول على وصف نصي لكل تصنيف، ومعرّف كيان "الرسم البياني المعرفي" (إذا كان متاحًا)، ونتيجة دقة المطابقة. على سبيل المثال:

Kotlin

for (label in labels) {
  val text = label.text
  val entityId = label.entityId
  val confidence = label.confidence
}

Java

for (FirebaseVisionImageLabel label: labels) {
  String text = label.getText();
  String entityId = label.getEntityId();
  float confidence = label.getConfidence();
}

الخطوات التالية

• قبل نشر تطبيق يستخدم إحدى واجهات Cloud API في مرحلة الإنتاج، عليك اتّخاذ بعض الخطوات الإضافية لمنع تأثير الوصول غير المصرّح به إلى واجهة برمجة التطبيقات والحدّ منه.