Migrando do Aspose.OCR para o IronOCR

O problema fundamental

O Aspose.OCR vincula a configuração de reconhecimento a um objeto de configurações que deve ser construído, preenchido e passado em cada chamada. O modo, o idioma, os filtros e a estratégia de área são todos propriedades desse objeto:

// Aspose.OCR: build a settings object for every recognition call
var api = new AsposeOcr();
var settings = new RecognitionSettings
{
    Language = Language.Eng,
    DetectAreasMode = DetectAreasMode.DOCUMENT, // must choose the right mode
    RecognizeSingleLine = false,
    AutoSkew = true
};
var result = api.RecognizeImage("form.jpg", settings);
string text = result.RecognitionText;

// Aspose.OCR: build a settings object for every recognition call
var api = new AsposeOcr();
var settings = new RecognitionSettings
{
    Language = Language.Eng,
    DetectAreasMode = DetectAreasMode.DOCUMENT, // must choose the right mode
    RecognizeSingleLine = false,
    AutoSkew = true
};
var result = api.RecognizeImage("form.jpg", settings);
string text = result.RecognitionText;

Imports Aspose.OCR

' Aspose.OCR: build a settings object for every recognition call
Dim api As New AsposeOcr()
Dim settings As New RecognitionSettings With {
    .Language = Language.Eng,
    .DetectAreasMode = DetectAreasMode.DOCUMENT, ' must choose the right mode
    .RecognizeSingleLine = False,
    .AutoSkew = True
}
Dim result = api.RecognizeImage("form.jpg", settings)
Dim text As String = result.RecognitionText

IronOCR usa uma única chamada .Read(). A configuração fica no caso da instância IronTesseract quando necessário, não em um objeto por chamada:

// IronOCR: one call, no settings object required
var text = new IronTesseract().Read("form.jpg").Text;

// IronOCR: one call, no settings object required
var text = new IronTesseract().Read("form.jpg").Text;

Imports IronOcr

Dim text As String = New IronTesseract().Read("form.jpg").Text

Passo 1: Substitua o pacote NuGet

Remover Aspose.OCR:

dotnet remove package Aspose.OCR

dotnet remove package Aspose.OCR

Instale o IronOCR a partir do NuGet :

dotnet add package IronOcr

Etapa 2: Atualizar Namespaces

Substitua todas as importações de namespace Aspose.OCR:

// Before (Aspose.OCR)
using Aspose.OCR;
using Aspose.OCR.Models;
using Aspose.OCR.Models.PreprocessingFilters;

// After (IronOCR)
using IronOcr;

// Before (Aspose.OCR)
using Aspose.OCR;
using Aspose.OCR.Models;
using Aspose.OCR.Models.PreprocessingFilters;

// After (IronOCR)
using IronOcr;

Imports IronOcr

Etapa 3: Inicializar a licença

Remova a chamada de licença baseada em arquivo da Aspose e substitua-a pela chave de string do IronOCR. Coloque isso na inicialização do aplicativo — uma vez por processo, não uma vez por solicitação:

// Remove Aspose license setup
// var license = new Aspose.OCR.License();
// license.SetLicense("Aspose.OCR.lic");

// Add IronOCR license at startup
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";

// Production pattern: read from environment variable
IronOcr.License.LicenseKey = Environment.GetEnvironmentVariable("IRONOCR_LICENSE");

// Remove Aspose license setup
// var license = new Aspose.OCR.License();
// license.SetLicense("Aspose.OCR.lic");

// Add IronOCR license at startup
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";

// Production pattern: read from environment variable
IronOcr.License.LicenseKey = Environment.GetEnvironmentVariable("IRONOCR_LICENSE");

' Remove Aspose license setup
' Dim license As New Aspose.OCR.License()
' license.SetLicense("Aspose.OCR.lic")

' Add IronOCR license at startup
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY"

' Production pattern: read from environment variable
IronOcr.License.LicenseKey = Environment.GetEnvironmentVariable("IRONOCR_LICENSE")

Configuração das definições de reconhecimento

Aspose.OCR centraliza todo o comportamento de reconhecimento em um objeto RecognitionSettings. Idioma, modo de detecção de área, sinalizador de linha única e limite, tudo isso está disponível como propriedades. Você o constrói do zero para cada tipo de documento ou padrão de chamada.

Abordagem Aspose.OCR:

// Configuring recognition settings for a structured form
var api = new AsposeOcr();

var settings = new RecognitionSettings
{
    Language = Language.Eng,
    DetectAreasMode = DetectAreasMode.DOCUMENT,
    RecognizeSingleLine = false,
    AutoSkew = true,
    RecognitionAreas = new List<Rectangle>
    {
        new Rectangle(0, 0, 800, 100)  // header zone
    }
};

var result = api.RecognizeImage("structured-form.jpg", settings);
Console.WriteLine(result.RecognitionText);

// Configuring recognition settings for a structured form
var api = new AsposeOcr();

var settings = new RecognitionSettings
{
    Language = Language.Eng,
    DetectAreasMode = DetectAreasMode.DOCUMENT,
    RecognizeSingleLine = false,
    AutoSkew = true,
    RecognitionAreas = new List<Rectangle>
    {
        new Rectangle(0, 0, 800, 100)  // header zone
    }
};

var result = api.RecognizeImage("structured-form.jpg", settings);
Console.WriteLine(result.RecognitionText);

Imports System
Imports System.Collections.Generic
Imports AsposeOcr

' Configuring recognition settings for a structured form
Dim api As New AsposeOcr()

