Como Depurar OCR em C

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

O IronOCR permite detectar falhas de OCR na origem, avaliar a qualidade do reconhecimento em nível de palavra e caractere e monitorar tarefas de longa duração em tempo real. Ferramentas integradas, como registro de arquivos de diagnóstico, hierarquia de exceções tipadas, pontuação de confiança por resultado e o evento OcrProgress, dão suporte a esses fluxos de trabalho em pipelines de produção.

Este guia apresenta exemplos práticos para cada um dos seguintes tópicos: ativação do registro de diagnóstico, tratamento de exceções tipadas, validação da saída com pontuações de confiança, monitoramento do progresso do trabalho em tempo real e isolamento de erros em pipelines de lote.

Início rápido: Ativar registro completo de diagnóstico de OCR

Defina LogFilePath e LoggingModo na classe Installation antes da primeira chamada Read. Basta ter duas propriedades para capturar a inicialização do Tesseract, o carregamento do pacote de idiomas e os detalhes de processamento em um arquivo de log.

  1. Instale IronOCR com o Gerenciador de Pacotes NuGet

    PM > Install-Package IronOcr
  2. Copie e execute este trecho de código.

    IronOcr.Installation.LogFilePath = "ocr.log"; IronOcr.Installation.LoggingModo = IronOcr.Installation.LoggingModos.All;
  3. Implante para testar em seu ambiente de produção.

    Comece a usar IronOCR em seu projeto hoje com uma avaliação gratuita

    arrow pointer


Como faço para ativar o registro de diagnóstico?

A classe Installation expõe três controles de registro. Defina esses valores antes de chamar qualquer método 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

LoggingModo aceita valores de sinalizador da enumeração LoggingModos :

Tabela 1: Opções de modos de registro
ModoAlvo de SaídaCaso de uso
NenhumDesativadoProdução com monitoramento externo
DebugJanela de saída de depuração do IDEDesenvolvimento local
ArquivoCaminhoDoArquivoDeLogColeta de log do lado do servidor
TodosDebug + ArquivoCaptura de diagnóstico completa

A propriedade CustomLogger é compatível com qualquer implementação de Microsoft.Extensions.Logging.ILogger, permitindo direcionar diagnósticos de OCR para Serilog, NLog ou outros coletores de logs estruturados em seu pipeline. Use ClearLogFiles para remover dados de log acumulados entre execuções.

Com o sistema de registro de logs implementado, o próximo passo é entender quais exceções o IronOCR pode gerar e como lidar com cada uma delas.

Que exceções o IronOCR gera?

O IronOCR define exceções tipadas no namespace IronOcr.Exceçãos . Ao capturar esses erros especificamente, em vez de usar um bloco de captura genérico, você pode direcionar cada tipo de falha para o caminho de correção correto.

Tabela 2: Referência de Exceções do IronOCR
ExceçãoCausa ComumCorreção
IronOcrInputExceçãoImagem/PDF corrompido ou não suportadoValide o arquivo antes de carregá-lo em OcrInput
IronOcrProductExceçãoErro interno do motor durante a execução do OCRAtivar log, verificar saída de log, atualizar para a última versão do NuGet
IronOcrDictionaryExceçãoArquivo de idioma .traineddata ausente ou corrompidoReinstale o pacote de idiomas NuGet ou defina LanguagePackDirectory .
IronOcrNativeExceçãoFalha na interoperabilidade nativa do C++Instale Visual C++ Redistributable; verifique o suporte a AVX
IronOcrLicensingExceçãoChave de licença ausente ou expiradaDefina LicenseKey antes de chamar a Read
LanguagePackExceçãoPacote de idiomas não encontrado no caminho esperadoVerifique LanguagePackDirectory ou reinstale o pacote de idiomas NuGet
IronOcrAssemblyVersionMismatchExceçãoVersões de assembly incompatíveis após atualização parcialLimpe o cache do NuGet, restaure os pacotes, verifique se todos os pacotes IronOCR correspondem

