Migración de Charlesw Tesseract a IronOCR

El problema fundamental

El envoltorio charlesw requiere una configuración binaria nativa específica de la plataforma antes de que se pueda ejecutar el OCR:

// charlesw Tesseract: OS detection required just to find native DLLs
// DllNotFoundException on any platform where binaries do not resolve
if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
{
    Environment.SetEnvironmentVariable("LD_LIBRARY_PATH", "/app/lib");
}
var engine = new TesseractEngine(@"./tessdata", "eng", EngineMode.Default);
using var img = Pix.LoadFromFile(imagePath); // Requires leptonica native DLL
using var page = engine.Process(img);
return page.GetText();

// charlesw Tesseract: OS detection required just to find native DLLs
// DllNotFoundException on any platform where binaries do not resolve
if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
{
    Environment.SetEnvironmentVariable("LD_LIBRARY_PATH", "/app/lib");
}
var engine = new TesseractEngine(@"./tessdata", "eng", EngineMode.Default);
using var img = Pix.LoadFromFile(imagePath); // Requires leptonica native DLL
using var page = engine.Process(img);
return page.GetText();

Imports System
Imports System.Runtime.InteropServices
Imports Tesseract

' charlesw Tesseract: OS detection required just to find native DLLs
' DllNotFoundException on any platform where binaries do not resolve
If RuntimeInformation.IsOSPlatform(OSPlatform.Linux) Then
    Environment.SetEnvironmentVariable("LD_LIBRARY_PATH", "/app/lib")
End If

Dim engine As New TesseractEngine("./tessdata", "eng", EngineMode.Default)
Using img As Pix = Pix.LoadFromFile(imagePath) ' Requires leptonica native DLL
    Using page As Page = engine.Process(img)
        Return page.GetText()
    End Using
End Using

IronOCR no tiene configuración binaria nativa:

// IronOCR: no path management, no OS detection, no leptonica dependency
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";
var text = new IronTesseract().Read(imagePath).Text;

// IronOCR: no path management, no OS detection, no leptonica dependency
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";
var text = new IronTesseract().Read(imagePath).Text;

' IronOCR: no path management, no OS detection, no leptonica dependency
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY"
Dim text As String = New IronTesseract().Read(imagePath).Text

Paso 1: Sustituir el paquete NuGet

Elimine el paquete charlesw de Tesseract:

dotnet remove package Tesseract

dotnet remove package Tesseract

Instala IronOCR desde NuGet :

dotnet add package IronOcr

Paso 2: Actualizar los espacios de nombres

// Before (charlesw Tesseract)
using Tesseract;

// After (IronOCR)
using IronOcr;

// Before (charlesw Tesseract)
using Tesseract;

// After (IronOCR)
using IronOcr;

Imports IronOcr

Paso 3: Inicializar licencia

Agregue esta llamada una sola vez al iniciar la aplicación, antes de que se ejecute cualquier operación de OCR:

IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";

IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";

IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY"

En la página de licencias de IronOCR encontrará una licencia de prueba gratuita. La versión de prueba elimina la marca de agua de la salida y habilita el acceso completo a la API.

Eliminación de la configuración de ruta binaria nativa

El patrón de inicialización más común en los proyectos charlesw/tesseract es una clase de fábrica o auxiliar que construye la ruta tessdata y configura la carga de la biblioteca nativa por entorno. Este código existe únicamente debido al modelo de despliegue del envoltorio.

Enfoque del teseracto de Charlesw:

// A realistic factory found in production charlesw/Tesseract projects
public static class OcrEngineFactory
{
    private static string GetTessDataPath()
    {
        // Different path per environment — all wrong until explicitly configured
        if (Environment.GetEnvironmentVariable("DOTNET_RUNNING_IN_CONTAINER") == "true")
            return "/app/tessdata";                                    // Docker
        if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
            return Path.Combine(AppContext.BaseDirectory, "tessdata"); // Linux bare metal
        if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
            return "/usr/local/share/tessdata";                        // macOS Homebrew install
        return @".\tessdata";                                          // Windows dev machine
    }

    public static TesseractEngine Create(string language = "eng")
    {
        // If leptonica-1.82.0.dll is not in output directory: DllNotFoundException at this line
        // If tessdata folder is missing: TesseractException at engine construction
        return new TesseractEngine(GetTessDataPath(), language, EngineMode.Default);
    }
}

// Call site
using var engine = OcrEngineFactory.Create();
using var img = Pix.LoadFromFile("invoice.jpg");
using var page = engine.Process(img);
Console.WriteLine(page.GetText());

// A realistic factory found in production charlesw/Tesseract projects
public static class OcrEngineFactory
{
    private static string GetTessDataPath()
    {
        // Different path per environment — all wrong until explicitly configured
        if (Environment.GetEnvironmentVariable("DOTNET_RUNNING_IN_CONTAINER") == "true")
            return "/app/tessdata";                                    // Docker
        if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
            return Path.Combine(AppContext.BaseDirectory, "tessdata"); // Linux bare metal
        if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
            return "/usr/local/share/tessdata";                        // macOS Homebrew install
        return @".\tessdata";                                          // Windows dev machine
    }

    public static TesseractEngine Create(string language = "eng")
    {
        // If leptonica-1.82.0.dll is not in output directory: DllNotFoundException at this line
        // If tessdata folder is missing: TesseractException at engine construction
        return new TesseractEngine(GetTessDataPath(), language, EngineMode.Default);
    }
}

// Call site
using var engine = OcrEngineFactory.Create();
using var img = Pix.LoadFromFile("invoice.jpg");
using var page = engine.Process(img);
Console.WriteLine(page.GetText());

