تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

يمكنك استخدام ML Kit للتعرّف على النص في الصور أو الفيديوهات، مثل نص لافتة شارع. في ما يلي الخصائص الرئيسية لهذه الميزة:

الميزة	غير مجمَّعة	مُجمَّعة
اسم المكتبة	com.google.android.gms:play-services-mlkit-text-recognition com.google.android.gms:play-services-mlkit-text-recognition-chinese com.google.android.gms:play-services-mlkit-text-recognition-devanagari com.google.android.gms:play-services-mlkit-text-recognition-japanese com.google.android.gms:play-services-mlkit-text-recognition-korean	com.google.mlkit:text-recognition com.google.mlkit:text-recognition-chinese com.google.mlkit:text-recognition-devanagari com.google.mlkit:text-recognition-japanese com.google.mlkit:text-recognition-korean
التنفيذ	يتم تنزيل النموذج بشكل ديناميكي من خلال "خدمات Google Play".	يتم ربط النموذج بشكل ثابت بتطبيقك في وقت الإنشاء.
حجم التطبيق	زيادة في الحجم تبلغ حوالي 260 كيلوبايت لكل بنية نص برمجي	زيادة في الحجم تبلغ 4 ميغابايت تقريبًا لكل نص برمجي لكل بنية
وقت الإعداد	قد تحتاج إلى الانتظار إلى أن يتم تنزيل النموذج قبل استخدامه للمرة الأولى.	يتوفّر النموذج على الفور.
الأداء	في الوقت الفعلي على معظم الأجهزة لمكتبة النصوص اللاتينية، وأبطأ بالنسبة إلى اللغات الأخرى	في الوقت الفعلي على معظم الأجهزة لمكتبة النصوص اللاتينية، وأبطأ بالنسبة إلى اللغات الأخرى

جرّبه الآن

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

قبل البدء

تتطلّب واجهة برمجة التطبيقات هذه المستوى 21 أو إصدارًا أحدث من واجهة برمجة التطبيقات Android. تأكَّد من أنّ ملف الإصدار الخاص بتطبيقك يستخدم القيمة minSdkVersion أو قيمة أعلى من 21.

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

أضِف الاعتماديات الخاصة بمكتبات ML Kit على Android إلى ملف Gradle على مستوى التطبيق في وحدتك، والذي يكون عادةً app/build.gradle:

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

dependencies {
  // To recognize Latin script
  implementation 'com.google.mlkit:text-recognition:16.0.1'

  // To recognize Chinese script
  implementation 'com.google.mlkit:text-recognition-chinese:16.0.1'

  // To recognize Devanagari script
  implementation 'com.google.mlkit:text-recognition-devanagari:16.0.1'

  // To recognize Japanese script
  implementation 'com.google.mlkit:text-recognition-japanese:16.0.1'

  // To recognize Korean script
  implementation 'com.google.mlkit:text-recognition-korean:16.0.1'
}

لاستخدام النموذج في "خدمات Google Play"، يجب استيفاء الشروط التالية:

dependencies {
  // To recognize Latin script
  implementation 'com.google.android.gms:play-services-mlkit-text-recognition:19.0.1'

  // To recognize Chinese script
  implementation 'com.google.android.gms:play-services-mlkit-text-recognition-chinese:16.0.1'

  // To recognize Devanagari script
  implementation 'com.google.android.gms:play-services-mlkit-text-recognition-devanagari:16.0.1'

  // To recognize Japanese script
  implementation 'com.google.android.gms:play-services-mlkit-text-recognition-japanese:16.0.1'

  // To recognize Korean script
  implementation 'com.google.android.gms:play-services-mlkit-text-recognition-korean:16.0.1'
}

إذا اخترت استخدام النموذج في "خدمات Google Play"، يمكنك إعداد تطبيقك لتنزيل النموذج تلقائيًا على الجهاز بعد تثبيت تطبيقك من "متجر Play". لإجراء ذلك، أضِف تعريفًا على النحو التالي إلى ملف AndroidManifest.xml في تطبيقك:
```
<application ...>
      ...
      <meta-data
          android:name="com.google.mlkit.vision.DEPENDENCIES"
          android:value="ocr" >
      
</application>
```
يمكنك أيضًا التحقّق بشكل صريح من توفّر النموذج وطلب تنزيله من خلال واجهة برمجة التطبيقات ModuleInstallClient API في "خدمات Google Play". إذا لم تفعِّل تنزيل النماذج في وقت التثبيت أو لم تطلب تنزيلها بشكل صريح، سيتم تنزيل النموذج في المرة الأولى التي تشغّل فيها الماسح الضوئي. لن يؤدي تقديم طلبات قبل اكتمال التنزيل إلى ظهور أي نتائج.

1. إنشاء مثيل من `TextRecognizer`