Utilize o seguinte bloco try-catch para tratar cada tipo de exceção separadamente, aplicando filtros de exceção para registro condicional.

Entrada

Uma fatura de fornecedor de página única da IronOCR Solutions para a Acme Corporation, carregada via LoadPdf em OcrInput. Inclui quatro itens de linha, impostos e um total geral — variedade de texto suficiente para proporcionar a cada manipulador de exceções um exercício realista.

invoice_scan.pdf: Fatura do fornecedor (nº INV-2024-7829) usada para demonstrar cada manipulador de exceção tipado em sequência.

: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

Saída

Resultado bem-sucedido

A fatura é carregada corretamente e o mecanismo retorna a contagem de caracteres juntamente com uma pontuação de confiança.

Saída do terminal mostrando a leitura OCR bem-sucedida do arquivo invoice_scan.pdf, com contagem de caracteres e pontuação de confiança.

Saída com falha

Saída do terminal mostrando a exceção lançada ao carregar um arquivo PDF ausente.

Ordene os blocos de captura do mais específico para o mais geral. A cláusula when em IronOcrNativeExceção filtra falhas relacionadas ao AVX sem capturar erros nativos não relacionados. Cada manipulador registra a mensagem de exceção; O bloco "catch-all" também captura o rastreamento da pilha para análise posterior.

Identificar a exceção correta indica que algo deu errado, mas não o quão bem o motor se comportou quando obteve sucesso. Para isso, utilize índices de confiança.

Como validar os resultados do OCR com níveis de confiança?

Cada OcrResult expõe uma propriedade Confidence, um valor entre 0 e 1 que representa a certeza estatística do mecanismo, calculada em média para todos os caracteres reconhecidos. Você pode acessar isso em todos os níveis da hierarquia de resultados: documento , página ,parágrafo , palavra ecaractere .

Utilize um padrão de limiar para impedir que resultados de baixa qualidade se propaguem a jusante.

Entrada

Um recibo térmico com itens discriminados, descontos, totais e um código de barras, carregado via LoadImage. Sua largura estreita, fonte monoespaçada e impressão tênue fazem dele um teste de estresse prático para limites de confiança por palavra.

Exemplo de recibo térmico do FoodMart mostrando as compras detalhadas, os totais e os pontos de recompensa usados ​​como entrada para OCR.

receipt.png: Imagem de um recibo escaneado termicamente, utilizada para demonstrar a validação de confiança com base em limiares e a análise detalhada da precisão por palavra.

: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

Saída

Saída do terminal mostrando a pontuação de confiança, a decisão de aceitar/sinalizar/rejeitar e um detalhamento por palavra com baixa confiança para a imagem do recibo.

Este padrão é essencial em pipelines onde o OCR alimenta entrada de dados, processamento de faturas ou fluxos de trabalho de conformidade. A análise detalhada por palavra identifica exatamente quais regiões da imagem de origem causaram degradação; Em seguida, você pode aplicar filtros de qualidade de imagem ou correções de orientação e reprocessar. Para um olhar mais profundo sobre a pontuação de confiança, veja o guia de níveis de confiança.

Para empregos de longa duração, a confiança por si só não basta. Você também precisa saber se o motor ainda está progredindo, e é aí que entra o evento OcrProgress.

Como posso monitorar o progresso do OCR em tempo real?

Para documentos com várias páginas, o evento OcrProgress em IronTesseract é acionado após a conclusão de cada página. O objeto OcrProgressEventArgs expõe a porcentagem de progresso, a duração decorrida, o total de páginas e as páginas concluídas. O exemplo utiliza como entrada este relatório trimestral de três páginas: um documento comercial estruturado que abrange um resumo executivo, detalhamento da receita e métricas operacionais.

Entrada

Um relatório financeiro de três páginas referente ao primeiro trimestre de 2024 foi carregado via LoadPdf. A primeira página apresenta o resumo executivo com as métricas de KPIs, a segunda contém tabelas de receita por linha de produto e região, e a terceira aborda os volumes de processamento operacional — cada tipo de página gera um tempo específico que você pode observar nos retornos de chamada de progresso.