Imports System
Imports System.IO
Imports System.Runtime.InteropServices
Imports Tesseract

Public Module OcrEngineFactory
    Private Function GetTessDataPath() As String
        ' Different path per environment — all wrong until explicitly configured
        If Environment.GetEnvironmentVariable("DOTNET_RUNNING_IN_CONTAINER") = "true" Then
            Return "/app/tessdata"                                    ' Docker
        End If
        If RuntimeInformation.IsOSPlatform(OSPlatform.Linux) Then
            Return Path.Combine(AppContext.BaseDirectory, "tessdata") ' Linux bare metal
        End If
        If RuntimeInformation.IsOSPlatform(OSPlatform.OSX) Then
            Return "/usr/local/share/tessdata"                        ' macOS Homebrew install
        End If
        Return ".\tessdata"                                           ' Windows dev machine
    End Function

    Public Function Create(Optional language As String = "eng") As TesseractEngine
        ' If leptonica-1.82.0.dll is not in output directory: DllNotFoundException at this line
        ' If tessdata folder is missing: TesseractException at engine construction
        Return New TesseractEngine(GetTessDataPath(), language, EngineMode.Default)
    End Function
End Module

' Call site
Using engine As TesseractEngine = OcrEngineFactory.Create()
    Using img As Pix = Pix.LoadFromFile("invoice.jpg")
        Using page As Page = engine.Process(img)
            Console.WriteLine(page.GetText())
        End Using
    End Using
End Using

Enfoque IronOCR:

// IronOCR: no factory, no path logic, no OS detection
// Runs identically on Windows, Linux, macOS, and ARM64
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";

var result = new IronTesseract().Read("invoice.jpg");
Console.WriteLine(result.Text);

// IronOCR: no factory, no path logic, no OS detection
// Runs identically on Windows, Linux, macOS, and ARM64
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";

var result = new IronTesseract().Read("invoice.jpg");
Console.WriteLine(result.Text);

' IronOCR: no factory, no path logic, no OS detection
' Runs identically on Windows, Linux, macOS, and ARM64
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY"

Dim result = New IronTesseract().Read("invoice.jpg")
Console.WriteLine(result.Text)

La clase OcrEngineFactory entera se elimina. La lógica de ruta condicional de plataforma, la verificación DOTNET_RUNNING_IN_CONTAINER y la dependencia de DLL de Leptonica desaparecen con ella. Todos los entornos (estación de trabajo del desarrollador, agente de CI, contenedor Docker, máquina virtual en la nube) ejecutan las mismas dos líneas. La guía de configuración de IronTesseract cubre las opciones de configuración cuando es necesario ajustar los valores predeterminados, pero para la mayoría de las implementaciones no es necesario ajustar ninguno.

Reemplazo de conversión de imágenes de Leptonica

El envoltorio charlesw utiliza el tipo Pix de Leptonica como su representación de imagen. Cualquier código que manipule imágenes antes del OCR debe convertir a través de Pix, lo que requiere que la DLL nativa de Leptonica esté cargada y operativa. Reemplazar este patrón con OcrInput elimina por completo la dependencia de Leptonica.

Enfoque del teseracto de Charlesw:

// Pix is Leptonica's image type — requires leptonica native DLL
// Converting from System.Drawing.Bitmap requires a temp file round-trip
public string ProcessInMemoryImage(Bitmap bitmap)
{
    // No direct Bitmap → Pix conversion; must write to temp file
    var tempPath = Path.Combine(Path.GetTempPath(), $"ocr_{Guid.NewGuid()}.png");
    try
    {
        bitmap.Save(tempPath, System.Drawing.Imaging.ImageFormat.Png);

        using var engine = new TesseractEngine(@"./tessdata", "eng", EngineMode.Default);
        using var pix = Pix.LoadFromFile(tempPath);   // Leptonica file I/O
        using var page = engine.Process(pix);

        return page.GetText();
    }
    finally
    {
        if (File.Exists(tempPath)) File.Delete(tempPath);
    }
}

// Pix is Leptonica's image type — requires leptonica native DLL
// Converting from System.Drawing.Bitmap requires a temp file round-trip
public string ProcessInMemoryImage(Bitmap bitmap)
{
    // No direct Bitmap → Pix conversion; must write to temp file
    var tempPath = Path.Combine(Path.GetTempPath(), $"ocr_{Guid.NewGuid()}.png");
    try
    {
        bitmap.Save(tempPath, System.Drawing.Imaging.ImageFormat.Png);

        using var engine = new TesseractEngine(@"./tessdata", "eng", EngineMode.Default);
        using var pix = Pix.LoadFromFile(tempPath);   // Leptonica file I/O
        using var page = engine.Process(pix);

        return page.GetText();
    }
    finally
    {
        if (File.Exists(tempPath)) File.Delete(tempPath);
    }
}

Imports System
Imports System.Drawing
Imports System.IO
Imports Tesseract

Public Function ProcessInMemoryImage(bitmap As Bitmap) As String
    ' No direct Bitmap → Pix conversion; must write to temp file
    Dim tempPath As String = Path.Combine(Path.GetTempPath(), $"ocr_{Guid.NewGuid()}.png")
    Try
        bitmap.Save(tempPath, System.Drawing.Imaging.ImageFormat.Png)

        Using engine As New TesseractEngine("./tessdata", "eng", EngineMode.Default)
            Using pix As Pix = Pix.LoadFromFile(tempPath) ' Leptonica file I/O
                Using page As Page = engine.Process(pix)
                    Return page.GetText()
                End Using
            End Using
        End Using
    Finally
        If File.Exists(tempPath) Then File.Delete(tempPath)
    End Try