Dim settings As New RecognitionSettings With {
    .Language = Language.Eng,
    .DetectAreasMode = DetectAreasMode.DOCUMENT,
    .RecognizeSingleLine = False,
    .AutoSkew = True,
    .RecognitionAreas = New List(Of Rectangle) From {
        New Rectangle(0, 0, 800, 100)  ' header zone
    }
}

Dim result = api.RecognizeImage("structured-form.jpg", settings)
Console.WriteLine(result.RecognitionText)

Abordagem IronOCR:

// Recognition behavior configured once on the IronTesseract instance
var ocr = new IronTesseract();
ocr.Language = OcrLanguage.English;

// Region targeting replaces RecognitionAreas in RecognitionSettings
var headerRegion = new CropRectangle(0, 0, 800, 100);
using var input = new OcrInput();
input.LoadImage("structured-form.jpg", headerRegion);

var result = ocr.Read(input);
Console.WriteLine(result.Text);

// Recognition behavior configured once on the IronTesseract instance
var ocr = new IronTesseract();
ocr.Language = OcrLanguage.English;

// Region targeting replaces RecognitionAreas in RecognitionSettings
var headerRegion = new CropRectangle(0, 0, 800, 100);
using var input = new OcrInput();
input.LoadImage("structured-form.jpg", headerRegion);

var result = ocr.Read(input);
Console.WriteLine(result.Text);

Imports IronOcr

' Recognition behavior configured once on the IronTesseract instance
Dim ocr As New IronTesseract()
ocr.Language = OcrLanguage.English

' Region targeting replaces RecognitionAreas in RecognitionSettings
Dim headerRegion As New CropRectangle(0, 0, 800, 100)
Using input As New OcrInput()
    input.LoadImage("structured-form.jpg", headerRegion)

    Dim result = ocr.Read(input)
    Console.WriteLine(result.Text)
End Using

Não há nenhum objeto de configurações para construir por chamada. A linguagem vai na instância IronTesseract; a seleção de região vai em OcrInput no tempo de carga. As decisões DetectAreasMode e RecognizeSingleLine são manejadas automaticamente pelo motor. Para obter orientações detalhadas sobre OCR baseado em região, consulte o guia prático de OCR baseado em região .

Migração do Modo de Detecção de Área

Aspose.OCR requer que você escolha um valor DetectAreasMode antes de cada chamada de reconhecimento. COMBINE mescla texto de diferentes regiões de layout, DOCUMENT trata a imagem como um documento padrão, TABLE otimiza para layouts em grade. Selecionar o modo errado para o tipo de documento causa desalinhamento ou ausência de saída.

Abordagem Aspose.OCR:

// Three separate calls with different modes for different document types
var api = new AsposeOcr();

// For a document with mixed prose and table content
var docSettings = new RecognitionSettings
{
    DetectAreasMode = DetectAreasMode.COMBINE,
    Language = Language.Eng
};

// For a pure tabular document
var tableSettings = new RecognitionSettings
{
    DetectAreasMode = DetectAreasMode.TABLE,
    Language = Language.Eng
};

// For a single-column text document
var linearSettings = new RecognitionSettings
{
    DetectAreasMode = DetectAreasMode.DOCUMENT,
    Language = Language.Eng
};

string mixedResult = api.RecognizeImage("mixed-layout.jpg", docSettings).RecognitionText;
string tableResult = api.RecognizeImage("data-table.jpg", tableSettings).RecognitionText;
string linearResult = api.RecognizeImage("text-document.jpg", linearSettings).RecognitionText;

// Three separate calls with different modes for different document types
var api = new AsposeOcr();

// For a document with mixed prose and table content
var docSettings = new RecognitionSettings
{
    DetectAreasMode = DetectAreasMode.COMBINE,
    Language = Language.Eng
};

// For a pure tabular document
var tableSettings = new RecognitionSettings
{
    DetectAreasMode = DetectAreasMode.TABLE,
    Language = Language.Eng
};

// For a single-column text document
var linearSettings = new RecognitionSettings
{
    DetectAreasMode = DetectAreasMode.DOCUMENT,
    Language = Language.Eng
};

string mixedResult = api.RecognizeImage("mixed-layout.jpg", docSettings).RecognitionText;
string tableResult = api.RecognizeImage("data-table.jpg", tableSettings).RecognitionText;
string linearResult = api.RecognizeImage("text-document.jpg", linearSettings).RecognitionText;

Imports AsposeOcr

' Three separate calls with different modes for different document types
Dim api As New AsposeOcr()

' For a document with mixed prose and table content
Dim docSettings As New RecognitionSettings With {
    .DetectAreasMode = DetectAreasMode.COMBINE,
    .Language = Language.Eng
}

' For a pure tabular document
Dim tableSettings As New RecognitionSettings With {
    .DetectAreasMode = DetectAreasMode.TABLE,
    .Language = Language.Eng
}

' For a single-column text document
Dim linearSettings As New RecognitionSettings With {
    .DetectAreasMode = DetectAreasMode.DOCUMENT,
    .Language = Language.Eng
}

Dim mixedResult As String = api.RecognizeImage("mixed-layout.jpg", docSettings).RecognitionText
Dim tableResult As String = api.RecognizeImage("data-table.jpg", tableSettings).RecognitionText
Dim linearResult As String = api.RecognizeImage("text-document.jpg", linearSettings).RecognitionText

Abordagem IronOCR:

// Single API surface handles all layout types automatically
var ocr = new IronTesseract();

// Same code path for every document type
var mixedResult = ocr.Read("mixed-layout.jpg").Text;
var tableResult = ocr.Read("data-table.jpg").Text;
var linearResult = ocr.Read("text-document.jpg").Text;