أنشئ مثيلاً من TextRecognizer، مع تمرير الخيارات المتعلّقة بالمكتبة التي حدّدت تبعيتها أعلاه:

Kotlin

// When using Latin script library
val recognizer = TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS)

// When using Chinese script library
val recognizer = TextRecognition.getClient(ChineseTextRecognizerOptions.Builder().build())

// When using Devanagari script library
val recognizer = TextRecognition.getClient(DevanagariTextRecognizerOptions.Builder().build())

// When using Japanese script library
val recognizer = TextRecognition.getClient(JapaneseTextRecognizerOptions.Builder().build())

// When using Korean script library
val recognizer = TextRecognition.getClient(KoreanTextRecognizerOptions.Builder().build())

Java

// When using Latin script library
TextRecognizer recognizer =
  TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS);

// When using Chinese script library
TextRecognizer recognizer =
  TextRecognition.getClient(new ChineseTextRecognizerOptions.Builder().build());

// When using Devanagari script library
TextRecognizer recognizer =
  TextRecognition.getClient(new DevanagariTextRecognizerOptions.Builder().build());

// When using Japanese script library
TextRecognizer recognizer =
  TextRecognition.getClient(new JapaneseTextRecognizerOptions.Builder().build());

// When using Korean script library
TextRecognizer recognizer =
  TextRecognition.getClient(new KoreanTextRecognizerOptions.Builder().build());

2. إعداد الصورة المصدر

للتعرّف على نص في صورة، أنشئ عنصر InputImage من Bitmap أو media.Image أو ByteBuffer أو مصفوفة بايت أو ملف على الجهاز. بعد ذلك، مرِّر الكائن InputImage إلى الطريقة processImage في TextRecognizer.

يمكنك إنشاء عنصر 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
}MLKitVisionImage.kt

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

Java

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

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

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

Kotlin

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

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

Java

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، عليك إجراء التصريح التالي:

Kotlin

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

Java

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

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

3- معالجة الصورة

مرِّر الصورة إلى طريقة process:

Kotlin

val result = recognizer.process(image)
        .addOnSuccessListener { visionText ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }TextRecognitionActivity.kt

Java

Task<Text> result =
        recognizer.process(image)
                .addOnSuccessListener(new OnSuccessListener<Text>() {
                    @Override
                    public void onSuccess(Text visionText) {
                        // Task completed successfully
                        // ...
                    }
                })
                .addOnFailureListener(
                        new OnFailureListener() {
                            @Override
                            public void onFailure(@NonNull Exception e) {
                                // Task failed with an exception
                                // ...
                            }
                        });TextRecognitionActivity.java

ملاحظة: إذا كنت تستخدم واجهة برمجة التطبيقات CameraX، احرص على إغلاق ImageProxy عند الانتهاء من استخدامها، على سبيل المثال، عن طريق إضافة OnCompleteListener إلى Task التي تم إرجاعها من الطريقة process. يمكنك الاطّلاع على فئة VisionProcessorBase في تطبيق البدء السريع النموذجي للحصول على مثال.

4. استخراج النص من كتل النص التي تم التعرّف عليها

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

يمثّل كل TextBlock مستطيلاً نصيًا يحتوي على صفر أو أكثر من كائنات Line. يمثّل كل كائن Line سطرًا من النص، ويحتوي على صفر أو أكثر من كائنات Element. يمثّل كل كائن Element كلمة أو كيانًا يشبه الكلمة، ويحتوي على صفر أو أكثر من كائنات Symbol. يمثّل كل كائن Symbol حرفًا أو رقمًا أو كيانًا يشبه الكلمة.

بالنسبة إلى كل كائن TextBlock وLine وElement وSymbol، يمكنك الحصول على النص الذي تم التعرّف عليه في المنطقة، وإحداثيات حدود المنطقة، والعديد من السمات الأخرى، مثل معلومات التدوير، ونسبة الثقة، وما إلى ذلك.

على سبيل المثال:

Kotlin

val resultText = result.text
for (block in result.textBlocks) {
    val blockText = block.text
    val blockCornerPoints = block.cornerPoints
    val blockFrame = block.boundingBox
    for (line in block.lines) {
        val lineText = line.text
        val lineCornerPoints = line.cornerPoints
        val lineFrame = line.boundingBox
        for (element in line.elements) {
            val elementText = element.text
            val elementCornerPoints = element.cornerPoints
            val elementFrame = element.boundingBox
        }
    }
}TextRecognitionActivity.kt

Java

