Comment déboguer OCR en C

This article was translated from English: Does it need improvement?
Translated
View the article in English

IronOCR vous permet de détecter les erreurs de reconnaissance optique de caractères (OCR) à la source, d'évaluer la qualité de la reconnaissance au niveau du mot et du caractère, et de surveiller les tâches de longue durée en temps réel. Des outils intégrés, tels que la journalisation des fichiers de diagnostic, une hiérarchie d'exceptions typées, un score de confiance par résultat et l'événement OcrProgress, prennent en charge ces flux de travail dans les pipelines de production.

Ce guide présente des exemples pratiques pour chaque fonctionnalité : activation de la journalisation des diagnostics, gestion des exceptions typées, validation des résultats avec des scores de confiance, surveillance de la progression des tâches en temps réel et isolation des erreurs dans les pipelines de traitement par lots.

Démarrage rapide : Activer la journalisation complète des diagnostics OCR

Définissez LogFilePath et LoggingMode sur la classe Installation avant le premier appel Read. Deux propriétés suffisent pour enregistrer dans un fichier journal les détails de l'initialisation de Tesseract, du chargement du pack de langue et du traitement.

  1. Installez IronOCR avec le Gestionnaire de Packages NuGet

    PM > Install-Package IronOcr
  2. Copiez et exécutez cet extrait de code.

    IronOcr.Installation.LogFilePath = "ocr.log"; IronOcr.Installation.LoggingMode = IronOcr.Installation.LoggingModes.All;
  3. Déployez pour tester sur votre environnement de production.

    Commencez à utiliser IronOCR dans votre projet dès aujourd'hui avec un essai gratuit

    arrow pointer


Comment activer la journalisation des diagnostics ?

La classe Installation expose trois contrôles de journalisation. Définissez ces paramètres avant d'appeler une méthode Read.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-enable-logging.cs
using IronOcr;

// Write logs to a specific file
Installation.LogFilePath = "logs/ocr_diagnostics.log";

// Enable all logging channels: file + debug output
Installation.LoggingMode = Installation.LoggingModes.All;

// Or pipe logs into your existing ILogger pipeline
Installation.CustomLogger = myLoggerInstance;
$vbLabelText   $csharpLabel

LoggingMode accepte les valeurs d'indicateur de l'énumération LoggingModes :

Tableau 1 : Options des modes de journalisation
ModeCible de sortieCas d'utilisation
NoneDésactivéProduction avec surveillance externe
DebugFenêtre de sortie de débogage de l'IDEDéveloppement local
FileLogFilePathCollecte de journaux côté serveur
AllDebug + FichierCapture diagnostique complète

La propriété CustomLogger prend en charge toute implémentation Microsoft.Extensions.Logging.ILogger, vous permettant de diriger les diagnostics OCR vers Serilog, NLog ou d'autres destinations de journalisation structurée dans votre pipeline. Utilisez ClearLogFiles pour supprimer les données de journalisation accumulées entre les exécutions.

Une fois la journalisation en place, l'étape suivante consiste à comprendre quelles exceptions IronOCR peut générer et comment gérer chacune d'elles.

Quelles exceptions IronOCR lève-t-il ?

IronOCR définit les exceptions typées sous l'espace de noms IronOcr.Exceptions . En les détectant spécifiquement, plutôt qu'en bloquant toute détection globale, vous pouvez acheminer chaque type de défaillance vers le chemin de correction approprié.

Tableau 2 : Référence des exceptions IronOCR
ExceptionCause communeSolution
IronOcrInputExceptionImage/PDF corrompu ou non pris en chargeValider le fichier avant de le charger dans OcrInput
IronOcrProductExceptionErreur interne du moteur lors de l'exécution OCRActiver la journalisation, vérifier la sortie du journal, mettre à jour vers la dernière version NuGet
IronOcrDictionaryExceptionFichier de langue .traineddata manquant ou corrompuRéinstallez le package linguistique NuGet ou définissez LanguagePackDirectory
IronOcrNativeExceptionÉchec de l'interopérabilité C++ nativeInstaller Visual C++ Redistributable; vérifier la prise en charge AVX
IronOcrLicensingExceptionClé de licence manquante ou expiréeDéfinissez LicenseKey avant d'appeler Read
LanguagePackExceptionPack linguistique non trouvé au chemin prévuVérifier LanguagePackDirectory ou réinstaller le package linguistique NuGet
IronOcrAssemblyVersionMismatchExceptionVersions d'assemblage incompatibles après une mise à jour partielleVider le cache NuGet, restaurer les packages, s'assurer que tous les packages IronOCR correspondent