End Function

Enfoque IronOCR:

// OcrInput accepts byte arrays and streams — no temp file, no Leptonica
public string ProcessInMemoryImage(byte[] imageBytes)
{
    using var input = new OcrInput();
    input.LoadImage(imageBytes);   // Direct byte array loading

    var result = new IronTesseract().Read(input);
    return result.Text;
}

// Or from a stream — same pattern
public string ProcessFromStream(Stream imageStream)
{
    using var input = new OcrInput();
    input.LoadImage(imageStream);

    var result = new IronTesseract().Read(input);
    return result.Text;
}

// OcrInput accepts byte arrays and streams — no temp file, no Leptonica
public string ProcessInMemoryImage(byte[] imageBytes)
{
    using var input = new OcrInput();
    input.LoadImage(imageBytes);   // Direct byte array loading

    var result = new IronTesseract().Read(input);
    return result.Text;
}

// Or from a stream — same pattern
public string ProcessFromStream(Stream imageStream)
{
    using var input = new OcrInput();
    input.LoadImage(imageStream);

    var result = new IronTesseract().Read(input);
    return result.Text;
}

Imports System.IO

' OcrInput accepts byte arrays and streams — no temp file, no Leptonica
Public Function ProcessInMemoryImage(imageBytes As Byte()) As String
    Using input As New OcrInput()
        input.LoadImage(imageBytes)   ' Direct byte array loading

        Dim result = New IronTesseract().Read(input)
        Return result.Text
    End Using
End Function

' Or from a stream — same pattern
Public Function ProcessFromStream(imageStream As Stream) As String
    Using input As New OcrInput()
        input.LoadImage(imageStream)

        Dim result = New IronTesseract().Read(input)
        Return result.Text
    End Using
End Function

El ciclo de ida y vuelta del archivo temporal desaparece. No se escribe ningún archivo en disco, no se invoca la DLL de Leptonica para la conversión, y no hay un bloque finally para limpiar. La guía de entrada de imágenes y la guía de entrada de flujo documentan todas las fuentes de entrada compatibles, incluida la carga desde URLs y archivos mapeados en memoria.

Filtrado por umbral de confianza

El envoltorio charlesw expone la confianza en dos niveles: page.GetMeanConfidence() para toda la página, y iter.GetConfidence(PageIteratorLevel.Word) para palabras individuales. Para filtrar las palabras con baja confianza en la salida, es necesario gestionar manualmente un bucle iterador.IronOCR expone el nivel de confianza directamente en los objetos de resultado, convirtiendo la lógica de umbral en una expresión LINQ.

Enfoque del teseracto de Charlesw:

// Word-level confidence filtering requires iterator boilerplate
public List<string> ExtractHighConfidenceWords(string imagePath, float minConfidence = 0.8f)
{
    var highConfidenceWords = new List<string>();

    using var engine = new TesseractEngine(@"./tessdata", "eng", EngineMode.Default);
    using var img = Pix.LoadFromFile(imagePath);
    using var page = engine.Process(img);

    // Page-level confidence only: fine-grained requires the iterator
    Console.WriteLine($"Page confidence: {page.GetMeanConfidence():P1}");

    using var iter = page.GetIterator();
    iter.Begin();
    do
    {
        if (iter.IsAtBeginningOf(PageIteratorLevel.Word))
        {
            var wordText = iter.GetText(PageIteratorLevel.Word)?.Trim();
            var wordConf  = iter.GetConfidence(PageIteratorLevel.Word) / 100f; // Returns 0-100
            if (!string.IsNullOrEmpty(wordText) && wordConf >= minConfidence)
                highConfidenceWords.Add(wordText);
        }
    } while (iter.Next(PageIteratorLevel.Para, PageIteratorLevel.Word));

    return highConfidenceWords;
}

// Word-level confidence filtering requires iterator boilerplate
public List<string> ExtractHighConfidenceWords(string imagePath, float minConfidence = 0.8f)
{
    var highConfidenceWords = new List<string>();

    using var engine = new TesseractEngine(@"./tessdata", "eng", EngineMode.Default);
    using var img = Pix.LoadFromFile(imagePath);
    using var page = engine.Process(img);

    // Page-level confidence only: fine-grained requires the iterator
    Console.WriteLine($"Page confidence: {page.GetMeanConfidence():P1}");

    using var iter = page.GetIterator();
    iter.Begin();
    do
    {
        if (iter.IsAtBeginningOf(PageIteratorLevel.Word))
        {
            var wordText = iter.GetText(PageIteratorLevel.Word)?.Trim();
            var wordConf  = iter.GetConfidence(PageIteratorLevel.Word) / 100f; // Returns 0-100
            if (!string.IsNullOrEmpty(wordText) && wordConf >= minConfidence)
                highConfidenceWords.Add(wordText);
        }
    } while (iter.Next(PageIteratorLevel.Para, PageIteratorLevel.Word));

    return highConfidenceWords;
}

Imports System
Imports Tesseract

