يمكنك استخدام حزمة تعلّم الآلة للتعرّف على النصوص في الصور أو الفيديو، مثل نص لافتة شارع. في ما يلي الخصائص الرئيسية لهذه الميزة:
| الميزة | غير مجمَّعة | مُجمَّعة |
|---|---|---|
| اسم المكتبة | 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 ميغابايت تقريبًا لكل نص ولكل بنية. |
| وقت التهيئة | قد يكون عليك الانتظار إلى أن يتم تنزيل النموذج قبل استخدامه لأول مرة. | النموذج متاح على الفور. |
| الأداء | في الوقت الفعلي على معظم الأجهزة لمكتبة النصوص اللاتينية، وأبطأ بالنسبة إلى المكتبات الأخرى | في الوقت الفعلي على معظم الأجهزة لمكتبة النصوص اللاتينية، وأبطأ بالنسبة إلى المكتبات الأخرى |
للتجربة:
- يمكنك تجربة التطبيق النموذجي للاطّلاع على مثال على استخدام واجهة برمجة التطبيقات هذه.
- يمكنك تجربة الرمز بنفسك من خلال الدرس التطبيقي حول الترميز.
قبل البدء
- في ملف
build.gradleعلى مستوى المشروع، تأكَّد من تضمين مستودع Maven من Google في كلٍّ من قسمَيbuildscriptوallprojects. أضِف التبعيات لمكتبات حزمة تعلّم الآلة على 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" > <!-- To use multiple models: android:value="ocr,ocr_chinese,ocr_devanagari,ocr_japanese,ocr_korean,..." --> </application>يمكنك أيضًا التحقّق بشكلٍ صريح من مدى توفّر النموذج وطلب تنزيله من خلال Google Play services ModuleInstallClient API. إذا لم تفعِّل عمليات تنزيل النموذج في وقت التثبيت أو لم تطلب تنزيله بشكلٍ صريح، يتم تنزيل النموذج في المرة الأولى التي تشغّل فيها الماسح الضوئي. لا تعرض الطلبات التي تقدّمها قبل اكتمال التنزيل أي نتائج.
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())
جافا
// 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 // ... } } }
جافا
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 }
جافا
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 )
جافا
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. معالجة الصورة
مرِّر الصورة إلى طريقة process:
Kotlin
val result = recognizer.process(image) .addOnSuccessListener { visionText -> // Task completed successfully // ... } .addOnFailureListener { e -> // Task failed with an exception // ... }
جافا
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 // ... } });
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 } } }
جافا
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(); } } } }
إرشادات متعلقة بالصورة المُدخَلة
-
لكي تتعرّف حزمة تعلّم الآلة على النص بدقة، يجب أن تحتوي الصور المُدخَلة على نص يتم تمثيله ببيانات بكسل كافية. من الناحية المثالية، يجب أن يكون حجم كل حرف 16×16 بكسل على الأقل. لا توجد عادةً فائدة من حيث الدقة إذا كان حجم الأحرف أكبر من 24×24 بكسل.
على سبيل المثال، قد تكون صورة بحجم 640×480 مناسبة لفحص بطاقة عمل تشغل العرض الكامل للصورة. لفحص مستند مطبوع على ورق بحجم الرسالة، قد تكون هناك حاجة إلى صورة بحجم 720×1280 بكسل.
-
يمكن أن يؤثر التركيز الضعيف للصورة في دقة التعرّف على النص. إذا لم تحصل على نتائج مقبولة، جرِّب أن تطلب من المستخدم إعادة التقاط الصورة.
-
إذا كنت تتعرّف على النص في تطبيق في الوقت الفعلي، عليك مراعاة الأبعاد الإجمالية للصور المُدخَلة. يمكن معالجة الصور الأصغر حجمًا بشكلٍ أسرع. للحدّ من وقت الاستجابة، تأكَّد من أنّ النص يشغل أكبر قدر ممكن من الصورة، والتقِط الصور بدقة أقل (مع مراعاة متطلبات الدقة المذكورة أعلاه). لمزيد من المعلومات، يُرجى الاطّلاع على نصائح بشأن تحسين الأداء.
نصائح بشأن تحسين الأداء
- إذا كنت تستخدم واجهة برمجة التطبيقات
Cameraأوcamera2، قلِّل عدد طلبات الكشف. إذا أصبح إطار فيديو جديد متاحًا أثناء تشغيل أداة الكشف، تجاهَل الإطار. يمكنك الاطّلاع على الفئةVisionProcessorBaseفي نموذج التطبيق للبدء السريع للحصول على مثال. - إذا كنت تستخدم واجهة برمجة التطبيقات
CameraX، تأكَّد من ضبط استراتيجية الضغط الخلفي على القيمة التلقائيةImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. يضمن ذلك تسليم صورة واحدة فقط للتحليل في كل مرة. إذا تم إنتاج المزيد من الصور عندما يكون المحلّل مشغولاً، سيتم تجاهلها تلقائيًا ولن يتم وضعها في قائمة الانتظار لتسليمها. بعد إغلاق الصورة التي يتم تحليلها من خلال استدعاء ImageProxy.close()، سيتم تسليم أحدث صورة تالية. - إذا كنت تستخدم ناتج أداة الكشف لتراكب الرسومات على
الصورة المُدخَلة، احصل أولاً على النتيجة من حزمة تعلّم الآلة، ثم اعرض الصورة
والتراكب في خطوة واحدة. يؤدي ذلك إلى العرض على سطح العرض
مرة واحدة فقط لكل إطار إدخال. يمكنك الاطّلاع على الفئتَين
CameraSourcePreviewوGraphicOverlayفي نموذج تطبيق البدء السريع للحصول على مثال. - إذا كنت تستخدم Camera2 API، التقط الصور بتنسيق
ImageFormat.YUV_420_888إذا كنت تستخدم Camera API الأقدم، التقط الصور بتنسيقImageFormat.NV21 - ننصحك بالتقاط الصور بدقة أقل. ومع ذلك، عليك أيضًا مراعاة متطلبات أبعاد الصور في واجهة برمجة التطبيقات هذه.