Reconnaître du texte dans des images avec ML Kit sur Android

Vous pouvez utiliser ML Kit pour reconnaître du texte dans des images ou des vidéos, comme le texte d'un panneau de signalisation. Voici les principales caractéristiques de cette fonctionnalité :

Cette API est disponible à l'aide d'une bibliothèque non groupée qui doit être téléchargée avant utilisation ou d'une bibliothèque groupée qui augmente la taille de votre application. Pour en savoir plus sur les différences entre les deux options d'installation, consultez ce guide.

Fonctionnalité	Non groupée	Groupée
Nom de la bibliothèque	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
Implémentation	Le modèle est téléchargé dynamiquement via les services Google Play.	Le modèle est lié statiquement à votre application au moment de la compilation.
Taille de l'application	Augmentation de la taille d'environ 260 Ko par architecture de script.	Augmentation de la taille d'environ 4 Mo par script et par architecture.
Délai d'initialisation	Vous devrez peut-être attendre le téléchargement du modèle avant de l'utiliser pour la première fois.	Le modèle est disponible immédiatement.
Performances	En temps réel sur la plupart des appareils pour la bibliothèque de scripts latins, plus lent pour les autres.	En temps réel sur la plupart des appareils pour la bibliothèque de scripts latins, plus lent pour les autres.

Essayer

• Essayez l'exemple d'application pour voir un exemple d'utilisation de cette API.
• Essayez le code vous-même avec l' atelier de programmation.

Avant de commencer

Cette API nécessite le niveau d'API Android 23 ou supérieur. Assurez-vous que le fichier de compilation de votre application utilise une valeur minSdkVersion de 23 ou plus.

1. Dans le fichier build.gradle au niveau du projet, veillez à inclure le dépôt Maven de Google à la fois dans les sections buildscript et allprojects.

2. Ajoutez les dépendances des bibliothèques Android ML Kit au fichier Gradle au niveau de l'application de votre module, qui est généralement app/build.gradle :

   Pour regrouper le modèle avec votre application :

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

   Pour utiliser le modèle dans les services 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'
   }
   

3. Si vous choisissez d'utiliser le modèle dans les services Google Play, vous pouvez configurer votre application pour qu'elle télécharge automatiquement le modèle sur l'appareil une fois qu'elle est installée depuis le Play Store. Pour ce faire, ajoutez la déclaration suivante au fichier AndroidManifest.xml de votre application :

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

   Vous pouvez également vérifier explicitement la disponibilité du modèle et demander le téléchargement via l'API ModuleInstallClient des services Google Play. Si vous n'activez pas les téléchargements de modèles au moment de l'installation ou ne demandez pas de téléchargement explicite, le modèle est téléchargé la première fois que vous exécutez le scanner. Les requêtes que vous effectuez avant la fin du téléchargement ne produisent aucun résultat.

1. Créer une instance de TextRecognizer

Créez une instance de TextRecognizer en transmettant les options liées à la bibliothèque pour laquelle vous avez déclaré une dépendance ci-dessus :

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. Préparer l'image d'entrée

Pour reconnaître du texte dans une image, créez un objet InputImage à partir de soit un Bitmap, un media.Image, un ByteBuffer, un tableau d'octets ou un fichier sur l' appareil. Transmettez ensuite l'objet InputImage à la méthode processImage du TextRecognizer.

Vous pouvez créer un InputImage objet à partir de différentes sources, chacune étant expliquée ci-dessous.

Utiliser un media.Image

Pour créer un objet InputImage à partir d'un objet media.Image, par exemple lorsque vous capturez une image à partir de l'appareil photo d'un appareil, transmettez l'objet media.Image et la rotation de l'image à InputImage.fromMediaImage().

Si vous utilisez la bibliothèque CameraX, les classes OnImageCapturedListener et ImageAnalysis.Analyzer calculent la valeur de rotation pour vous.

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

Si vous n'utilisez pas de bibliothèque d'appareil photo qui vous donne le degré de rotation de l'image, vous pouvez le calculer à partir du degré de rotation de l'appareil et de l'orientation du capteur de l'appareil photo dans l'appareil :

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

Transmettez ensuite l'objet media.Image et la valeur du degré de rotation à InputImage.fromMediaImage() :

Kotlin

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

Java

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

Utiliser un URI de fichier

Pour créer un InputImage objet à partir d'un URI de fichier, transmettez le contexte de l'application et l'URI du fichier à InputImage.fromFilePath(). Cela est utile lorsque vous utilisez un intent ACTION_GET_CONTENT pour inviter l'utilisateur à sélectionner une image dans son application de galerie.

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

Utiliser un ByteBuffer ou un ByteArray