Public Class WordExtractor
    Public Function ExtractHighConfidenceWords(imagePath As String, Optional minConfidence As Single = 0.8F) As List(Of String)
        Dim highConfidenceWords As New List(Of String)()

        Using engine As New TesseractEngine("./tessdata", "eng", EngineMode.Default)
            Using img As Pix = Pix.LoadFromFile(imagePath)
                Using page As Page = engine.Process(img)
                    ' Page-level confidence only: fine-grained requires the iterator
                    Console.WriteLine($"Page confidence: {page.GetMeanConfidence():P1}")

                    Using iter As ResultIterator = page.GetIterator()
                        iter.Begin()
                        Do
                            If iter.IsAtBeginningOf(PageIteratorLevel.Word) Then
                                Dim wordText As String = iter.GetText(PageIteratorLevel.Word)?.Trim()
                                Dim wordConf As Single = iter.GetConfidence(PageIteratorLevel.Word) / 100.0F ' Returns 0-100
                                If Not String.IsNullOrEmpty(wordText) AndAlso wordConf >= minConfidence Then
                                    highConfidenceWords.Add(wordText)
                                End If
                            End If
                        Loop While iter.Next(PageIteratorLevel.Para, PageIteratorLevel.Word)
                    End Using
                End Using
            End Using
        End Using

        Return highConfidenceWords
    End Function
End Class

Enfoque IronOCR:

// Confidence is a property on each result object — no iterator required
public List<string> ExtractHighConfidenceWords(string imagePath, double minConfidence = 80.0)
{
    var result = new IronTesseract().Read(imagePath);

    Console.WriteLine($"Page confidence: {result.Confidence}%");

    // LINQ directly on the word collection — no iterator state management
    return result.Pages
        .SelectMany(p => p.Lines)
        .SelectMany(l => l.Words)
        .Where(w => w.Confidence >= minConfidence && !string.IsNullOrWhiteSpace(w.Text))
        .Select(w => w.Text)
        .ToList();
}

// Confidence is a property on each result object — no iterator required
public List<string> ExtractHighConfidenceWords(string imagePath, double minConfidence = 80.0)
{
    var result = new IronTesseract().Read(imagePath);

    Console.WriteLine($"Page confidence: {result.Confidence}%");

    // LINQ directly on the word collection — no iterator state management
    return result.Pages
        .SelectMany(p => p.Lines)
        .SelectMany(l => l.Words)
        .Where(w => w.Confidence >= minConfidence && !string.IsNullOrWhiteSpace(w.Text))
        .Select(w => w.Text)
        .ToList();
}

Imports System
Imports System.Collections.Generic
Imports System.Linq

Public Function ExtractHighConfidenceWords(imagePath As String, Optional minConfidence As Double = 80.0) As List(Of String)
    Dim result = New IronTesseract().Read(imagePath)

    Console.WriteLine($"Page confidence: {result.Confidence}%")

    ' LINQ directly on the word collection — no iterator state management
    Return result.Pages _
        .SelectMany(Function(p) p.Lines) _
        .SelectMany(Function(l) l.Words) _
        .Where(Function(w) w.Confidence >= minConfidence AndAlso Not String.IsNullOrWhiteSpace(w.Text)) _
        .Select(Function(w) w.Text) _
        .ToList()
End Function

La máquina de estados iteradora ha desaparecido. Los valores de confianza en IronOCR se presentan de forma consistente en una escala de 0 a 100, sin necesidad de dividirlos por 100. La guía de puntuaciones de confianza abarca patrones de acceso por confianza por palabra, por línea y por página. La guía de lectura de resultados muestra cómo navegar por la jerarquía completa de resultados estructurados.

Procesamiento por lotes de archivos TIFF de varias páginas

Los archivos TIFF con múltiples fotogramas son habituales en los flujos de trabajo de escaneo de documentos. El contenedor charlesw no tiene soporte integrado para TIFF multifotograma; Cada fotograma debe extraerse manualmente antes de su procesamiento.IronOCR gestiona archivos TIFF multifotograma de forma nativa con una única llamada de carga.

Enfoque del teseracto de Charlesw:

// charlesw/Tesseract has no multi-frame TIFF support
// Each frame must be extracted via System.Drawing before OCR can run
public string ProcessMultiFrameTiff(string tiffPath)
{
    var fullText = new StringBuilder();

    using var tiffImage = Image.FromFile(tiffPath);
    var frameCount = tiffImage.GetFrameCount(FrameDimension.Page);

    using var engine = new TesseractEngine(@"./tessdata", "eng", EngineMode.Default);

    for (int i = 0; i < frameCount; i++)
    {
        tiffImage.SelectActiveFrame(FrameDimension.Page, i);

        // Must save each frame as a temp file for Pix to load
        var tempPath = Path.Combine(Path.GetTempPath(), $"tiff_frame_{i}.png");
        try
        {
            tiffImage.Save(tempPath, System.Drawing.Imaging.ImageFormat.Png);

            using var pix  = Pix.LoadFromFile(tempPath);
            using var page = engine.Process(pix);
            fullText.AppendLine(page.GetText());
        }
        finally
        {
            if (File.Exists(tempPath)) File.Delete(tempPath);
        }
    }

    return fullText.ToString();
}

// charlesw/Tesseract has no multi-frame TIFF support
// Each frame must be extracted via System.Drawing before OCR can run
public string ProcessMultiFrameTiff(string tiffPath)
{
    var fullText = new StringBuilder();

    using var tiffImage = Image.FromFile(tiffPath);
    var frameCount = tiffImage.GetFrameCount(FrameDimension.Page);

    using var engine = new TesseractEngine(@"./tessdata", "eng", EngineMode.Default);

    for (int i = 0; i < frameCount; i++)
    {
        tiffImage.SelectActiveFrame(FrameDimension.Page, i);

        // Must save each frame as a temp file for Pix to load
        var tempPath = Path.Combine(Path.GetTempPath(), $"tiff_frame_{i}.png");
        try
        {
            tiffImage.Save(tempPath, System.Drawing.Imaging.ImageFormat.Png);

            using var pix  = Pix.LoadFromFile(tempPath);
            using var page = engine.Process(pix);
            fullText.AppendLine(page.GetText());
        }
        finally
        {
            if (File.Exists(tempPath)) File.Delete(tempPath);
        }
    }

    return fullText.ToString();
}