Utilisez le bloc try-catch suivant pour gérer chaque type d'exception séparément, en appliquant des filtres d'exception pour la journalisation conditionnelle.

Entrée

Une facture fournisseur d'une seule page d' IronOCR Solutions à Acme Corporation, chargée via LoadPdf dans OcrInput. Il comprend quatre lignes de commande, la taxe et un total général — une variété de textes suffisante pour offrir à chaque gestionnaire d'exceptions un exercice réaliste.

invoice_scan.pdf : Facture fournisseur (#INV-2024-7829) utilisée pour démontrer chaque gestionnaire d'exceptions typé dans la séquence.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-exception-handling.cs
using IronOcr;
using IronOcr.Exceptions;

var ocr = new IronTesseract();

try
{
    using var input = new OcrInput();
    input.LoadPdf("invoice_scan.pdf");

    OcrResult result = ocr.Read(input);
    Console.WriteLine($"Text: {result.Text}");
    Console.WriteLine($"Confidence: {result.Confidence:P1}");
}
catch (IronOcrInputException ex)
{
    // File could not be loaded — corrupt, locked, or unsupported format
    Console.Error.WriteLine($"Input error: {ex.Message}");
}
catch (IronOcrDictionaryException ex)
{
    // Language pack missing — common in containerized deployments
    Console.Error.WriteLine($"Language pack error: {ex.Message}");
}
catch (IronOcrNativeException ex) when (ex.Message.Contains("AVX"))
{
    // CPU does not support AVX instructions
    Console.Error.WriteLine($"Hardware incompatibility: {ex.Message}");
}
catch (IronOcrLicensingException)
{
    Console.Error.WriteLine("License key is missing or invalid.");
}
catch (IronOcrProductException ex)
{
    // Catch-all for other IronOCR engine errors
    Console.Error.WriteLine($"OCR engine error: {ex.Message}");
    Console.Error.WriteLine($"Stack trace: {ex.StackTrace}");
}
$vbLabelText   $csharpLabel

Sortie

Résultats réussis

La facture se charge correctement et le moteur renvoie un nombre de caractères ainsi qu'un score de confiance.

Sortie du terminal affichant la lecture OCR réussie du fichier invoice_scan.pdf, avec le nombre de caractères et le score de confiance.

Sortie échouée

Sortie du terminal indiquant une exception levée lors du chargement d'un fichier PDF manquant

Classez les blocs catch du plus spécifique au plus général. La clause when sur IronOcrNativeException filtre les échecs liés à AVX sans intercepter les erreurs natives non liées. Chaque gestionnaire consigne le message d'exception ; Le bloc fourre-tout capture également la trace de la pile pour l'analyse post-mortem.

La détection de la bonne exception indique qu'un problème est survenu, mais pas la performance du moteur lorsqu'il a fonctionné correctement. Pour cela, utilisez les scores de confiance.

Comment valider les résultats de la reconnaissance optique de caractères (OCR) à l'aide de scores de confiance ?

Chaque OcrResult expose une propriété Confidence, une valeur entre 0 et 1 représentant la certitude statistique du moteur moyennée sur tous les caractères reconnus. Vous pouvez y accéder à chaque niveau de la hiérarchie des résultats : document , page ,paragraphe , mot etcaractère .

Utilisez un modèle à seuil pour empêcher la propagation en aval des résultats de faible qualité.

Entrée

Un reçu thermique avec des lignes détaillées, des remises, des totaux et un code-barres, chargé via LoadImage. Sa faible largeur, sa police à chasse fixe et son impression discrète en font un test de résistance pratique pour les seuils de confiance par mot.

Exemple de ticket de caisse thermique de FoodMart présentant le détail des achats, les totaux et les points de fidélité, utilisé comme entrée pour la reconnaissance optique de caractères (OCR).

receipt.png : Numérisation thermique du reçu utilisée pour démontrer la validation de la confiance par seuil et l'analyse détaillée de la précision mot par mot.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-confidence-scoring.cs
using IronOcr;

var ocr = new IronTesseract();
using var input = new OcrInput();
input.LoadImage("receipt.png");

OcrResult result = ocr.Read(input);
double confidence = result.Confidence;

Console.WriteLine($"Overall confidence: {confidence:P1}");

// Threshold-gated decision
if (confidence >= 0.90)
{
    Console.WriteLine("ACCEPT — high confidence, processing result.");
    ProcessResult(result.Text);
}
else if (confidence >= 0.70)
{
    Console.WriteLine("FLAG — moderate confidence, queuing for review.");
    QueueForReview(result.Text, confidence);
}
else
{
    Console.WriteLine("REJECT — low confidence, logging for investigation.");
    LogRejection("receipt.png", confidence);
}

// Drill into per-page and per-word confidence for diagnostics
foreach (var page in result.Pages)
{
    Console.WriteLine($"  Page {page.PageNumber}: {page.Confidence:P1}");

    var lowConfidenceWords = page.Words
        .Where(w => w.Confidence < 0.70)
        .ToList();

    foreach (var word in lowConfidenceWords)
    {
        Console.WriteLine($"    Low-confidence word: \"{word.Text}\" ({word.Confidence:P1})");
    }
}
$vbLabelText   $csharpLabel

Sortie

Affichage terminal indiquant le score de confiance, la décision d'acceptation/signalement/rejet et l'analyse détaillée des mots à faible confiance pour l'image du reçu

Ce modèle est essentiel dans les pipelines où l'OCR alimente l'entrée de données, le traitement des factures ou les workflows de conformité. L'analyse détaillée par mot permet d'identifier précisément les régions de l'image source qui ont provoqué la dégradation ; Vous pouvez ensuite appliquer des filtres de qualité d'image ou des corrections d'orientation et retraiter. Pour un regard plus approfondi sur l'évaluation des niveaux de confiance, voir le mode d'emploi sur les niveaux de confiance.

Pour les emplois de longue durée, la confiance seule ne suffit pas. Vous devez également savoir si le moteur progresse toujours, et c'est là qu'intervient l'événement OcrProgress.

Comment puis-je suivre la progression de la reconnaissance optique de caractères (OCR) en temps réel ?

Pour les documents de plusieurs pages, l'événement OcrProgress sur IronTesseract se déclenche après la fin de chaque page. L'objet OcrProgressEventArgs expose le pourcentage de progression, la durée écoulée, le nombre total de pages et les pages terminées. L'exemple utilise comme donnée d'entrée ce rapport trimestriel de trois pages : un document commercial structuré comprenant un résumé, une ventilation des revenus et des indicateurs opérationnels.

Entrée

Un rapport financier de trois pages pour le premier trimestre 2024 a été chargé via LoadPdf. La première page présente le résumé exécutif avec les indicateurs clés de performance (KPI), la deuxième contient des tableaux de revenus par gamme de produits et par région, et la troisième couvre les volumes de traitement opérationnel — chaque type de page produit un temps distinct par page que vous pouvez observer dans les rappels de progression.

quarterly_report.pdf : Rapport financier de trois pages pour le T1 2024 (résumé, ventilation des revenus, indicateurs opérationnels) utilisé pour illustrer les rappels `OcrProgress` en temps réel par page.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-progress-monitoring.cs
using IronOcr;

var ocr = new IronTesseract();

ocr.OcrProgress += (sender, e) =>
{
    Console.WriteLine(
        $"[OCR] {e.ProgressPercent}% complete | " +
        $"Page {e.PagesComplete}/{e.TotalPages} | " +
        $"Elapsed: {e.Duration.TotalSeconds:F1}s"
    );
};

using var input = new OcrInput();
input.LoadPdf("quarterly_report.pdf");

OcrResult result = ocr.Read(input);
Console.WriteLine($"Finished in {result.Pages.Count()} pages, confidence: {result.Confidence:P1}");
$vbLabelText   $csharpLabel

Sortie

Affichage dans le terminal des rappels d'événements OcrProgress par page, avec le pourcentage d'achèvement et le temps écoulé pour un PDF de trois pages

Intégrez cet événement à votre infrastructure de journalisation pour suivre la durée des tâches OCR et détecter les blocages. Si la durée écoulée dépasse un seuil sans que le pourcentage de progression n'augmente, le pipeline peut signaler la tâche pour enquête. Cela est particulièrement utile pour le traitement par lots de PDF où une seule page malformée peut bloquer l'ensemble du travail.

Le suivi de la progression indique l'état d'exécution, mais une défaillance au niveau d'un fichier peut tout de même interrompre le traitement par lots entier si elle n'est pas isolée.

Comment gérer les erreurs dans les pipelines OCR par lots ?

En production, la défaillance d'un seul fichier ne doit pas interrompre le traitement par lots entier. Isoler les erreurs par fichier, consigner les échecs avec leur contexte et générer un rapport de synthèse à la fin. L'exemple traite un dossier de documents numérisés contenant une facture, un bon de commande et un contrat de service, Plus qu'un fichier intentionnellement corrompu pour déclencher le chemin d'erreur. Un échantillon représentatif est présenté ci-dessous :

Entrée

Un dossier de fichiers PDF a été transmis à Directory.GetFiles : une facture, un bon de commande, un contrat de service et un fichier intentionnellement corrompu. Les deux exemples ci-dessous illustrent la variété des documents traités par le pipeline en une seule exécution.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-batch-pipeline.cs
using IronOcr;
using IronOcr.Exceptions;

var ocr = new IronTesseract();
Installation.LogFilePath = "batch_debug.log";
Installation.LoggingMode = Installation.LoggingModes.File;

string[] files = Directory.GetFiles("scans/", "*.pdf");
int succeeded = 0, failed = 0;
double totalConfidence = 0;
var failures = new List<(string File, string Error)>();

foreach (string file in files)
{
    try
    {
        using var input = new OcrInput();
        input.LoadPdf(file);

        OcrResult result = ocr.Read(input);
        totalConfidence += result.Confidence;
        succeeded++;

        Console.WriteLine($"OK: {Path.GetFileName(file)} — {result.Confidence:P1}");
    }
    catch (IronOcrInputException ex)
    {
        failed++;
        failures.Add((file, $"Input error: {ex.Message}"));
        Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.Message}");
    }
    catch (IronOcrProductException ex)
    {
        failed++;
        failures.Add((file, $"Engine error: {ex.Message}"));
        Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.Message}");
    }
    catch (Exception ex)
    {
        failed++;
        failures.Add((file, $"Unexpected: {ex.Message}"));
        Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.GetType().Name}: {ex.Message}");
    }
}