// For table documents, structured data is immediately available
var result = ocr.Read("data-table.jpg");
foreach (var page in result.Pages)
{
    foreach (var paragraph in page.Paragraphs)
    {
        Console.WriteLine($"Block at ({paragraph.X}, {paragraph.Y}): {paragraph.Text}");
    }
}

// Single API surface handles all layout types automatically
var ocr = new IronTesseract();

// Same code path for every document type
var mixedResult = ocr.Read("mixed-layout.jpg").Text;
var tableResult = ocr.Read("data-table.jpg").Text;
var linearResult = ocr.Read("text-document.jpg").Text;

// For table documents, structured data is immediately available
var result = ocr.Read("data-table.jpg");
foreach (var page in result.Pages)
{
    foreach (var paragraph in page.Paragraphs)
    {
        Console.WriteLine($"Block at ({paragraph.X}, {paragraph.Y}): {paragraph.Text}");
    }
}

Imports System

' Single API surface handles all layout types automatically
Dim ocr As New IronTesseract()

' Same code path for every document type
Dim mixedResult As String = ocr.Read("mixed-layout.jpg").Text
Dim tableResult As String = ocr.Read("data-table.jpg").Text
Dim linearResult As String = ocr.Read("text-document.jpg").Text

' For table documents, structured data is immediately available
Dim result = ocr.Read("data-table.jpg")
For Each page In result.Pages
    For Each paragraph In page.Paragraphs
        Console.WriteLine($"Block at ({paragraph.X}, {paragraph.Y}): {paragraph.Text}")
    Next
Next

O IronOCR elimina completamente a necessidade de selecionar o modo de operação. O motor analisa o layout e apresenta o resultado através da hierarquia Pages, Paragraphs, Lines, e Words. O guia de resultados de leitura aborda como navegar pelo modelo de resultados estruturados completo para análise de layout de documentos. Para padrões de extração específicos de tabelas, consulte o guia de leitura de tabelas .

Reconhecimento de lotes com filtragem baseada em confiança

Os fluxos de trabalho em lote do Aspose.OCR acumulam objetos RecognitionResult em uma lista. A filtragem por confiança requer iterar essa lista e calcular a média por região antes de aceitar um resultado. A lista deve ser gerenciada explicitamente e passada para SaveMultipageDocument se você quiser gerar várias páginas como um único arquivo.

Abordagem Aspose.OCR:

// Batch recognition with confidence filtering before output
var api = new AsposeOcr();
var settings = new RecognitionSettings
{
    Language = Language.Eng,
    DetectAreasMode = DetectAreasMode.DOCUMENT
};

string[] documentPaths = Directory.GetFiles("invoice-archive", "*.jpg");
var acceptedResults = new List<RecognitionResult>();
var rejectedPaths = new List<string>();

foreach (var path in documentPaths)
{
    var result = api.RecognizeImage(path, settings);

    // Confidence is an array of per-region values — must average manually
    float avgConfidence = result.RecognitionAreasConfidence != null
        ? result.RecognitionAreasConfidence.Average()
        : 0f;

    if (avgConfidence >= 0.70f)
    {
        acceptedResults.Add(result);
    }
    else
    {
        rejectedPaths.Add(path);
        Console.WriteLine($"Rejected: {path} ({avgConfidence:P0} confidence)");
    }
}

// Save accepted pages as a single searchable PDF
if (acceptedResults.Any())
{
    api.SaveMultipageDocument("high-confidence-invoices.pdf",
        SaveFormat.Pdf, acceptedResults);
}

Console.WriteLine($"Accepted: {acceptedResults.Count}, Rejected: {rejectedPaths.Count}");

// Batch recognition with confidence filtering before output
var api = new AsposeOcr();
var settings = new RecognitionSettings
{
    Language = Language.Eng,
    DetectAreasMode = DetectAreasMode.DOCUMENT
};

string[] documentPaths = Directory.GetFiles("invoice-archive", "*.jpg");
var acceptedResults = new List<RecognitionResult>();
var rejectedPaths = new List<string>();

foreach (var path in documentPaths)
{
    var result = api.RecognizeImage(path, settings);

    // Confidence is an array of per-region values — must average manually
    float avgConfidence = result.RecognitionAreasConfidence != null
        ? result.RecognitionAreasConfidence.Average()
        : 0f;

    if (avgConfidence >= 0.70f)
    {
        acceptedResults.Add(result);
    }
    else
    {
        rejectedPaths.Add(path);
        Console.WriteLine($"Rejected: {path} ({avgConfidence:P0} confidence)");
    }
}

// Save accepted pages as a single searchable PDF
if (acceptedResults.Any())
{
    api.SaveMultipageDocument("high-confidence-invoices.pdf",
        SaveFormat.Pdf, acceptedResults);
}

Console.WriteLine($"Accepted: {acceptedResults.Count}, Rejected: {rejectedPaths.Count}");

Imports System
Imports System.IO
Imports System.Linq
Imports Aspose.OCR

' Batch recognition with confidence filtering before output
Dim api As New AsposeOcr()
Dim settings As New RecognitionSettings With {
    .Language = Language.Eng,
    .DetectAreasMode = DetectAreasMode.DOCUMENT
}

Dim documentPaths As String() = Directory.GetFiles("invoice-archive", "*.jpg")
Dim acceptedResults As New List(Of RecognitionResult)()
Dim rejectedPaths As New List(Of String)()