Imports System.Drawing
Imports System.Drawing.Imaging
Imports Tesseract
Imports System.IO
Imports System.Text

Public Function ProcessMultiFrameTiff(tiffPath As String) As String
    Dim fullText As New StringBuilder()

    Using tiffImage As Image = Image.FromFile(tiffPath)
        Dim frameCount As Integer = tiffImage.GetFrameCount(FrameDimension.Page)

        Using engine As New TesseractEngine("./tessdata", "eng", EngineMode.Default)
            For i As Integer = 0 To frameCount - 1
                tiffImage.SelectActiveFrame(FrameDimension.Page, i)

                ' Must save each frame as a temp file for Pix to load
                Dim tempPath As String = Path.Combine(Path.GetTempPath(), $"tiff_frame_{i}.png")
                Try
                    tiffImage.Save(tempPath, Imaging.ImageFormat.Png)

                    Using pix As Pix = Pix.LoadFromFile(tempPath)
                        Using page As Page = engine.Process(pix)
                            fullText.AppendLine(page.GetText())
                        End Using
                    End Using
                Finally
                    If File.Exists(tempPath) Then File.Delete(tempPath)
                End Try
            Next
        End Using
    End Using

    Return fullText.ToString()
End Function

Enfoque IronOCR:

// LoadImageFrames handles multi-frame TIFFs natively — no frame extraction loop
public string ProcessMultiFrameTiff(string tiffPath)
{
    using var input = new OcrInput();
    input.LoadImageFrames(tiffPath);   // All frames loaded in one call

    var result = new IronTesseract().Read(input);

    // Pages maps directly to TIFF frames
    foreach (var page in result.Pages)
        Console.WriteLine($"Frame {page.PageNumber}: {page.Words.Count()} words");

    return result.Text;
}

// LoadImageFrames handles multi-frame TIFFs natively — no frame extraction loop
public string ProcessMultiFrameTiff(string tiffPath)
{
    using var input = new OcrInput();
    input.LoadImageFrames(tiffPath);   // All frames loaded in one call

    var result = new IronTesseract().Read(input);

    // Pages maps directly to TIFF frames
    foreach (var page in result.Pages)
        Console.WriteLine($"Frame {page.PageNumber}: {page.Words.Count()} words");

    return result.Text;
}

Imports System
Imports IronOcr

Public Class TiffProcessor
    ' LoadImageFrames handles multi-frame TIFFs natively — no frame extraction loop
    Public Function ProcessMultiFrameTiff(tiffPath As String) As String
        Using input As New OcrInput()
            input.LoadImageFrames(tiffPath) ' All frames loaded in one call

            Dim result = New IronTesseract().Read(input)

            ' Pages maps directly to TIFF frames
            For Each page In result.Pages
                Console.WriteLine($"Frame {page.PageNumber}: {page.Words.Count()} words")
            Next

            Return result.Text
        End Using
    End Function
End Class

El bucle de extracción de archivos temporales y la cadena de eliminación por fotograma han desaparecido. La detección de cantidad de marcos a través de FrameDimension.Page desaparece.IronOCR mapea los marcos TIFF a OcrResult.Pages, por lo que el acceso al texto por marco no requiere lógica de iteración adicional. La guía de entrada TIFF/GIF incluye opciones adicionales para la selección de fotogramas y el procesamiento parcial de TIFF.

Generación de PDF con capacidad de búsqueda

El programa envoltorio charlesw solo produce salida de texto. Convertir un documento escaneado en un PDF buscable — un requisito común para los sistemas de gestión documental — requiere una biblioteca secundaria de PDF (IronPDF, PDFSharp, o similar) para sobreponer el texto extraído sobre las páginas de imagen originales.IronOCR genera archivos PDF con capacidad de búsqueda en una sola llamada a un método, sin necesidad de bibliotecas secundarias.

Enfoque del teseracto de Charlesw:

// charlesw/Tesseract produces text only.
// Creating a searchable PDF requires a second library and significant code.
// The pattern below is representative — actual implementation varies by PDF library.
public void CreateSearchablePdf(string imagePath, string outputPdfPath)
{
    // Step 1: Extract text from image
    string extractedText;
    using var engine = new TesseractEngine(@"./tessdata", "eng", EngineMode.Default);
    using var img = Pix.LoadFromFile(imagePath);
    using var page = engine.Process(img);
    extractedText = page.GetText();

    // Step 2: Build a PDF with the image as background and text overlay
    // Requires a separate PDF library (not shown — 50-100+ additional lines)
    // The text layer must be positioned to match the original image layout
    // Word-level coordinates from the iterator are needed for accurate alignment
    throw new NotImplementedException(
        "Searchable PDF generation requires a separate PDF library. " +
        "Add PdfSharp, IronPDF, or similar, then implement text layer overlay.");
}

// charlesw/Tesseract produces text only.
// Creating a searchable PDF requires a second library and significant code.
// The pattern below is representative — actual implementation varies by PDF library.
public void CreateSearchablePdf(string imagePath, string outputPdfPath)
{
    // Step 1: Extract text from image
    string extractedText;
    using var engine = new TesseractEngine(@"./tessdata", "eng", EngineMode.Default);
    using var img = Pix.LoadFromFile(imagePath);
    using var page = engine.Process(img);
    extractedText = page.GetText();

    // Step 2: Build a PDF with the image as background and text overlay
    // Requires a separate PDF library (not shown — 50-100+ additional lines)
    // The text layer must be positioned to match the original image layout
    // Word-level coordinates from the iterator are needed for accurate alignment
    throw new NotImplementedException(
        "Searchable PDF generation requires a separate PDF library. " +
        "Add PdfSharp, IronPDF, or similar, then implement text layer overlay.");
}