// Summary report
Console.WriteLine($"\n--- Batch Summary ---");
Console.WriteLine($"Total: {files.Length} | Passed: {succeeded} | Failed: {failed}");
if (succeeded > 0)
    Console.WriteLine($"Average confidence: {totalConfidence / succeeded:P1}");

foreach (var (f, err) in failures)
    Console.WriteLine($"  {Path.GetFileName(f)}: {err}");
$vbLabelText   $csharpLabel

Sortie

Sortie du terminal affichant les résultats du traitement par lots avec le nombre de caractères par fichier, les scores de confiance, une erreur provenant d'un PDF corrompu et une ligne de résumé.

Le bloc de gestion externe traite les erreurs imprévues, notamment les délais d'attente réseau sur le stockage partagé, les problèmes d'autorisation ou les conditions de mémoire insuffisante sur les fichiers TIFF volumineux. Chaque échec enregistre le chemin du fichier et le message d'erreur pour le résumé, tandis que la boucle continue à traiter les fichiers restants. Le fichier journal à batch_debug.log capture les détails au niveau du moteur pour tout fichier qui déclenche des diagnostics internes.

Pour une exécution non bloquante dans les services ou les applications Web, IronOCR prend en charge ReadAsync , qui utilise la même structure try-catch.

Si le processus s'exécute sans erreur mais que le texte extrait est toujours incorrect, la cause première est presque toujours la qualité de l'image plutôt que le code. Voici comment remédier à cela.