For Each path In documentPaths
    Dim result = api.RecognizeImage(path, settings)

    ' Confidence is an array of per-region values — must average manually
    Dim avgConfidence As Single = If(result.RecognitionAreasConfidence IsNot Nothing,
                                     result.RecognitionAreasConfidence.Average(),
                                     0.0F)

    If avgConfidence >= 0.70F Then
        acceptedResults.Add(result)
    Else
        rejectedPaths.Add(path)
        Console.WriteLine($"Rejected: {path} ({avgConfidence:P0} confidence)")
    End If
Next

' Save accepted pages as a single searchable PDF
If acceptedResults.Any() Then
    api.SaveMultipageDocument("high-confidence-invoices.pdf",
                              SaveFormat.Pdf, acceptedResults)
End If

Console.WriteLine($"Accepted: {acceptedResults.Count}, Rejected: {rejectedPaths.Count}")

Abordagem IronOCR:

// Batch recognition with confidence filtering using unified result model
var ocr = new IronTesseract();
string[] documentPaths = Directory.GetFiles("invoice-archive", "*.jpg");

var acceptedResults = new List<OcrResult>();
var rejectedPaths = new List<string>();

foreach (var path in documentPaths)
{
    var result = ocr.Read(path);

    // Single confidence value — no averaging required
    if (result.Confidence >= 70.0)
    {
        acceptedResults.Add(result);
    }
    else
    {
        rejectedPaths.Add(path);
        Console.WriteLine($"Rejected: {path} ({result.Confidence:F1}% confidence)");
    }
}

// Save accepted pages — each result becomes a page in the output PDF
if (acceptedResults.Any())
{
    using var outputInput = new OcrInput();
    foreach (var path in documentPaths
        .Where(p => !rejectedPaths.Contains(p)))
    {
        outputInput.LoadImage(path);
    }
    var combined = ocr.Read(outputInput);
    combined.SaveAsSearchablePdf("high-confidence-invoices.pdf");
}

Console.WriteLine($"Accepted: {acceptedResults.Count}, Rejected: {rejectedPaths.Count}");

// Batch recognition with confidence filtering using unified result model
var ocr = new IronTesseract();
string[] documentPaths = Directory.GetFiles("invoice-archive", "*.jpg");

var acceptedResults = new List<OcrResult>();
var rejectedPaths = new List<string>();

foreach (var path in documentPaths)
{
    var result = ocr.Read(path);

    // Single confidence value — no averaging required
    if (result.Confidence >= 70.0)
    {
        acceptedResults.Add(result);
    }
    else
    {
        rejectedPaths.Add(path);
        Console.WriteLine($"Rejected: {path} ({result.Confidence:F1}% confidence)");
    }
}

// Save accepted pages — each result becomes a page in the output PDF
if (acceptedResults.Any())
{
    using var outputInput = new OcrInput();
    foreach (var path in documentPaths
        .Where(p => !rejectedPaths.Contains(p)))
    {
        outputInput.LoadImage(path);
    }
    var combined = ocr.Read(outputInput);
    combined.SaveAsSearchablePdf("high-confidence-invoices.pdf");
}

Console.WriteLine($"Accepted: {acceptedResults.Count}, Rejected: {rejectedPaths.Count}");

Imports IronTesseract
Imports System.IO
Imports System.Linq

' Batch recognition with confidence filtering using unified result model
Dim ocr As New IronTesseract()
Dim documentPaths As String() = Directory.GetFiles("invoice-archive", "*.jpg")

Dim acceptedResults As New List(Of OcrResult)()
Dim rejectedPaths As New List(Of String)()

For Each path In documentPaths
    Dim result = ocr.Read(path)

    ' Single confidence value — no averaging required
    If result.Confidence >= 70.0 Then
        acceptedResults.Add(result)
    Else
        rejectedPaths.Add(path)
        Console.WriteLine($"Rejected: {path} ({result.Confidence:F1}% confidence)")
    End If
Next

' Save accepted pages — each result becomes a page in the output PDF
If acceptedResults.Any() Then
    Using outputInput As New OcrInput()
        For Each path In documentPaths.Where(Function(p) Not rejectedPaths.Contains(p))
            outputInput.LoadImage(path)
        Next
        Dim combined = ocr.Read(outputInput)
        combined.SaveAsSearchablePdf("high-confidence-invoices.pdf")
    End Using
End If

Console.WriteLine($"Accepted: {acceptedResults.Count}, Rejected: {rejectedPaths.Count}")

result.Confidence é um único double variando de 0 a 100. A média de matriz do RecognitionAreasConfidence da Aspose retorna um float em um intervalo que varia conforme a versão — o limiar de comparação precisa ser ajustado durante a migração. Os índices de confiança orientam os documentos com valores de confiança por palavra, por linha e por página para fluxos de trabalho de validação de documentos. Para padrões de lote de alto volume, consulte o exemplo de multithreading .

Processamento de saída estruturada

Aspose.OCR gera dados estruturados através de SaveMultipageDocument com valores enum SaveFormat específicos do formato. A saída JSON grava um arquivo legível por máquina; a saída XML grava um arquivo de documento anotado. Acessar os dados estruturados brutos — posições das palavras, limites das linhas — requer iterar RecognitionAreasRectangles, que retorna geometria no nível da região, e não no nível da palavra.

Abordagem Aspose.OCR:

// Structured output: JSON and XML via SaveMultipageDocument
var api = new AsposeOcr();
var settings = new RecognitionSettings
{
    Language = Language.Eng,
    DetectAreasMode = DetectAreasMode.COMBINE
};

var results = new List<RecognitionResult>();
foreach (var path in new[] { "page1.jpg", "page2.jpg", "page3.jpg" })
{
    results.Add(api.RecognizeImage(path, settings));
}

// Export as JSON
api.SaveMultipageDocument("output.json", SaveFormat.Json, results);

