Como Depurar a Leitura de Texto com IronOCR em C
O IronOCR permite detectar falhas ao converter imagem em texto, 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.
-
Instale IronOCR com o Gerenciador de Pacotes NuGet
PM > Install-Package IronOcr -
Copie e execute este trecho de código.
IronOcr.Installation.LogFilePath = "ocr.log"; IronOcr.Installation.LoggingModo = IronOcr.Installation.LoggingModos.All; -
Implante para testar em seu ambiente de produção.
Comece a usar IronOCR em seu projeto hoje com uma avaliação gratuita
Fluxo de trabalho mínimo (5 etapas)
- Baixe uma biblioteca C# para depurar OCR.
- Defina
CaminhoDoArquivoDeLogpara um caminho de arquivo gravável. - Defina
LoggingModocomoTodospara captura de diagnóstico completa. - Execute sua operação de OCR e reproduza o problema
- Inspecione o arquivo de log gerado para avisos do motor e detalhes do processamento
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;
Imports 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
LoggingMode aceita valores de sinalizador da enumeração LoggingModes :
| Modo | Alvo de Saída | Caso de uso |
|---|---|---|
Nenhum | Desativado | Produção com monitoramento externo |
Debug | Janela de saída de depuração do IDE | Desenvolvimento local |
Arquivo | CaminhoDoArquivoDeLog | Coleta de log do lado do servidor |
Todos | Debug + Arquivo | Captura 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.Exceptions . 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.
| Exceção | Causa Comum | Correção |
|---|---|---|
IronOcrInputExceção | Imagem/PDF corrompido ou não suportado | Valide o arquivo antes de carregá-lo em OcrInput |
IronOcrProductExceção | Erro interno do motor durante a execução do OCR | Ativar log, verificar saída de log, atualizar para a última versão do NuGet |
IronOcrDictionaryExceção | Arquivo de idioma .traineddata ausente ou corrompido | Reinstale o pacote de idiomas NuGet ou defina LanguagePackDirectory . |
IronOcrNativeExceção | Falha na interoperabilidade nativa do C++ | Instale Visual C++ Redistributable; verifique o suporte a AVX |
IronOcrLicensingExceção | Chave de licença ausente ou expirada | Defina LicenseKey antes de chamar a Read |
LanguagePackExceção | Pacote de idiomas não encontrado no caminho esperado | Verifique LanguagePackDirectory ou reinstale o pacote de idiomas NuGet |
IronOcrAssemblyVersionMismatchExceção | Versões de assembly incompatíveis após atualização parcial | Limpe 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}");
}
Imports IronOcr
Imports IronOcr.Exceptions
Dim ocr As New IronTesseract()
Try
Using input As New OcrInput()
input.LoadPdf("invoice_scan.pdf")
Dim result As OcrResult = ocr.Read(input)
Console.WriteLine($"Text: {result.Text}")
Console.WriteLine($"Confidence: {result.Confidence:P1}")
End Using
Catch ex As IronOcrInputException
' File could not be loaded — corrupt, locked, or unsupported format
Console.Error.WriteLine($"Input error: {ex.Message}")
Catch ex As IronOcrDictionaryException
' Language pack missing — common in containerized deployments
Console.Error.WriteLine($"Language pack error: {ex.Message}")
Catch ex As IronOcrNativeException When ex.Message.Contains("AVX")
' CPU does not support AVX instructions
Console.Error.WriteLine($"Hardware incompatibility: {ex.Message}")
Catch ex As IronOcrLicensingException
Console.Error.WriteLine("License key is missing or invalid.")
Catch ex As IronOcrProductException
' Catch-all for other IronOCR engine errors
Console.Error.WriteLine($"OCR engine error: {ex.Message}")
Console.Error.WriteLine($"Stack trace: {ex.StackTrace}")
End Try
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 com falha
Ordene os blocos de captura do mais específico para o mais geral. A cláusula when em IronOcrNativeExceptions 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.
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})");
}
}
Imports IronOcr
Dim ocr As New IronTesseract()
Using input As New OcrInput()
input.LoadImage("receipt.png")
Dim result As OcrResult = ocr.Read(input)
Dim confidence As Double = result.Confidence
Console.WriteLine($"Overall confidence: {confidence:P1}")
' Threshold-gated decision
If confidence >= 0.9 Then
Console.WriteLine("ACCEPT — high confidence, processing result.")
ProcessResult(result.Text)
ElseIf confidence >= 0.7 Then
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)
End If
' Drill into per-page and per-word confidence for diagnostics
For Each page In result.Pages
Console.WriteLine($" Page {page.PageNumber}: {page.Confidence:P1}")
Dim lowConfidenceWords = page.Words _
.Where(Function(w) w.Confidence < 0.7) _
.ToList()
For Each word In lowConfidenceWords
Console.WriteLine($" Low-confidence word: ""{word.Text}"" ({word.Confidence:P1})")
Next
Next
End Using
Saída
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}");
Imports IronOcr
Dim ocr = New IronTesseract()
AddHandler ocr.OcrProgress, Sub(sender, e)
Console.WriteLine(
$"[OCR] {e.ProgressPercent}% complete | " &
$"Page {e.PagesComplete}/{e.TotalPages} | " &
$"Elapsed: {e.Duration.TotalSeconds:F1}s"
)
End Sub
Using input As New OcrInput()
input.LoadPdf("quarterly_report.pdf")
Dim result As OcrResult = ocr.Read(input)
Console.WriteLine($"Finished in {result.Pages.Count()} pages, confidence: {result.Confidence:P1}")
End Using
Saída
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.
batch-scan-01.pdf: Fatura da Bright Horizon Ltd. (INV-2024-001) — OCR aprovado.
batch-scan-02.pdf: Pedido de compra da TechSupply Inc. (PO-2024-042) — segundo tipo de documento na mesma 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}");
Imports IronOcr
Imports IronOcr.Exceptions
Imports System.IO
Dim ocr As New IronTesseract()
Installation.LogFilePath = "batch_debug.log"
Installation.LoggingMode = Installation.LoggingModes.File
Dim files As String() = Directory.GetFiles("scans/", "*.pdf")
Dim succeeded As Integer = 0
Dim failed As Integer = 0
Dim totalConfidence As Double = 0
Dim failures As New List(Of (File As String, Error As String))()
For Each file As String In files
Try
Using input As New OcrInput()
input.LoadPdf(file)
Dim result As OcrResult = ocr.Read(input)
totalConfidence += result.Confidence
succeeded += 1
Console.WriteLine($"OK: {Path.GetFileName(file)} — {result.Confidence:P1}")
End Using
Catch ex As IronOcrInputException
failed += 1
failures.Add((file, $"Input error: {ex.Message}"))
Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.Message}")
Catch ex As IronOcrProductException
failed += 1
failures.Add((file, $"Engine error: {ex.Message}"))
Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.Message}")
Catch ex As Exception
failed += 1
failures.Add((file, $"Unexpected: {ex.Message}"))
Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.GetType().Name}: {ex.Message}")
End Try
Next
' Summary report
Console.WriteLine(vbCrLf & "--- Batch Summary ---")
Console.WriteLine($"Total: {files.Length} | Passed: {succeeded} | Failed: {failed}")
If succeeded > 0 Then
Console.WriteLine($"Average confidence: {totalConfidence / succeeded:P1}")
End If
For Each failure In failures
Console.WriteLine($" {Path.GetFileName(failure.File)}: {failure.Error}")
Next
Saída
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.
- Utilize a correção de orientação para corrigir automaticamente a inclinação e a rotação de documentos digitalizados.
- Ajuste a configuração de DPI para imagens de baixa resolução antes do processamento.
- Utilizar visão computacional para detectar e isolar regiões de texto em layouts complexos. O utilitário IronOCR permite testar visualmente combinações de filtros e exportar a configuração ideal em C#.
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:
- Navegação na estrutura de resultados e metadados do OCR, incluindo páginas, blocos, parágrafos, palavras e coordenadas.
- Compreender a pontuação de confiança em todos os níveis da hierarquia de resultados
- Utilizando processamento assíncrono e multithreading com
ReadAsyncpara pipelines de alto desempenho - Consulte a referência completa da API para obter a lista completa de propriedades.
Para uso em produção, lembre-se de obter uma licença para remover marcas d'água e acessar a funcionalidade completa.
Perguntas frequentes
Quais são os problemas comuns ao depurar OCR em C#?
Problemas comuns incluem resultados de OCR incorretos, baixos níveis de confiança e exceções inesperadas. O IronOCR oferece ferramentas como registro de logs e pontuação de confiança para ajudar a identificar e resolver esses problemas.
Como o IronOCR auxilia no tratamento de erros em C#?
O IronOCR oferece exceções tipadas e mensagens de erro detalhadas, o que auxilia na compreensão e no tratamento eficaz de erros durante a operação de OCR em aplicações C#.
Quais recursos de registro o IronOCR oferece para depuração?
O IronOCR inclui recursos de registro integrados que ajudam a monitorar os processos de OCR e identificar possíveis problemas, registrando informações detalhadas sobre as operações de OCR.
Como a pontuação de confiança pode melhorar os resultados do OCR?
A pontuação de confiança no IronOCR ajuda a determinar a precisão do texto reconhecido, permitindo que os desenvolvedores se concentrem em áreas de baixa confiança e melhorem os resultados do OCR.
Posso acompanhar o progresso das tarefas de OCR usando o IronOCR?
Sim, o IronOCR oferece recursos de acompanhamento de progresso que permitem aos desenvolvedores monitorar o status e a duração das tarefas de OCR, facilitando um melhor gerenciamento de recursos e a otimização do desempenho.
Quais padrões try-catch são recomendados para o tratamento de erros em OCR?
A IronOCR sugere o uso de padrões try-catch prontos para produção para lidar com exceções de forma adequada, garantindo que os aplicativos de OCR permaneçam robustos e de fácil manutenção.
Como as ferramentas integradas do IronOCR podem aprimorar a depuração de OCR?
As ferramentas do IronOCR, como registro de logs, exceções tipadas e pontuação de confiança, oferecem suporte abrangente para identificar e resolver problemas, aprimorando assim o processo de depuração.
Por que o registro de erros é importante em aplicações de OCR?
O registro de erros é crucial, pois fornece informações sobre o que deu errado durante o processamento de OCR, permitindo que os desenvolvedores diagnostiquem e corrijam rapidamente os problemas em seus aplicativos.
Qual o papel das exceções tipadas na depuração do IronOCR?
As exceções tipadas no IronOCR fornecem informações específicas sobre o erro, facilitando aos desenvolvedores a compreensão da natureza do problema e a aplicação de soluções adequadas durante a depuração.
Como os desenvolvedores podem se beneficiar dos recursos de depuração do IronOCR?
Os desenvolvedores podem aproveitar os recursos de depuração do IronOCR para solucionar problemas com eficiência, aumentar a estabilidade do aplicativo e melhorar a qualidade geral dos resultados de OCR.