quarterly_report.pdf: Relatório financeiro de três páginas do primeiro trimestre de 2024 (resumo executivo, detalhamento da receita, métricas operacionais) usado para demonstrar os retornos de chamada `OcrProgress` em tempo real por página.

: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

Saída

Saída do terminal mostrando os retornos de chamada do evento OcrProgress por página, com a porcentagem de conclusão e o tempo decorrido para um PDF de três páginas.

Integre esse evento à sua infraestrutura de registro para monitorar a duração do trabalho de OCR e detectar paralisações. Se a duração decorrida exceder um limite sem que a porcentagem de progresso avance, o pipeline poderá sinalizar a tarefa para investigação. Isso é particularmente útil para processamento em lote de PDFs, onde uma única página malformada pode atrasar o trabalho inteiro.

O monitoramento do progresso mostra o estado da execução, mas uma falha em nível de arquivo ainda pode interromper todo o lote prematuramente se não for isolada.

Como lidar com erros em pipelines de OCR em lote?

Em produção, a falha de um único arquivo não deve interromper todo o lote. Isolar erros por arquivo, registrar falhas com contexto e gerar um relatório resumido ao final. O exemplo processa uma pasta de documentos digitalizados contendo uma fatura, uma ordem de compra e um contrato de serviço, Plus de um arquivo intencionalmente corrompido para acionar o caminho de erro. Segue abaixo um exemplo representativo:

Entrada

Uma pasta de PDFs foi passada para Directory.GetFiles — uma fatura, uma ordem de compra, um contrato de serviço e um arquivo intencionalmente corrompido. Os dois exemplos representativos abaixo mostram a variedade de documentos que o pipeline processa em uma única execução.

: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

Saída

Saída do terminal mostrando os resultados do pipeline em lote com contagens de caracteres por arquivo, pontuações de confiança, um erro de um PDF corrompido e uma linha de resumo.

O bloco catch externo lida com erros imprevistos, incluindo timeouts de rede em armazenamento compartilhado, problemas de permissão ou condições de falta de memória em arquivos TIFF grandes. Cada falha registra o caminho do arquivo e a mensagem de erro para o resumo, enquanto o loop continua processando os arquivos restantes. O arquivo de registro em batch_debug.log captura detalhes em nível de mecanismo para qualquer arquivo que acione diagnósticos internos.

Para execução não bloqueante em serviços ou aplicações web, o IronOCR suporta ReadAsync , que usa a mesma estrutura try-catch.

Se o pipeline for executado sem erros, mas o texto extraído ainda estiver incorreto, a causa principal é quase sempre a qualidade da imagem, e não o código. Eis como resolver isso.

Como posso depurar a precisão do OCR?

Se os níveis de confiança forem consistentemente baixos, o problema está na imagem de origem e não no mecanismo de OCR. O IronOCR oferece ferramentas de pré-processamento para solucionar esse problema:

Aplique filtros de qualidade de imagem, como nitidez, redução de ruído, dilatação e erosão, para melhorar a clareza do texto.

Para problemas específicos de implantação, a IronOCR mantém guias de solução de problemas dedicados para Azure Functions , Docker e Linux , além de guias para configuração geral do ambiente .

Para onde devo ir em seguida?

Agora que você entende como depurar o IronOCR em tempo de execução, explore:

Para uso em produção, lembre-se de obter uma licença para remover marcas d'água e acessar a funcionalidade completa.

Curtis Chau
Redator Técnico

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais ...

Leia mais
Pronto para começar?
Nuget Downloads 5,556,263 | Versão: 2026.3 acaba de ser lançado
Still Scrolling Icon

Ainda está rolando a tela?

Quer provas rápidas? PM > Install-Package IronOcr
executar um exemplo Veja sua imagem se transformar em texto pesquisável.