// Export as XML
api.SaveMultipageDocument("output.xml", SaveFormat.Xml, results);

// Accessing area-level geometry (not word-level)
foreach (var result in results)
{
    var areas = result.RecognitionAreasRectangles;
    if (areas != null)
    {
        foreach (var area in areas)
        {
            Console.WriteLine($"Area at ({area.X},{area.Y}): {area.Width}x{area.Height}");
        }
    }
    // No direct word-level collection with individual confidence values
}

// Structured output: JSON and XML via SaveMultipageDocument
var api = new AsposeOcr();
var settings = new RecognitionSettings
{
    Language = Language.Eng,
    DetectAreasMode = DetectAreasMode.COMBINE
};

var results = new List<RecognitionResult>();
foreach (var path in new[] { "page1.jpg", "page2.jpg", "page3.jpg" })
{
    results.Add(api.RecognizeImage(path, settings));
}

// Export as JSON
api.SaveMultipageDocument("output.json", SaveFormat.Json, results);

// Export as XML
api.SaveMultipageDocument("output.xml", SaveFormat.Xml, results);

// Accessing area-level geometry (not word-level)
foreach (var result in results)
{
    var areas = result.RecognitionAreasRectangles;
    if (areas != null)
    {
        foreach (var area in areas)
        {
            Console.WriteLine($"Area at ({area.X},{area.Y}): {area.Width}x{area.Height}");
        }
    }
    // No direct word-level collection with individual confidence values
}

Imports System
Imports System.Collections.Generic
Imports AsposeOcr

' Structured output: JSON and XML via SaveMultipageDocument
Dim api As New AsposeOcr()
Dim settings As New RecognitionSettings With {
    .Language = Language.Eng,
    .DetectAreasMode = DetectAreasMode.COMBINE
}

Dim results As New List(Of RecognitionResult)()
For Each path In New String() {"page1.jpg", "page2.jpg", "page3.jpg"}
    results.Add(api.RecognizeImage(path, settings))
Next

' Export as JSON
api.SaveMultipageDocument("output.json", SaveFormat.Json, results)

' Export as XML
api.SaveMultipageDocument("output.xml", SaveFormat.Xml, results)

' Accessing area-level geometry (not word-level)
For Each result In results
    Dim areas = result.RecognitionAreasRectangles
    If areas IsNot Nothing Then
        For Each area In areas
            Console.WriteLine($"Area at ({area.X},{area.Y}): {area.Width}x{area.Height}")
        Next
    End If
    ' No direct word-level collection with individual confidence values
Next

Abordagem IronOCR:

// Structured output: navigate a rich result object model
var ocr = new IronTesseract();

using var input = new OcrInput();
input.LoadImage("page1.jpg");
input.LoadImage("page2.jpg");
input.LoadImage("page3.jpg");

var result = ocr.Read(input);

// Export as searchable PDF (preserves layout)
result.SaveAsSearchablePdf("output.pdf");

// Export as hOCR (XHTML with bounding box coordinates — feeds downstream tools)
result.SaveAsHocrFile("output.hocr");

// Word-level structured access — direct collection, no indirection
foreach (var page in result.Pages)
{
    Console.WriteLine($"Page {page.PageNumber}: {page.Words.Length} words, " +
                      $"{page.Confidence:F1}% confidence");

    foreach (var word in page.Words)
    {
        Console.WriteLine($"  '{word.Text}' at ({word.X},{word.Y}) " +
                          $"size {word.Width}x{word.Height} — {word.Confidence:F1}%");
    }
}

// Paragraph-level layout for document structure analysis
foreach (var paragraph in result.Pages[0].Paragraphs)
{
    Console.WriteLine($"Paragraph at ({paragraph.X},{paragraph.Y}): {paragraph.Text}");
}

// Structured output: navigate a rich result object model
var ocr = new IronTesseract();

using var input = new OcrInput();
input.LoadImage("page1.jpg");
input.LoadImage("page2.jpg");
input.LoadImage("page3.jpg");

var result = ocr.Read(input);

// Export as searchable PDF (preserves layout)
result.SaveAsSearchablePdf("output.pdf");

// Export as hOCR (XHTML with bounding box coordinates — feeds downstream tools)
result.SaveAsHocrFile("output.hocr");

// Word-level structured access — direct collection, no indirection
foreach (var page in result.Pages)
{
    Console.WriteLine($"Page {page.PageNumber}: {page.Words.Length} words, " +
                      $"{page.Confidence:F1}% confidence");

    foreach (var word in page.Words)
    {
        Console.WriteLine($"  '{word.Text}' at ({word.X},{word.Y}) " +
                          $"size {word.Width}x{word.Height} — {word.Confidence:F1}%");
    }
}

// Paragraph-level layout for document structure analysis
foreach (var paragraph in result.Pages[0].Paragraphs)
{
    Console.WriteLine($"Paragraph at ({paragraph.X},{paragraph.Y}): {paragraph.Text}");
}

Imports IronTesseract

' Structured output: navigate a rich result object model
Dim ocr As New IronTesseract()