Pour créer un objet InputImage à partir d'un ByteBuffer ou d'un ByteArray, calculez d'abord le degré de rotation de l'image comme décrit précédemment pour l'entrée media.Image. Créez ensuite l'objet InputImage avec le tampon ou le tableau, ainsi que la hauteur, la largeur, le format d'encodage des couleurs et le degré de rotation de l'image :

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

Utiliser un Bitmap

Pour créer un objet InputImage à partir d'un objet Bitmap, effectuez la déclaration suivante :

Kotlin

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

Java

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

L'image est représentée par un objet Bitmap ainsi que par des degrés de rotation.

3. Traiter l'image

Transmettez l'image à la méthode 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

Remarque : Si vous utilisez l'API CameraX, veillez à fermer l'ImageProxy lorsque vous avez terminé de l'utiliser, par exemple en ajoutant un OnCompleteListener à la Task renvoyée par la méthode process. Pour obtenir un exemple, consultez la classe VisionProcessorBase dans l'application exemple de démarrage rapide.

4. Extraire le texte des blocs de texte reconnus

Si l'opération de reconnaissance de texte réussit, un Text objet est transmis à l'écouteur de réussite. Un objet Text contient le texte complet reconnu dans l'image et zéro ou plusieurs objets TextBlock.

Chaque TextBlock représente un bloc de texte rectangulaire, qui contient zéro ou plusieurs objets Line. Chaque Line objet représente une ligne de texte, qui contient zéro ou plusieurs Element objets. Chaque Element objet représente un mot ou une entité de type mot, qui contient zéro ou plusieurs Symbol objets. Chaque Symbol objet représente un caractère, un chiffre ou une entité de type mot.

Pour chaque objet TextBlock, Line, Element et Symbol, vous pouvez obtenir le texte reconnu dans la région, les coordonnées de délimitation de la région et de nombreux autres attributs tels que les informations de rotation, le score de confiance etc.

Exemple :

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

Consignes concernant les images d'entrée

• Pour que ML Kit reconnaisse le texte avec précision, les images d'entrée doivent contenir du texte représenté par suffisamment de données de pixels. Dans l'idéal, chaque caractère doit mesurer au moins 16 x 16 pixels. En général, il n'est pas plus précis d'utiliser des caractères de plus de 24 x 24 pixels.

  Ainsi, par exemple, une image de 640 x 480 pixels peut être idéale pour numériser une carte de visite qui occupe toute la largeur de l'image. Pour numériser un document imprimé sur du papier au format lettre, une image de 720 x 1 280 pixels peut être nécessaire.

• Une mauvaise mise au point de l'image peut affecter la précision de la reconnaissance de texte. Si vous n'obtenez pas de résultats acceptables, essayez de demander à l'utilisateur de reprendre l'image.

• Si vous reconnaissez du texte dans une application en temps réel, vous devez tenir compte des dimensions globales des images d'entrée. Les images plus petites peuvent être traitées plus rapidement. Pour réduire la latence, assurez-vous que le texte occupe la plus grande partie possible de l'image et capturez des images à des résolutions inférieures (en gardant à l'esprit les exigences de précision mentionnées ci-dessus). Pour en savoir plus, consultez Conseils pour améliorer les performances.

Conseils pour améliorer les performances

• Si vous utilisez l'API Camera ou camera2, limitez les appels au détecteur. Si une nouvelle image vidéo devient disponible pendant l'exécution du détecteur, supprimez l'image. Pour obtenir un exemple, consultez la classe VisionProcessorBase dans l'application exemple de démarrage rapide.
• Si vous utilisez l'API CameraX, assurez-vous que la stratégie de contre-pression est définie sur sa valeur par défaut ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Cela garantit qu'une seule image sera fournie pour l'analyse à la fois. Si d'autres images sont produites lorsque l'analyseur est occupé, elles seront supprimées automatiquement et ne seront pas mises en file d'attente pour la livraison. Une fois que l'image analysée est fermée en appelant ImageProxy.close(), la dernière image la plus récente est fournie.
• Si vous utilisez la sortie du détecteur pour superposer des graphiques sur l'image d'entrée, obtenez d'abord le résultat de ML Kit, puis effectuez le rendu de l'image et la superposition en une seule étape. Le rendu n'est effectué qu'une seule fois sur la surface d'affichage pour chaque image d'entrée. Pour obtenir un exemple, consultez les classes CameraSourcePreview et GraphicOverlay dans l'application exemple de démarrage rapide.
• Si vous utilisez l'API Camera2, capturez des images au format ImageFormat.YUV_420_888 Si vous utilisez l'ancienne API Camera, capturez des images au ImageFormat.NV21 format.
• Envisagez de capturer des images à une résolution inférieure. Toutefois, gardez également à l'esprit les exigences de cette API concernant les dimensions des images.