Comment puis-je déboguer la précision de la reconnaissance optique de caractères (OCR) ?

Si les scores de confiance sont constamment faibles, le problème provient de l'image source et non du moteur OCR. IronOCR propose des outils de prétraitement pour y remédier :

Pour les problèmes spécifiques au déploiement, IronOCR propose des guides de dépannage dédiés à Azure Functions , Docker et Linux , ainsi qu'à la configuration générale de l'environnement .

Où devrais-je aller ensuite ?

Maintenant que vous savez comment déboguer IronOCR en cours d'exécution, explorez :

Pour une utilisation en production, pensez à obtenir une licence pour supprimer les filigranes et accéder à toutes les fonctionnalités.

Curtis Chau
Rédacteur technique

Curtis Chau détient un baccalauréat en informatique (Université de Carleton) et se spécialise dans le développement front-end avec expertise en Node.js, TypeScript, JavaScript et React. Passionné par la création d'interfaces utilisateur intuitives et esthétiquement plaisantes, Curtis aime travailler avec des frameworks modernes ...

Lire la suite
Prêt à commencer?
Nuget Téléchargements 5,556,263 | Version : 2026.3 vient de sortir
Still Scrolling Icon

Vous faites encore défiler ?

Vous voulez une preuve rapidement ? PM > Install-Package IronOcr
lancez un échantillon regardez votre image se transformer en texte consultable.