Using input As New OcrInput()
    input.LoadImage("page1.jpg")
    input.LoadImage("page2.jpg")
    input.LoadImage("page3.jpg")

    Dim result = ocr.Read(input)

    ' Export as searchable PDF (preserves layout)
    result.SaveAsSearchablePdf("output.pdf")

    ' Export as hOCR (XHTML with bounding box coordinates — feeds downstream tools)
    result.SaveAsHocrFile("output.hocr")

    ' Word-level structured access — direct collection, no indirection
    For Each page In result.Pages
        Console.WriteLine($"Page {page.PageNumber}: {page.Words.Length} words, " &
                          $"{page.Confidence:F1}% confidence")

        For Each word In page.Words
            Console.WriteLine($"  '{word.Text}' at ({word.X},{word.Y}) " &
                              $"size {word.Width}x{word.Height} — {word.Confidence:F1}%")
        Next
    Next

    ' Paragraph-level layout for document structure analysis
    For Each paragraph In result.Pages(0).Paragraphs
        Console.WriteLine($"Paragraph at ({paragraph.X},{paragraph.Y}): {paragraph.Text}")
    Next
End Using

IronOCR expõe dados ao nível de palavra como uma coleção Words direta em cada página, com valores Confidence individuais por palavra. O RecognitionAreasRectangles do Aspose.OCR fornece geometria de região sem um detalhamento de confiança ao nível de palavra. A exportação hOCR gera XHTML compatível com ferramentas que utilizam saída anotada com caixas delimitadoras — consulte o guia de exportação hOCR para obter detalhes sobre o formato. Para o modelo completo de resultado estruturado, a referência API OcrResult documenta todas as propriedades em OcrResult.Page, OcrResult.Paragraph, OcrResult.Line, e OcrResult.Word.

Problema 1: O modo DetectAreas não possui equivalente direto.

Aspose.OCR: O código define settings.DetectAreasMode = DetectAreasMode.TABLE ou DetectAreasMode.COMBINE esperando comportamento específico de layout. A remoção da enumeração deixa em aberto a questão de como o IronOCR lida com o mesmo layout.

Solução: Remova o enum completamente. O IronOCR realiza análises de layout automaticamente. Se você precisa inspecionar a estrutura de layout detectada, navegue result.Pages[n].Paragraphs — cada parágrafo carrega um X, Y, Largura, Altura, caixa delimitadora e o texto que contém. Para extração explícita de tabelas, consulte o guia de leitura de tabelas :

// No mode to set — read directly and inspect the structure
var result = new IronTesseract().Read("data-table.jpg");
foreach (var paragraph in result.Pages[0].Paragraphs)
{
    Console.WriteLine($"Block ({paragraph.X},{paragraph.Y}): {paragraph.Text}");
}

// No mode to set — read directly and inspect the structure
var result = new IronTesseract().Read("data-table.jpg");
foreach (var paragraph in result.Pages[0].Paragraphs)
{
    Console.WriteLine($"Block ({paragraph.X},{paragraph.Y}): {paragraph.Text}");
}

Imports IronTesseract

Dim result = New IronTesseract().Read("data-table.jpg")
For Each paragraph In result.Pages(0).Paragraphs
    Console.WriteLine($"Block ({paragraph.X},{paragraph.Y}): {paragraph.Text}")
Next

Problema 2: Incompatibilidade do Limiar de Confiança das Áreas de Reconhecimento

Aspose.OCR: O código existente compara result.RecognitionAreasConfidence.Average() contra um limiar como 0.75f. O result.Confidence do IronOCR está em uma escala diferente.

Solução: result.Confidence é uma porcentagem de 0 a 100. Multiplique seu limiar Aspose por 100 para converter: 0.75f se torna 75.0. Em seguida, atualize toda a lógica de comparação:

// Aspose.OCR threshold pattern
// if (result.RecognitionAreasConfidence.Average() >= 0.75f)

//IronOCR equivalent — multiply old threshold by 100
var result = new IronTesseract().Read("document.jpg");
if (result.Confidence >= 75.0)
{
    Console.WriteLine($"High confidence result: {result.Text}");
}

// Aspose.OCR threshold pattern
// if (result.RecognitionAreasConfidence.Average() >= 0.75f)

//IronOCR equivalent — multiply old threshold by 100
var result = new IronTesseract().Read("document.jpg");
if (result.Confidence >= 75.0)
{
    Console.WriteLine($"High confidence result: {result.Text}");
}

Imports IronOcr

Dim result = New IronTesseract().Read("document.jpg")
If result.Confidence >= 75.0 Then
    Console.WriteLine($"High confidence result: {result.Text}")
End If

Problema 3: A saída JSON/XML do SaveMultipageDocument não possui um método direto.

Aspose.OCR: api.SaveMultipageDocument("out.json", SaveFormat.Json, results) escreve um arquivo JSON com metadados de reconhecimento. As equipes que consomem essa saída posteriormente precisam encontrar o equivalente.

Solução:IronOCR não tem um método equivalente a SaveFormat.Json. A substituição é navegar result.Pages e serializar com System.Text.Json. Isso lhe dá controle total sobre o esquema:

using var input = new OcrInput();
input.LoadImage("document.jpg");
var result = new IronTesseract().Read(input);

// Build your own structured JSON from the result model
var pageData = result.Pages.Select(p => new
{
    PageNumber = p.PageNumber,
    Confidence = p.Confidence,
    Text = p.Text,
    Words = p.Words.Select(w => new
    {
        Text = w.Text,
        X = w.X,
        Y = w.Y,
        Width = w.Width,
        Height = w.Height,
        Confidence = w.Confidence
    }).ToArray()
}).ToArray();

File.WriteAllText("output.json",
    System.Text.Json.JsonSerializer.Serialize(pageData,
        new System.Text.Json.JsonSerializerOptions { WriteIndented = true }));

using var input = new OcrInput();
input.LoadImage("document.jpg");
var result = new IronTesseract().Read(input);