Imports Tesseract

Public Sub CreateSearchablePdf(imagePath As String, outputPdfPath As String)
    ' Step 1: Extract text from image
    Dim extractedText As String
    Using engine As New TesseractEngine("./tessdata", "eng", EngineMode.Default)
        Using img As Pix = Pix.LoadFromFile(imagePath)
            Using page As Page = engine.Process(img)
                extractedText = page.GetText()
            End Using
        End Using
    End Using

    ' Step 2: Build a PDF with the image as background and text overlay
    ' Requires a separate PDF library (not shown — 50-100+ additional lines)
    ' The text layer must be positioned to match the original image layout
    ' Word-level coordinates from the iterator are needed for accurate alignment
    Throw New NotImplementedException("Searchable PDF generation requires a separate PDF library. " & _
                                      "Add PdfSharp, IronPDF, or similar, then implement text layer overlay.")
End Sub

Enfoque IronOCR:

// SaveAsSearchablePdf produces a PDF/A-compatible searchable document
// No secondary library, no text overlay code, no coordinate mapping
public void CreateSearchablePdf(string imagePath, string outputPdfPath)
{
    var result = new IronTesseract().Read(imagePath);
    result.SaveAsSearchablePdf(outputPdfPath);
    Console.WriteLine($"Searchable PDF saved: {outputPdfPath}");
}

// Same API works for multi-page TIFF or existing PDF input
public void MakePdfSearchable(string scannedPdfPath, string outputPdfPath)
{
    var result = new IronTesseract().Read(scannedPdfPath);
    result.SaveAsSearchablePdf(outputPdfPath);
}

// SaveAsSearchablePdf produces a PDF/A-compatible searchable document
// No secondary library, no text overlay code, no coordinate mapping
public void CreateSearchablePdf(string imagePath, string outputPdfPath)
{
    var result = new IronTesseract().Read(imagePath);
    result.SaveAsSearchablePdf(outputPdfPath);
    Console.WriteLine($"Searchable PDF saved: {outputPdfPath}");
}

// Same API works for multi-page TIFF or existing PDF input
public void MakePdfSearchable(string scannedPdfPath, string outputPdfPath)
{
    var result = new IronTesseract().Read(scannedPdfPath);
    result.SaveAsSearchablePdf(outputPdfPath);
}

' SaveAsSearchablePdf produces a PDF/A-compatible searchable document
' No secondary library, no text overlay code, no coordinate mapping
Public Sub CreateSearchablePdf(imagePath As String, outputPdfPath As String)
    Dim result = New IronTesseract().Read(imagePath)
    result.SaveAsSearchablePdf(outputPdfPath)
    Console.WriteLine($"Searchable PDF saved: {outputPdfPath}")
End Sub

' Same API works for multi-page TIFF or existing PDF input
Public Sub MakePdfSearchable(scannedPdfPath As String, outputPdfPath As String)
    Dim result = New IronTesseract().Read(scannedPdfPath)
    result.SaveAsSearchablePdf(outputPdfPath)
End Sub

SaveAsSearchablePdf() incrusta el texto OCR como una capa invisible alineada a las palabras reconocidas, haciendo que el documento sea totalmente buscable sin alterar su apariencia visual. La guía práctica en formato PDF, que permite realizar búsquedas , abarca la selección del rango de páginas y las opciones de compresión. En la página de ejemplos en formato PDF con función de búsqueda encontrará un ejemplo práctico.

Problema 1: Excepción DllNotFoundException para binarios de Leptonica o Tesseract

Charlesw Tesseract: System.DllNotFoundException: Unable to load DLL 'leptonica-1.82.0': The specified module could not be found. Esta excepción se dispara cuando la DLL nativa de Leptonica no está en la ubicación esperada. Es común en contenedores Docker nuevos, agentes CI o cualquier entorno donde la carpeta runtimes/ del paquete NuGet no se copió correctamente.

Solución: Elimina el paquete Tesseract. Instala IronOcr.IronOCR incluye internamente todos los binarios nativos y no realiza invocaciones P/Invoke en el sistema Leptonica. La excepción no puede producirse porque no existe ninguna dependencia externa de Leptonica:

dotnet remove package Tesseract
:InstallCmd dotnet add package IronOcr

dotnet remove package Tesseract
:InstallCmd dotnet add package IronOcr

No se requiere apt-get install libleptonica-dev. No hay entradas <CopyToOutputDirectory> para DLLs nativas.

Problema 2: Errores en la ruta de Tessdata después de la implementación.

Charlesw Tesseract: Tesseract.TesseractException: Failed to initialise tesseract engine. Esto se dispara cuando TessDataPath no se resuelve en tiempo de ejecución. Compila sin error, falla solo en tiempo de ejecución, y la ruta de fallo depende del entorno de despliegue.

Solución: El concepto de ruta tessdata no existe en IronOCR. Elimina la constante, elimina el XML CopyToOutputDirectory en .csproj, y elimina el método de fábrica que lo construye. Los datos de idioma se distribuyen como paquetes NuGet :

# Replace this manual tessdata file management:
#   tessdata/eng.traineddata  (15 MB, manually downloaded)
#   tessdata/fra.traineddata  (15 MB, manually downloaded)
#   .csproj <CopyToOutputDirectory> entry