String resultText = result.getText();
for (Text.TextBlock block : result.getTextBlocks()) {
    String blockText = block.getText();
    Point[] blockCornerPoints = block.getCornerPoints();
    Rect blockFrame = block.getBoundingBox();
    for (Text.Line line : block.getLines()) {
        String lineText = line.getText();
        Point[] lineCornerPoints = line.getCornerPoints();
        Rect lineFrame = line.getBoundingBox();
        for (Text.Element element : line.getElements()) {
            String elementText = element.getText();
            Point[] elementCornerPoints = element.getCornerPoints();
            Rect elementFrame = element.getBoundingBox();
            for (Text.Symbol symbol : element.getSymbols()) {
                String symbolText = symbol.getText();
                Point[] symbolCornerPoints = symbol.getCornerPoints();
                Rect symbolFrame = symbol.getBoundingBox();
            }
        }
    }
}TextRecognitionActivity.java

إرشادات حول الصورة المدخَلة

لكي يتعرّف ML Kit على النص بدقة، يجب أن تحتوي الصور المدخلة على نص يمثّله عدد كافٍ من وحدات البكسل. من المفترض أن يكون حجم كل حرف 16×16 بكسل على الأقل. بشكل عام، لا يؤدي تكبير حجم الأحرف إلى أكثر من 24×24 بكسل إلى تحسين الدقة.

على سبيل المثال، قد تكون صورة بحجم 640x480 مناسبة لمسح بطاقة عمل ضوئيًا تشغل العرض الكامل للصورة. لمسح مستند ضوئيًا مطبوع على ورق بحجم الرسالة، قد تحتاج إلى صورة بحجم 720x1280 بكسل.
يمكن أن يؤثر التركيز الضعيف للصورة في دقة التعرّف على النص. إذا لم تحصل على نتائج مقبولة، اطلب من المستخدم إعادة التقاط الصورة.
إذا كنت تتعرّف على نص في تطبيق يعمل في الوقت الفعلي، عليك مراعاة الأبعاد الإجمالية لصور الإدخال. يمكن معالجة الصور الأصغر حجمًا بشكل أسرع. للحدّ من وقت الاستجابة، احرص على أن يشغل النص أكبر قدر ممكن من الصورة، والتقط الصور بدقة أقل (مع مراعاة متطلبات الدقة المذكورة أعلاه). لمزيد من المعلومات، يُرجى الاطّلاع على نصائح لتحسين الأداء.

نصائح لتحسين الأداء

إذا كنت تستخدم واجهة برمجة التطبيقات Camera أو camera2، عليك تقييد عدد طلبات البيانات من أداة الرصد. إذا توفّر إطار فيديو جديد أثناء تشغيل أداة رصد الحركة، تجاهِل الإطار. يمكنك الاطّلاع على فئة VisionProcessorBase في نموذج تطبيق البدء السريع للحصول على مثال.
في حال استخدام واجهة برمجة التطبيقات CameraX، احرص على ضبط استراتيجية الضغط الخلفي على القيمة التلقائية ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. يضمن ذلك تسليم صورة واحدة فقط لتحليلها في كل مرة. إذا تم إنتاج المزيد من الصور عندما يكون المحلّل مشغولاً، سيتم إسقاطها تلقائيًا ولن يتم وضعها في قائمة انتظار للتسليم. بعد إغلاق الصورة التي يتم تحليلها من خلال استدعاء ImageProxy.close()، سيتم عرض أحدث صورة تالية.
إذا كنت تستخدم ناتج أداة رصد الوجوه لتراكب الرسومات على صورة الإدخال، احصل أولاً على النتيجة من "حزمة تعلُّم الآلة"، ثم اعرض الصورة والتراكب في خطوة واحدة. ويتم عرض هذا المحتوى على مساحة العرض مرة واحدة فقط لكل إطار إدخال. يمكنك الاطّلاع على الفئتين CameraSourcePreview و GraphicOverlay في تطبيق العيّنة للبدء السريع للحصول على مثال.
إذا كنت تستخدم Camera2 API، التقط الصور بتنسيق ImageFormat.YUV_420_888. إذا كنت تستخدم الإصدار القديم من Camera API، التقط الصور بتنسيق ImageFormat.NV21.
ننصحك بالتقاط الصور بدقة أقل. ومع ذلك، يُرجى أيضًا مراعاة متطلبات أبعاد الصورة في واجهة برمجة التطبيقات هذه.

التعرّف على النص في الصور باستخدام أدوات تعلّم الآلة على نظام التشغيل Android تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

جرّبه الآن

قبل البدء

1. إنشاء مثيل من TextRecognizer

Kotlin

Java

2. إعداد الصورة المصدر

استخدام media.Image

Kotlin

Java

Kotlin

Java

Kotlin

Java

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

Kotlin

Java

استخدام ByteBuffer أو ByteArray

Kotlin

Java

استخدام Bitmap

Kotlin

Java

3- معالجة الصورة

Kotlin

Java

4. استخراج النص من كتل النص التي تم التعرّف عليها

Kotlin

Java

إرشادات حول الصورة المدخَلة

نصائح لتحسين الأداء

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

1. إنشاء مثيل من `TextRecognizer`

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

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

استخدام `Bitmap`