// Build your own structured JSON from the result model
var pageData = result.Pages.Select(p => new
{
    PageNumber = p.PageNumber,
    Confidence = p.Confidence,
    Text = p.Text,
    Words = p.Words.Select(w => new
    {
        Text = w.Text,
        X = w.X,
        Y = w.Y,
        Width = w.Width,
        Height = w.Height,
        Confidence = w.Confidence
    }).ToArray()
}).ToArray();

File.WriteAllText("output.json",
    System.Text.Json.JsonSerializer.Serialize(pageData,
        new System.Text.Json.JsonSerializerOptions { WriteIndented = true }));

Imports IronOcr
Imports System.IO
Imports System.Text.Json

Using input As New OcrInput()
    input.LoadImage("document.jpg")
    Dim result = New IronTesseract().Read(input)

    ' Build your own structured JSON from the result model
    Dim pageData = result.Pages.Select(Function(p) New With {
        .PageNumber = p.PageNumber,
        .Confidence = p.Confidence,
        .Text = p.Text,
        .Words = p.Words.Select(Function(w) New With {
            .Text = w.Text,
            .X = w.X,
            .Y = w.Y,
            .Width = w.Width,
            .Height = w.Height,
            .Confidence = w.Confidence
        }).ToArray()
    }).ToArray()

    File.WriteAllText("output.json",
        JsonSerializer.Serialize(pageData,
            New JsonSerializerOptions With {.WriteIndented = True}))
End Using

Para saída XHTML com coordenadas incorporadas que ferramentas downstream podem analisar, result.SaveAsHocrFile("output.hocr") é o equivalente semântico mais próximo.

Problema 4: DocumentRecognitionSettings.StartPage usa índice baseado em 0

Aspose.OCR: DocumentRecognitionSettings.StartPage = 2 significa a terceira página (baseado em zero). Este é o erro de deslocamento de uma unidade mais comum nas migrações de Aspose para IronOCR.

Solução: O IronOCR utiliza indexação de páginas baseada em 1 em todo o processo. Adicione 1 a cada valor StartPage e recalcule a página final de acordo. Crie um teste específico para um PDF de várias páginas conhecido, a fim de detectar esse problema antes da produção:

// Aspose.OCR: StartPage = 2 means the 3rd page (0-based)
// var settings = new DocumentRecognitionSettings { StartPage = 2, PagesNumber = 3 };

// IronOCR: page 3 is index 3 (1-based), range of 3 ends at page 5
using var input = new OcrInput();
input.LoadPdfPages("document.pdf", 3, 5);
var result = new IronTesseract().Read(input);

// Aspose.OCR: StartPage = 2 means the 3rd page (0-based)
// var settings = new DocumentRecognitionSettings { StartPage = 2, PagesNumber = 3 };

// IronOCR: page 3 is index 3 (1-based), range of 3 ends at page 5
using var input = new OcrInput();
input.LoadPdfPages("document.pdf", 3, 5);
var result = new IronTesseract().Read(input);

Imports IronOcr

' Aspose.OCR: StartPage = 2 means the 3rd page (0-based)
' Dim settings As New DocumentRecognitionSettings With {.StartPage = 2, .PagesNumber = 3}

' IronOCR: page 3 is index 3 (1-based), range of 3 ends at page 5
Using input As New OcrInput()
    input.LoadPdfPages("document.pdf", 3, 5)
    Dim result = New IronTesseract().Read(input)
End Using

Problema 5: RecognizeSingleLine não possui indicador direto

Aspose.OCR: settings.RecognizeSingleLine = true diz ao motor para tratar toda a imagem como uma única linha de texto. Isso é usado para reconhecimento de etiquetas, extração de campos e outras entradas de formato fixo.

Solução: Use um CropRectangle para isolar precisamente a linha de texto, o que impede o motor de executar detecção de layout completa em uma imagem de linha única. Para zonas legíveis por máquina ou formatos de etiquetas, o guia de leitura de documentos específicos aborda a abordagem apropriada:

// Aspose.OCR: single-line flag
// var settings = new RecognitionSettings { RecognizeSingleLine = true };

// IronOCR: crop to the line region — layout detection skips automatically
var lineRegion = new CropRectangle(10, 45, 600, 30); // x, y, width, height
using var input = new OcrInput();
input.LoadImage("label.jpg", lineRegion);
var result = new IronTesseract().Read(input);
Console.WriteLine(result.Text.Trim());

// Aspose.OCR: single-line flag
// var settings = new RecognitionSettings { RecognizeSingleLine = true };

// IronOCR: crop to the line region — layout detection skips automatically
var lineRegion = new CropRectangle(10, 45, 600, 30); // x, y, width, height
using var input = new OcrInput();
input.LoadImage("label.jpg", lineRegion);
var result = new IronTesseract().Read(input);
Console.WriteLine(result.Text.Trim());

Imports IronOcr

Dim lineRegion As New CropRectangle(10, 45, 600, 30) ' x, y, width, height
Using input As New OcrInput()
    input.LoadImage("label.jpg", lineRegion)
    Dim result = New IronTesseract().Read(input)
    Console.WriteLine(result.Text.Trim())
End Using

Questão 6: Instâncias Aspose.OCR por thread não são necessárias

Aspose.OCR: A documentação recomenda criar uma nova instância AsposeOcr() por thread para evitar problemas de segurança de thread no processamento paralelo. O código existente cria instâncias dentro de lambdas Parallel.ForEach.

Solução: IronTesseract é seguro para threads. Uma única instância lida com cargas de trabalho paralelas. Remover a instanciação por thread e compartilhar uma única instância:

// Aspose.OCR: per-thread instance due to thread-safety concerns
// Parallel.ForEach(paths, path => { var api = new AsposeOcr(); ... });

// IronOCR: single shared instance, fully thread-safe
var ocr = new IronTesseract();