# With NuGet packages:
dotnet add package IronOcr.Languages.French

# Replace this manual tessdata file management:
#   tessdata/eng.traineddata  (15 MB, manually downloaded)
#   tessdata/fra.traineddata  (15 MB, manually downloaded)
#   .csproj <CopyToOutputDirectory> entry

# With NuGet packages:
dotnet add package IronOcr.Languages.French

La guía para varios idiomas muestra cómo configurar el reconocimiento de varios idiomas después de agregar paquetes de idiomas.

Problema 3: La compilación del contenedor falla cuando se actualiza la imagen base.

Charlesw Tesseract: El Dockerfile incluye apt-get install -y libleptonica-dev para satisfacer la dependencia nativa de Leptonica. Cuando la imagen base pasa de Debian Bullseye a Bookworm, o cuando el nombre del paquete Leptonica cambia entre distribuciones, la compilación falla con un error de apt. Para solucionarlo, es necesario saber qué nombre de paquete utilizar en la nueva distribución.

Solución: Elimina la línea de Leptonica apt-get por completo.IronOCR en Linux solo requiere el paquete estándar libgdiplus que cualquier aplicación .NET que use System.Drawing ya necesita:

# Before: Leptonica explicit install — breaks on base image updates
RUN apt-get update && apt-get install -y libleptonica-dev

# After: standard .NET Linux requirement only
RUN apt-get update && apt-get install -y libgdiplus

La guía de implementación de Docker proporciona plantillas de Dockerfile probadas para imágenes base comunes. No se requiere ningún código de infraestructura específico de Charlesw.

Problema 4: El patrón iterador falla en páginas vacías o con espacios en blanco.

Charlesw Tesseract: El ResultIterator devuelve null de iter.GetText() en algunos segmentos de página, requiriendo verificaciones explícitas de nulidad a lo largo del bucle. Omitir una verificación de nulidad causa NullReferenceException en páginas en blanco o imágenes sin texto reconocible.

Solución: Las colecciones de resultados de IronOCR nunca son nulas. Las páginas vacías devuelven colecciones vacías. Compruebe el contenido del texto en lugar de las referencias nulas:

// Before: null checks required at every iterator level
var wordText = iter.GetText(PageIteratorLevel.Word);
if (wordText != null && wordText.Trim().Length > 0)
    results.Add(wordText.Trim());

// After: collection is safe to enumerate; check content as needed
foreach (var word in result.Pages.SelectMany(p => p.Lines).SelectMany(l => l.Words))
{
    if (!string.IsNullOrWhiteSpace(word.Text))
        results.Add(word.Text);
}

// Before: null checks required at every iterator level
var wordText = iter.GetText(PageIteratorLevel.Word);
if (wordText != null && wordText.Trim().Length > 0)
    results.Add(wordText.Trim());

// After: collection is safe to enumerate; check content as needed
foreach (var word in result.Pages.SelectMany(p => p.Lines).SelectMany(l => l.Words))
{
    if (!string.IsNullOrWhiteSpace(word.Text))
        results.Add(word.Text);
}

' Before: null checks required at every iterator level
Dim wordText = iter.GetText(PageIteratorLevel.Word)
If wordText IsNot Nothing AndAlso wordText.Trim().Length > 0 Then
    results.Add(wordText.Trim())
End If

' After: collection is safe to enumerate; check content as needed
For Each word In result.Pages.SelectMany(Function(p) p.Lines).SelectMany(Function(l) l.Words)
    If Not String.IsNullOrWhiteSpace(word.Text) Then
        results.Add(word.Text)
    End If
Next

Problema 5: Violaciones de seguridad de roscas bajo carga

Charlesw Tesseract: TesseractEngine no es seguro para hilos. Compartir una misma instancia entre varias solicitudes concurrentes en una aplicación ASP.NET provoca infracciones de acceso o resultados corruptos. La solución habitual consiste en crear un motor por hilo, pero esto no resulta obvio a partir de la API y los mensajes de error cuando algo falla son excepciones nativas crípticas.

Solución: IronTesseract es seguro para hilos. Una instancia puede atender solicitudes concurrentes, o para un máximo rendimiento, crear una por hilo en un Parallel.ForEach — ambos patrones funcionan sin modificación:

// Thread-safe parallel processing — IronTesseract handles concurrent access
var results = new System.Collections.Concurrent.ConcurrentBag<string>();
Parallel.ForEach(imageFiles, imagePath =>
{
    var ocr    = new IronTesseract();
    var result = ocr.Read(imagePath);
    results.Add(result.Text);
});

// Thread-safe parallel processing — IronTesseract handles concurrent access
var results = new System.Collections.Concurrent.ConcurrentBag<string>();
Parallel.ForEach(imageFiles, imagePath =>
{
    var ocr    = new IronTesseract();
    var result = ocr.Read(imagePath);
    results.Add(result.Text);
});

Imports System.Collections.Concurrent
Imports System.Threading.Tasks

' Thread-safe parallel processing — IronTesseract handles concurrent access
Dim results As New ConcurrentBag(Of String)()
Parallel.ForEach(imageFiles, Sub(imagePath)
    Dim ocr As New IronTesseract()
    Dim result = ocr.Read(imagePath)
    results.Add(result.Text)
End Sub)

La guía de OCR asíncrono abarca patrones asíncronos para controladores ASP.NET Core donde el bloqueo de subprocesos no es aceptable.

Problema 6: Falta el binario ARM64 en tiempo de ejecución.