Parallel.ForEach(documentPaths, path =>
{
    var result = ocr.Read(path);
    Console.WriteLine($"{Path.GetFileName(path)}: {result.Confidence:F1}%");
});

// Aspose.OCR: per-thread instance due to thread-safety concerns
// Parallel.ForEach(paths, path => { var api = new AsposeOcr(); ... });

// IronOCR: single shared instance, fully thread-safe
var ocr = new IronTesseract();

Parallel.ForEach(documentPaths, path =>
{
    var result = ocr.Read(path);
    Console.WriteLine($"{Path.GetFileName(path)}: {result.Confidence:F1}%");
});

Imports System.IO
Imports IronOcr
Imports System.Threading.Tasks

Dim ocr As New IronTesseract()

Parallel.ForEach(documentPaths, Sub(path)
    Dim result = ocr.Read(path)
    Console.WriteLine($"{Path.GetFileName(path)}: {result.Confidence:F1}%")
End Sub)

Tarefas pré-migração

Audite todas as referências a Aspose.OCR na base de código:

grep -rn "using Aspose.OCR" --include="*.cs" .
grep -rn "AsposeOcr\|RecognitionSettings\|DocumentRecognitionSettings" --include="*.cs" .
grep -rn "DetectAreasMode\|SaveFormat\|RecognitionResult" --include="*.cs" .
grep -rn "RecognitionAreasConfidence\|RecognitionText\|RecognizePdf" --include="*.cs" .
grep -rn "PreprocessingFilter\|SaveMultipageDocument" --include="*.cs" .
grep -rn "Aspose.OCR.License\|SetLicense" --include="*.cs" .

grep -rn "using Aspose.OCR" --include="*.cs" .
grep -rn "AsposeOcr\|RecognitionSettings\|DocumentRecognitionSettings" --include="*.cs" .
grep -rn "DetectAreasMode\|SaveFormat\|RecognitionResult" --include="*.cs" .
grep -rn "RecognitionAreasConfidence\|RecognitionText\|RecognizePdf" --include="*.cs" .
grep -rn "PreprocessingFilter\|SaveMultipageDocument" --include="*.cs" .
grep -rn "Aspose.OCR.License\|SetLicense" --include="*.cs" .

Documente cada ocorrência por categoria: chamadas de reconhecimento, objetos de configuração, pipelines de pré-processamento, chamadas de saída e inicialização de licença. Anote todos os valores DetectAreasMode em uso — estes determinam qual caminho de migração de layout se aplica. Registre todos os valores enum SaveFormat — cada formato não-PDF precisa da abordagem de serialização personalizada do Problema 3 acima.

Migração de código

1. Remova o pacote NuGet Aspose.OCR de todos os projetos na solução
2. Instale o pacote NuGet IronOcr em todos os projetos
3. Substitua using Aspose.OCR; e using Aspose.OCR.Models; por using IronOcr;
4. Substitua new Aspose.OCR.License().SetLicense("file.lic") por IronOcr.License.LicenseKey = "key" no início do aplicativo
5. Substitua new AsposeOcr() por new IronTesseract()
6. Remova todos os blocos de construção RecognitionSettings e DocumentRecognitionSettings
7. Remova todas as referências enum DetectAreasMode — não é necessário equivalente
8. Substitua api.RecognizeImage(path, settings) por ocr.Read(path)
9. Substitua api.RecognizePdf(path, settings) por ocr.Read(path) ou ocr.Read(input) usando input.LoadPdf()
10. Substitua result.RecognitionText por result.Text
11. Substitua result.RecognitionAreasConfidence.Average() por result.Confidence e multiplique o limiar antigo por 100
12. Substitua api.SaveMultipageDocument(path, SaveFormat.Pdf, list) por result.SaveAsSearchablePdf(path)
13. Substitua api.SaveMultipageDocument(path, SaveFormat.Json, list) por serialização direta de result.Pages
14. Converta todas as cadeias PreprocessingFilter para chamadas de método OcrInput (veja a tabela de mapeamento de API)
15. Atualize DocumentRecognitionSettings.StartPage de baseado em zero para baseado em 1 (adicione 1 a cada valor)
16. Remova a instanciação per-thread de AsposeOcr — compartilhe uma única instância IronTesseract

Testes pós-migração

• Execute o OCR em uma amostra representativa de cada tipo de documento em uso na produção e compare a contagem de caracteres com a saída padrão do Aspose.OCR.
• Verificar valores de confiança:IronOCR retorna de 0 a 100; Confirme que todas as comparações de limiar utilizam a nova escala.
• Teste a seleção de intervalo de páginas em um PDF com mais de 10 páginas usando numeração de páginas baseada em 1 e verifique se as páginas corretas são retornadas.
• Teste a ingestão de PDFs protegidos por senha sem o Aspose.PDF instalado — confirme que não há exceções de dependência.
• Confirme que result.Text corresponde à saída esperada para cada DetectAreasMode que estava em uso (COMBINAR, TABELA, DOCUMENTO)
• Teste o caminho de saída JSON: serialize result.Pages e valide o esquema contra quaisquer consumidores downstream
• Execute o processador em lote paralelo e verifique se não há exceções de threading (instância IronTesseract compartilhada)
• Confirme se o PDF pesquisável abre em um visualizador de PDF e se o texto pode ser selecionado nos locais corretos.
• Validar se a chave de licença é inicializada sem erros em cada ambiente de implantação (inicialização do ASP.NET , Função do Azure, contêiner Docker)
• Verifique se as entradas TIFF pré-processadas ainda produzem a saída esperada através de input.LoadImageFrames()