Charlesw Tesseract: En los agentes de CI de AWS Graviton (Linux ARM64) o Apple Silicon, es posible que el paquete archivado no incluya un binario nativo para ARM64. El fallo es un DllNotFoundException o un BadImageFormatException en la creación del motor — un error en tiempo de ejecución en una plataforma para la que el paquete no tiene camino de soporte.

Solución:IronOCR distribuye binarios ARM64 validados tanto para Linux como para macOS. Implementación en ARM64 sin cambios en el código. La guía de implementación para Linux y la guía de implementación para macOS confirman los identificadores de tiempo de ejecución compatibles.

Pre-Migración

Analiza el código fuente para identificar todos los patrones que vayan a cambiar:

# Find all references to Tesseract namespace (engine creation, Pix usage, iterator usage)
grep -rn "using Tesseract" --include="*.cs" .

# Find TesseractEngine instantiation points
grep -rn "TesseractEngine" --include="*.cs" .

# Find Pix usage (Leptonica image type)
grep -rn "Pix\." --include="*.cs" .

# Find tessdata path constants and methods
grep -rn "tessdata\|TessDataPath\|traineddata" --include="*.cs" .

# Find platform-conditional deployment code
grep -rn "IsOSPlatform\|DOTNET_RUNNING_IN_CONTAINER\|LD_LIBRARY_PATH" --include="*.cs" .

# Find iterator pattern usage
grep -rn "GetIterator\|ResultIterator\|PageIteratorLevel" --include="*.cs" .

# Find confidence calls
grep -rn "GetMeanConfidence\|GetConfidence" --include="*.cs" .

# Find .csproj tessdata copy entries
grep -rn "tessdata" --include="*.csproj" .

# Find all references to Tesseract namespace (engine creation, Pix usage, iterator usage)
grep -rn "using Tesseract" --include="*.cs" .

# Find TesseractEngine instantiation points
grep -rn "TesseractEngine" --include="*.cs" .

# Find Pix usage (Leptonica image type)
grep -rn "Pix\." --include="*.cs" .

# Find tessdata path constants and methods
grep -rn "tessdata\|TessDataPath\|traineddata" --include="*.cs" .

# Find platform-conditional deployment code
grep -rn "IsOSPlatform\|DOTNET_RUNNING_IN_CONTAINER\|LD_LIBRARY_PATH" --include="*.cs" .

# Find iterator pattern usage
grep -rn "GetIterator\|ResultIterator\|PageIteratorLevel" --include="*.cs" .

# Find confidence calls
grep -rn "GetMeanConfidence\|GetConfidence" --include="*.cs" .

# Find .csproj tessdata copy entries
grep -rn "tessdata" --include="*.csproj" .

Tenga en cuenta los entornos de implementación a los que se dirige el proyecto (Docker, Linux, ARM64, Azure, AWS): estos son los entornos donde charlesw/tesseract requiere la mayor cantidad de configuración que IronOCR elimina.

Migración de código

1. Ejecuta dotnet remove package Tesseract para desinstalar el envoltorio charlesw
2. Ejecuta dotnet add package IronOcr para instalar IronOCR
3. Añade IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY"; al iniciar la aplicación
4. Reemplaza todas las declaraciones using Tesseract; con using IronOcr;
5. Elimine la constante de ruta de datos de prueba y cualquier método que construya la ruta por entorno.
6. Elimina todos los bloques RuntimeInformation.IsOSPlatform() escritos para la selección de ruta de tessdata
7. Elimina las entradas <CopyToOutputDirectory> para archivos de tessdata de todos los archivos .csproj
8. Elimina los archivos de tessdata .traineddata del control de código fuente o de las tiendas de artefactos de despliegue
9. Añade dotnet add package IronOcr.Languages.* para cada idioma previamente desplegado como un archivo .traineddata
10. Reemplaza cadenas TesseractEngine + Pix.LoadFromFile() + engine.Process() con new IronTesseract().Read()
11. Reemplaza todas las llamadas Pix.LoadFromFile() y Pix.LoadFromMemory() con input.LoadImage()
12. Reemplaza todas las llamadas page.GetText() con result.Text
13. Reemplaza la extracción de palabras/líneas basada en iterador con acceso directo a colecciones en result.Pages
14. Reemplaza la lógica de umbral iter.GetConfidence() con LINQ en result.Words o result.Lines
15. Elimina libleptonica-dev / leptonica-1.82.0.dll de Dockerfiles y scripts de despliegue

Posmigración

Verifique lo siguiente después de completar las actualizaciones del código:

• El OCR se ejecuta correctamente en Windows sin errores de DLL nativas.
• OCR se ejecuta exitosamente en un contenedor Docker Linux sin ningún cambio en apt-get más allá de libgdiplus
• El OCR produce texto en ARM64 si esa plataforma está en la matriz de implementación.
• Los archivos TIFF de varias páginas devuelven el texto de todos los fotogramas, no solo del primero.
• El filtrado de confianza devuelve el mismo conjunto lógico de palabras de alta confianza que la implementación del iterador anterior.
• Los documentos en idiomas específicos (francés, alemán, etc.) se reconocen correctamente después de instalar los paquetes NuGet de idioma.
• Las operaciones de OCR paralelas se completan sin excepciones ni resultados corruptos.
• Se genera un archivo PDF con capacidad de búsqueda donde la implementación anterior solo devolvía texto.
• Compilación de pipelines de CI/CD sin pasos de descarga de datos de prueba ni comandos de instalación de Leptonica.
• Prueba de humo con el mismo corpus de imágenes utilizado para validar la implementación anterior.