Niniejszy przewodnik przeprowadza programistów .NET przez proces pełnej migracji zPatagames Tesseract.NET SDKdo IronOCR. Obejmuje to mechaniczne tłumaczenie API, wdrożenie wielopłatformowe, które stanowi podstawę większości migracji, oraz praktyczne zmiany w kodzie wymagane do przeniesienia produkcyjnego potoku OCR z komercyjnego opakowania przeznaczonego wyłącznie dla systemu Windows do biblioteki działającej bez modyfikacji w systemach Windows, Linux, macOS, Docker, Azure i AWS.

Dlaczego warto przejść z Patagames Tesseract.NET SDK

Większość zespołów, które rozważają zastąpienie Patagames, nie jest niezadowolona z dokładności OCR. Napotykają przeszkodę wdrożeniową — cel w postaci kontenera Linux, projekt migracji do chmury lub potok CI na Ubuntu — i odkrywają, że natywny plik binarny przeznaczony wyłącznie dla systemu Windows po prostu nie ma szans na tej platformie. To jedno ograniczenie determinuje pozostałą część oceny migracji.

Wdrożenie wyłącznie w systemie Windows blokuje nowoczesny stos .NET. Firma Patagames dostarcza natywne pliki binarne dla systemu Windows dla swojego opakowania silnika Tesseract. Nie ma pakietów uruchomieniowych dla systemów Linux x64, macOS ani ARM. Klasa OcrApi wczytuje bibliotekę DLL systemu Windows w trakcie działania; na każdym innym systemie operacyjnym aplikacja nie uruchamia się. Dodaj zależność System.Drawing.Bitmap, którą Microsoft formalnie oznaczył jako nieobsługiwaną dla nowego rozwoju międzyplatformowego, a biblioteka jest niekompatybilna z domyślnym modelem wdrażania każdego dostawcy chmury i orchestru kontenerów.

Płacenie stawek komercyjnych za darmowy silnik bez dostępu międzyplatformowego. Silnik Tesseract, na którym opiera się Patagames, jest open source i darmowy. Darmowe opakowania społecznościowe, takie jak tesseractocr, również dostarczają dziś wstępnie zbudowane binaria Windows, co eliminuje główny argument wygody, który Patagames historycznie oferował. Licencja komercyjna na Patagames zapewnia nieco bardziej przejrzystą powierzchnię API w porównaniu z surowym Tesseractem, ale nie dodaje przetwarzania wstępnego, obsługi plików PDF, możliwości wyszukiwania w plikach PDF ani wdrażania na wielu platformach — czterech funkcji, które definiują kompletną bibliotekę OCR w 2026 roku.

Niejasne ceny uniemożliwiają planowanie budżetu. Patagames nie publikuje cen licencji. Ocena biblioteki wymaga kontaktu z działem sprzedaży przed dokonaniem jakiegokolwiek porównania kosztów. Ceny IronOCR zaczynają się od $999 za wieczystą licencję Lite dla jednego dewelopera z rokiem aktualizacji wliczonych. Zespoły mogą ocenić stosunek kosztów do możliwości bez konieczności przechodzenia przez proces sprzedaży. Pełne informacje na temat poziomów licencji można znaleźć na stronie licencyjnej IronOCR.

Surowe zmienne Tesseract wyciekają przez API. Ustawienie trybu segmentacji strony w Patagames wymaga wywołania api.SetVariable("tessedit_pageseg_mode", "3") — surowego przypisania zmiennej Tesseract opartego na łańcuchu znaków, bez IntelliSense, bez sprawdzania w czasie kompilacji i bez odkrywalności. Jeśli nazwa zmiennej jest błędnie napisana, wywołanie nie powoduje żadnego działania.IronOCR opakowuje każdą opcję konfiguracji Tesseract w mocno typowanych właściwościach na IronTesseract.Configuration.

Brak zorganizowanego wyjścia poza płaski łańcuch znaków. Patagames GetTextFromImage zwraca pojedynczy łańcuch znaków. Nie ma dostępu do granic słów, grupowania wierszy, struktury akapitów ani wyników pewności dla poszczególnych słów. Aplikacje, które muszą wyodrębniać określone pola z formularzy lub weryfikować dokładność OCR na poziomie poszczególnych słów, nie mają podstaw do działania w oparciu o API Patagames.

Pipeline'y CI/CD zatrzymują się na etapie Linuksa. Nowoczesne zespoły programistów .NET uruchamiają CI na Linuksie — GitHub Actions, GitLab CI i Azure DevOps domyślnie korzystają z runnerów opartych na Linuksie. Projekt odwołujący się do Tesseract.Net.SDK albo nie zbuduje natywnego odniesienia binarnego, albo zawiedzie podczas testów integracyjnych w trakcie działania. Każdy przebieg testu wymaga środowiska CI przeznaczonego dla systemu Windows lub rozwiązania zastępczego, które całkowicie symuluje warstwę OCR.

Podstawowy problem

Patagames jest przeznaczony wyłącznie dla systemu Windows. W momencie zmiany miejsca wdrożenia biblioteka nie może za nim podążać:

// Patagames: Windows DLL loads; fails on Linux container or macOS developer machine
using var api = OcrApi.Create();
api.Init(@"./tessdata", "eng"); // tessdata path — must be manually managed in every environment
using var bitmap = new Bitmap(imagePath); // System.Drawing — unsupported on non-Windows targets
return api.GetTextFromImage(bitmap);

// Patagames: Windows DLL loads; fails on Linux container or macOS developer machine
using var api = OcrApi.Create();
api.Init(@"./tessdata", "eng"); // tessdata path — must be manually managed in every environment
using var bitmap = new Bitmap(imagePath); // System.Drawing — unsupported on non-Windows targets
return api.GetTextFromImage(bitmap);

// IronOCR: same code runs on Windows, Linux, macOS, Docker, Azure, AWS
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";
var text = new IronTesseract().Read(imagePath).Text;

// IronOCR: same code runs on Windows, Linux, macOS, Docker, Azure, AWS
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";
var text = new IronTesseract().Read(imagePath).Text;

Brak katalogu tessdata. Brak natywnej ścieżki DLL. Bez warunków związanych z platformą. Wykres zależności NuGet automatycznie określa właściwe środowisko uruchomieniowe dla każdego celu.

IronOCR a Patagames Tesseract.NET SDK: porównanie funkcji

Poniższa tabela przedstawia funkcje istotne dla zespołów, które obecnie korzystają z Patagames w środowisku produkcyjnym.

Szybki start: Migracja zPatagames Tesseract.NET SDKdo IronOCR

Krok 1: Zastąp pakiet NuGet

Usuń Patagames Tesseract.NET SDK:

dotnet remove package Tesseract.Net.SDK

dotnet remove package Tesseract.Net.SDK

Zainstaluj IronOCR z NuGet:

dotnet add package IronOcr

Aby uzyskać obsługę języków innych niż angielski, zainstaluj odpowiedni pakiet językowy:

dotnet add package IronOcr.Languages.French, IronOcr.Languages.German

Krok 2: Aktualizacja przestrzeni nazw

Zastąp przestrzenie nazw Patagames przestrzenią nazw IronOCR:

// Before (Patagames)
using Patagames.Ocr;
using Patagames.Ocr.Enums;
using System.Drawing;

// After (IronOCR)
using IronOcr;

// Before (Patagames)
using Patagames.Ocr;
using Patagames.Ocr.Enums;
using System.Drawing;

// After (IronOCR)
using IronOcr;

Krok 3: Inicjalizacja licencji

Dodaj inicjalizację licencji przy uruchomieniu aplikacji (przed pierwszym wywołaniem IronTesseract):

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

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

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

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

Dostępna jest bezpłatna licencja próbna na ironsoftware.com/C#/ocr/ na rozpoczęcie testów migracyjnych bez zakupu.

Przykłady migracji kodu

Przetwarzanie folderów w trybie wsadowym

W fazie 1 pokazano wyodrębnianie pojedynczego obrazu. Produkcje Patagames zazwyczaj inicjalizują OcrApi wewnątrz pętli, wywołując api.Init() przy każdej iteracji — co ponownie ładuje dane tessdata i ponownie inicjalizuje silnik Tesseract dla każdego pliku. Ten wzór składa koszt inicjalizacji na setki dokumentów.

Podejście Patagames:

// NuGet: Tesseract.Net.SDK
using Patagames.Ocr;
using System.Drawing;
using System.IO;

public class PatagamesBatchProcessor
{
    private const string TessDataPath = @"./tessdata";

    public Dictionary<string, string> ProcessFolder(string folderPath)
    {
        var results = new Dictionary<string, string>();

        foreach (var file in Directory.GetFiles(folderPath, "*.jpg"))
        {
            // OcrApi re-initialized per file — tessdata loaded each time
            using var api = OcrApi.Create();
            api.Init(TessDataPath, "eng");

            using var bitmap = new Bitmap(file);
            var text = api.GetTextFromImage(bitmap);

            results[Path.GetFileName(file)] = text;
        }

        return results;
    }
}

// NuGet: Tesseract.Net.SDK
using Patagames.Ocr;
using System.Drawing;
using System.IO;

public class PatagamesBatchProcessor
{
    private const string TessDataPath = @"./tessdata";

    public Dictionary<string, string> ProcessFolder(string folderPath)
    {
        var results = new Dictionary<string, string>();

        foreach (var file in Directory.GetFiles(folderPath, "*.jpg"))
        {
            // OcrApi re-initialized per file — tessdata loaded each time
            using var api = OcrApi.Create();
            api.Init(TessDataPath, "eng");

            using var bitmap = new Bitmap(file);
            var text = api.GetTextFromImage(bitmap);

            results[Path.GetFileName(file)] = text;
        }

        return results;
    }
}

Podejście IronOCR:

// NuGet: IronOcr
using IronOcr;
using System.IO;

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

public class IronOcrBatchProcessor
{
    public Dictionary<string, string> ProcessFolder(string folderPath)
    {
        var results = new Dictionary<string, string>();
        // Single engine instance — initialized once, reused across all files
        var ocr = new IronTesseract();

        foreach (var file in Directory.GetFiles(folderPath, "*.jpg"))
        {
            var result = ocr.Read(file);
            results[Path.GetFileName(file)] = result.Text;
        }

        return results;
    }
}

// NuGet: IronOcr
using IronOcr;
using System.IO;

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

public class IronOcrBatchProcessor
{
    public Dictionary<string, string> ProcessFolder(string folderPath)
    {
        var results = new Dictionary<string, string>();
        // Single engine instance — initialized once, reused across all files
        var ocr = new IronTesseract();

        foreach (var file in Directory.GetFiles(folderPath, "*.jpg"))
        {
            var result = ocr.Read(file);
            results[Path.GetFileName(file)] = result.Text;
        }

        return results;
    }
}

Instancja IronTesseractIronOCR utrzymuje stan silnika podczas wywołań. Ponowne wykorzystanie jednej instancji dla całej partii eliminuje obciążenie związane z inicjalizacją każdego pliku i całkowicie usuwa zależność od ścieżki tessdata. Aby równolegle przetwarzać wsadowo na wielu rdzeniach CPU, zobacz przykład wielowątkowości — twórz po jednym IronTesseract na wątek zamiast dzielić jedną instancję.

Migracja trybu segmentacji stron

Patagames wystawia tryb segmentacji strony za pomocą surowego wywołania SetVariable z kluczem łańcuchowym i wartością całkowitą rzutowaną na łańcuch. Brak IntelliSense, brak walidacji enum, brak podpowiedzi dokumentacji w miejscu wywołania. Pojedyncza cyfra decyduje o tym, czy Tesseract traktuje dane wejściowe jako pojedynczy blok tekstu, kolumnę, słowo czy pojedynczy znak — i nie ma żadnej informacji zwrotnej w przypadku błędnego wpisania nazwy zmiennej.

Podejście Patagames:

// NuGet: Tesseract.Net.SDK
using Patagames.Ocr;
using Patagames.Ocr.Enums;
using System.Drawing;

public string OcrSingleLineField(string imagePath)
{
    using var api = OcrApi.Create();
    api.Init(@"./tessdata", "eng");

    // Raw variable string — no IntelliSense, no validation
    // PageSegmentationMode.SingleLine == 7
    api.SetVariable("tessedit_pageseg_mode", "7");

    // Additional variable to suppress dictionary output
    api.SetVariable("tessedit_char_whitelist", "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz -.:/");

    using var bitmap = new Bitmap(imagePath);
    return api.GetTextFromImage(bitmap);
}

// NuGet: Tesseract.Net.SDK
using Patagames.Ocr;
using Patagames.Ocr.Enums;
using System.Drawing;

public string OcrSingleLineField(string imagePath)
{
    using var api = OcrApi.Create();
    api.Init(@"./tessdata", "eng");

    // Raw variable string — no IntelliSense, no validation
    // PageSegmentationMode.SingleLine == 7
    api.SetVariable("tessedit_pageseg_mode", "7");

    // Additional variable to suppress dictionary output
    api.SetVariable("tessedit_char_whitelist", "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz -.:/");

    using var bitmap = new Bitmap(imagePath);
    return api.GetTextFromImage(bitmap);
}

Podejście IronOCR:

// NuGet: IronOcr
using IronOcr;

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

public string OcrSingleLineField(string imagePath)
{
    var ocr = new IronTesseract();

    // Strongly typed enum — discoverable through IntelliSense
    ocr.Configuration.PageSegmentationMode = TesseractPageSegmentationMode.SingleLine;

    var result = ocr.Read(imagePath);
    return result.Text;
}

// NuGet: IronOcr
using IronOcr;

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

public string OcrSingleLineField(string imagePath)
{
    var ocr = new IronTesseract();

    // Strongly typed enum — discoverable through IntelliSense
    ocr.Configuration.PageSegmentationMode = TesseractPageSegmentationMode.SingleLine;

    var result = ocr.Read(imagePath);
    return result.Text;
}

Każda opcja konfiguracji Tesseract, którą Patagames wystawia przez SetVariable, ma bezpośredni silnie typowany odpowiednik w IronTesseract.Configuration. Migracja polega na mechanicznej zamianie literałów łańcuchowych na nazwane wartości wyliczeniowe. Pełny opis konfiguracji znajduje się w dokumentacji API IronTesseract. Przewodnik dotyczący czytania konkretnych dokumentów zawiera informacje o tym, kiedy stosować poszczególne tryby segmentacji stron w różnych typach dokumentów.

Wynik Zastąpienie wzorca iteratora

Patagames zwraca płaski łańcuch znaków z GetTextFromImage. Wyodrębnianie poszczególnych słów, ich ramek lub wyników pewności z danych wyjściowych Patagames wymaga napisania parsera na podstawie zwróconego ciągu znaków — lub uzyskania dostępu do podstawowego interfejsu API iteratora wyników Tesseract bezpośrednio poprzez interop. Żadne z tych podejść nie jest niezawodne ani łatwe w utrzymaniu.IronOCR wystawia w pełni zorganizowany OcrResult z natywnym dostępem do każdego poziomu hierarchii dokumentów.

Podejście Patagames:

// NuGet: Tesseract.Net.SDK
using Patagames.Ocr;
using System.Drawing;

public void ExtractWordsWithPositions(string imagePath)
{
    using var api = OcrApi.Create();
    api.Init(@"./tessdata", "eng");

    using var bitmap = new Bitmap(imagePath);
    // Tylko płaski ciąg znaków — no word positions, no confidence, no line grouping
    var text = api.GetTextFromImage(bitmap);

    // Only option: split on whitespace and hope line breaks survive
    var words = text.Split(new[] { ' ', '\n', '\r' },
        StringSplitOptions.RemoveEmptyEntries);

    foreach (var word in words)
    {
        // Nie X, Y, Width, Height — position information is lost
        Console.WriteLine(word);
    }
}

// NuGet: Tesseract.Net.SDK
using Patagames.Ocr;
using System.Drawing;

public void ExtractWordsWithPositions(string imagePath)
{
    using var api = OcrApi.Create();
    api.Init(@"./tessdata", "eng");

    using var bitmap = new Bitmap(imagePath);
    // Tylko płaski ciąg znaków — no word positions, no confidence, no line grouping
    var text = api.GetTextFromImage(bitmap);

    // Only option: split on whitespace and hope line breaks survive
    var words = text.Split(new[] { ' ', '\n', '\r' },
        StringSplitOptions.RemoveEmptyEntries);

    foreach (var word in words)
    {
        // Nie X, Y, Width, Height — position information is lost
        Console.WriteLine(word);
    }
}

Podejście IronOCR:

// NuGet: IronOcr
using IronOcr;

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

public void ExtractWordsWithPositions(string imagePath)
{
    var result = new IronTesseract().Read(imagePath);

    foreach (var page in result.Pages)
    {
        Console.WriteLine($"Page {page.PageNumber}: {page.Width}x{page.Height}px");

        foreach (var paragraph in page.Paragraphs)
        {
            Console.WriteLine($"  Paragraph at ({paragraph.X}, {paragraph.Y})");
            Console.WriteLine($"  Text: {paragraph.Text}");
        }

        foreach (var word in page.Words)
        {
            // Bounding box, confidence, and text for every word
            Console.WriteLine($"  Word: '{word.Text}' at ({word.X},{word.Y}) " +
                              $"size {word.Width}x{word.Height} " +
                              $"confidence {word.Confidence:F1}%");
        }
    }

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

// NuGet: IronOcr
using IronOcr;

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

public void ExtractWordsWithPositions(string imagePath)
{
    var result = new IronTesseract().Read(imagePath);

    foreach (var page in result.Pages)
    {
        Console.WriteLine($"Page {page.PageNumber}: {page.Width}x{page.Height}px");

        foreach (var paragraph in page.Paragraphs)
        {
            Console.WriteLine($"  Paragraph at ({paragraph.X}, {paragraph.Y})");
            Console.WriteLine($"  Text: {paragraph.Text}");
        }

        foreach (var word in page.Words)
        {
            // Bounding box, confidence, and text for every word
            Console.WriteLine($"  Word: '{word.Text}' at ({word.X},{word.Y}) " +
                              $"size {word.Width}x{word.Height} " +
                              $"confidence {word.Confidence:F1}%");
        }
    }

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

Pełna struktura OcrResult - strony, akapity, linie, słowa i znaki - eliminuje potrzebę jakiegokolwiek parsera przetwarzania końcowego. Koordynaty WORD umożliwiają wyodrębnianie pól według pozycji, co stanowi podstawę przetwarzania faktur, OCR formularzy i wyodrębniania tabel. Pełną hierarchię można znaleźć w przewodniku po wynikach strukturalnych, a informacje na temat filtrowania słów o niskim poziomie pewności — w przewodniku po wynikach pewności.

Przetwarzanie wielostronicowych plików TIFF

Patagames akceptuje System.Drawing.Bitmap. Wieloklatkowy TIFF zawiera wiele osadzonych obrazów, ale System.Drawing.Bitmap nie automatycznie enumeruje klatek — należy użyć Image.SelectActiveFrame(), aby ręcznie przez nie przechodzić i przekazać każdą bitmapę klatki do GetTextFromImage w pętli. API enumeracji klatek nie jest oczywiste, a komunikaty o błędach, gdy zawiedzie, nie są opisowe.

Podejście Patagames:

// NuGet: Tesseract.Net.SDK
using Patagames.Ocr;
using System.Drawing;
using System.Drawing.Imaging;
using System.Text;

public string ProcessMultiPageTiff(string tiffPath)
{
    using var api = OcrApi.Create();
    api.Init(@"./tessdata", "eng");

    var sb = new StringBuilder();

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

    for (int i = 0; i < frameCount; i++)
    {
        // Manual frame selection — FrameDimension.Page required
        tiffImage.SelectActiveFrame(FrameDimension.Page, i);

        using var frameBitmap = new Bitmap(tiffImage);
        var pageText = api.GetTextFromImage(frameBitmap);
        sb.AppendLine(pageText);
    }

    return sb.ToString();
}

// NuGet: Tesseract.Net.SDK
using Patagames.Ocr;
using System.Drawing;
using System.Drawing.Imaging;
using System.Text;

public string ProcessMultiPageTiff(string tiffPath)
{
    using var api = OcrApi.Create();
    api.Init(@"./tessdata", "eng");

    var sb = new StringBuilder();

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

    for (int i = 0; i < frameCount; i++)
    {
        // Manual frame selection — FrameDimension.Page required
        tiffImage.SelectActiveFrame(FrameDimension.Page, i);

        using var frameBitmap = new Bitmap(tiffImage);
        var pageText = api.GetTextFromImage(frameBitmap);
        sb.AppendLine(pageText);
    }

    return sb.ToString();
}

Podejście IronOCR:

// NuGet: IronOcr
using IronOcr;

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

public string ProcessMultiPageTiff(string tiffPath)
{
    using var input = new OcrInput();
    // LoadImageFrames handles all frames automatically
    input.LoadImageFrames(tiffPath);

    // Optional: apply preprocessing to all frames at once
    input.Deskew();
    input.DeNoise();

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

    // Per-page access if needed
    foreach (var page in result.Pages)
    {
        Console.WriteLine($"Page {page.PageNumber}: {page.Words.Length} words");
    }

    return result.Text;
}

// NuGet: IronOcr
using IronOcr;

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

public string ProcessMultiPageTiff(string tiffPath)
{
    using var input = new OcrInput();
    // LoadImageFrames handles all frames automatically
    input.LoadImageFrames(tiffPath);

    // Optional: apply preprocessing to all frames at once
    input.Deskew();
    input.DeNoise();

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

    // Per-page access if needed
    foreach (var page in result.Pages)
    {
        Console.WriteLine($"Page {page.PageNumber}: {page.Words.Length} words");
    }

    return result.Text;
}

OcrInput.LoadImageFrames() obsługuje enumerację klatek wewnętrznie i stosuje przetwarzanie wstępne do każdej klatki w potoku. Ceremonia wyboru klatki System.Drawing całkowicie znika. Zapoznaj się z instrukcją dotyczącą plików TIFF i GIF, aby poznać dodatkowe opcje, w tym wybór pojedynczych klatek, gdy potrzebne są tylko określone strony.

Wprowadzanie plików PDF bez zewnętrznego renderera

Patagames nie obsługuje natywnie formatu PDF. Rurociąg OCR oparty na Patagames wymaga zewnętrznej biblioteki renderowania PDF — PdfiumViewer, iText lub PDFSharp — aby przekonwertować każdą stronę na Bitmap przed przekazaniem do GetTextFromImage. Ta zewnętrzna zależność powoduje dodatkowe obciążenie związane z zarządzaniem pakietami, konieczność uwzględnienia oddzielnej licencji oraz tworzy dodatkowy punkt awarii. Jakość renderowania różni się również w zależności od biblioteki, co wpływa na dokładność OCR niezależnie od silnika Tesseract.

Podejście Patagames:

// NuGet: Tesseract.Net.SDK + PdfiumViewer (external dependency)
using Patagames.Ocr;
using PdfiumViewer; // separate NuGet package required
using System.Drawing;
using System.Text;

public string OcrPdfDocument(string pdfPath)
{
    using var api = OcrApi.Create();
    api.Init(@"./tessdata", "eng");

    var sb = new StringBuilder();

    // External renderer required — Patagames has no PDF support
    using var pdfDoc = PdfDocument.Load(pdfPath);

    for (int page = 0; page < pdfDoc.PageCount; page++)
    {
        // Render at 300 DPI for acceptable OCR accuracy
        using var img = pdfDoc.Render(page, 300, 300, false);
        using var bitmap = new Bitmap(img);

        var pageText = api.GetTextFromImage(bitmap);
        sb.AppendLine(pageText);
    }

    return sb.ToString();
}

// NuGet: Tesseract.Net.SDK + PdfiumViewer (external dependency)
using Patagames.Ocr;
using PdfiumViewer; // separate NuGet package required
using System.Drawing;
using System.Text;

public string OcrPdfDocument(string pdfPath)
{
    using var api = OcrApi.Create();
    api.Init(@"./tessdata", "eng");

    var sb = new StringBuilder();

    // External renderer required — Patagames has no PDF support
    using var pdfDoc = PdfDocument.Load(pdfPath);

    for (int page = 0; page < pdfDoc.PageCount; page++)
    {
        // Render at 300 DPI for acceptable OCR accuracy
        using var img = pdfDoc.Render(page, 300, 300, false);
        using var bitmap = new Bitmap(img);

        var pageText = api.GetTextFromImage(bitmap);
        sb.AppendLine(pageText);
    }

    return sb.ToString();
}

Podejście IronOCR:

// NuGet: IronOcr only — no external PDF renderer
using IronOcr;

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

public string OcrPdfDocument(string pdfPath)
{
    using var input = new OcrInput();
    input.LoadPdf(pdfPath);

    // Preprocessing applies to every page in one call
    input.Deskew();

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

    // Full per-page structured access
    foreach (var page in result.Pages)
    {
        Console.WriteLine($"Page {page.PageNumber}: {page.Paragraphs.Length} paragraphs");
    }

    return result.Text;
}

// NuGet: IronOcr only — no external PDF renderer
using IronOcr;

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

public string OcrPdfDocument(string pdfPath)
{
    using var input = new OcrInput();
    input.LoadPdf(pdfPath);

    // Preprocessing applies to every page in one call
    input.Deskew();

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

    // Full per-page structured access
    foreach (var page in result.Pages)
    {
        Console.WriteLine($"Page {page.PageNumber}: {page.Paragraphs.Length} paragraphs");
    }

    return result.Text;
}

Jeden pakiet NuGet zastępuje dwa. Krok renderowania znika. Przewodnik dotyczący plików PDF obejmuje pliki jednostronicowe, wielostronicowe oraz chronione hasłem. W przypadku przepływu pracy związanego z tworzeniem plików PDF z możliwością wyszukiwania — generowania dokumentu z możliwością wyszukiwania za pomocą klawiszy Ctrl+F na podstawie zeskanowanego pliku PDF — przewodnik dotyczący plików PDF z możliwością wyszukiwania oraz przykład pliku PDF z możliwością wyszukiwania przedstawiają pełny proces w pięciu wierszach.

Patagames Tesseract.NET SDK API do IronOCR – dokumentacja API

Typowe problemy związane z migracją i ich rozwiązania

Problem 1: Brak katalogu Tessdata w nowym środowisku

Patagames: Wywołanie api.Init(@"./tessdata", "eng") zawodzi w czasie działania, gdy brakuje katalogu tessdata lub pliku eng.traineddata. W środowiskach kontenerowych jest to błąd występujący w momencie wdrażania, bez ostrzeżenia podczas kompilacji. Zespoły wdrażające rozwiązania w Dockerze często odkrywają to dopiero po przesłaniu obrazu.

**Rozwiązanie:**IronOCR całkowicie rezygnuje z koncepcji katalogu tessdata. Zainstaluj dane językowe jako pakiety NuGet:

dotnet add package IronOcr.Languages.English

Dane językowe rozwiązywane są w czasie budowy i automatycznie włączane do wyjścia dotnet publish. Nie ma możliwości popełnienia błędu ani pozycji na liście kontrolnej wdrożenia dotyczącej plików językowych.

Problem 2: System.Drawing.Bitmap nie działa w systemie Linux

Patagames: Konstruktor System.Drawing.Bitmap zgłasza wyjątki TypeInitializationException lub PlatformNotSupportedException na Linuxie, chyba że zainstalowany jest pakiet systemowy libgdiplus. Nawet z obecnością libgdiplus zachowanie jest niespójne w różnych dystrybucjach. Microsoft wyraźnie odradza używanie System.Drawing na platformach innych niż Windows w nowych projektach.

**Rozwiązanie:**IronOCR akceptuje bezpośrednio ścieżki plików, tablice bajtów i strumienie. Zależność System.Drawing nie jest wymagana:

// Replace this pattern:
using var bitmap = new Bitmap(imagePath); // fails without libgdiplus on Linux
api.GetTextFromImage(bitmap);

// With:
var result = new IronTesseract().Read(imagePath); // no System.Drawing required

// Replace this pattern:
using var bitmap = new Bitmap(imagePath); // fails without libgdiplus on Linux
api.GetTextFromImage(bitmap);

// With:
var result = new IronTesseract().Read(imagePath); // no System.Drawing required

Zobacz przewodnik po formatach obrazów, aby zapoznać się ze wszystkimi obsługiwanymi typami danych wejściowych, w tym tablicami bajtów i strumieniami.

Problem 3: Ciche błędy SetVariable

Patagames: api.SetVariable("tessedit_pageseg_mode", someValue) zwraca bool, ale większość dzwoniących odrzuca wartość zwróconą. Gdy nazwa zmiennej jest błędnie napisana lub przekazano wartość nieobsługiwaną, Tesseract po cichu stosuje wartość domyślną i kontynuuje działanie. Trudno jest powiązać wynikające z tego pogorszenie dokładności z wywołaniem konfiguracji.

Rozwiązanie: Właściwości konfiguracyjne IronOCRsą silnie typowane. Nieprawidłowe przypisanie powoduje błąd kompilatora, a nie ciche domyślne zachowanie w czasie wykonywania:

// Compile-time safety — no silent failures
var ocr = new IronTesseract();
ocr.Configuration.PageSegmentationMode = TesseractPageSegmentationMode.SingleBlock;
ocr.Configuration.TesseractVersion = TesseractVersion.Tesseract5; // also strongly typed

// Compile-time safety — no silent failures
var ocr = new IronTesseract();
ocr.Configuration.PageSegmentationMode = TesseractPageSegmentationMode.SingleBlock;
ocr.Configuration.TesseractVersion = TesseractVersion.Tesseract5; // also strongly typed

Problem 4: OcrApi zainicjowane wewnątrz pętli

Patagames: Zespoły, które inicjalizują OcrApi wewnątrz pętli przetwarzania, ponoszą koszty załadowania tessdata przy każdej iteracji. Typowy wzór — OcrApi.Create() i api.Init() wewnątrz foreach — jest poprawny z perspektywy izolacji wątków, ale kosztowny przy przetwarzaniu setek dokumentów.

Rozwiązanie: Utwórz po jednym IronTesseract na wątek i używaj go ponownie dla wszystkich dokumentów przypisanych do tego wątku. Instancja jest bezstanowa między wywołaniami .Read():

// One instance, many reads — engine initialized once
var ocr = new IronTesseract();
ocr.Language = OcrLanguage.English;

foreach (var file in imageFiles)
{
    var text = ocr.Read(file).Text;
    ProcessText(text);
}

// One instance, many reads — engine initialized once
var ocr = new IronTesseract();
ocr.Language = OcrLanguage.English;

foreach (var file in imageFiles)
{
    var text = ocr.Read(file).Text;
    ProcessText(text);
}

W przypadku równoległych obciążeń wsadowych należy utworzyć jedną instancję na zadanie. Zobacz przewodnik optymalizacji prędkości dla opcji dopasowania przepustowości, w tym IronTesseract.Configuration.TesseractVersion i predefiniowanych szybkości odczytu.

Problem 5: Brak działającego obrazu bazowego Docker dla systemu Linux

Patagames: Nie ma pliku binarnego Patagames zgodnego z systemem Linux. Każda próba uruchomienia aplikacji opartej na Patagames w kontenerze Docker w systemie Linux kończy się niepowodzeniem. Jedynym obejściem jest kontener oparty na Windows (FROM mcr.microsoft.com/windows/servercore), który jest znacząco większy, wolniejszy do pobrania i niekompatybilny z większością konfiguracji Kubernetes, które korzystają z pul węzłów Linux.

**Rozwiązanie:**IronOCR obsługuje standardowe obrazy bazowe systemu Linux. Przewodnik wdrażania Docker obejmuje dokładną konfigurację pliku Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY --from=build /app/publish .
#IronOCR resolves the Linux native runtime from NuGet automatically
ENTRYPOINT ["dotnet", "MyApp.dll"]

FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY --from=build /app/publish .
#IronOCR resolves the Linux native runtime from NuGet automatically
ENTRYPOINT ["dotnet", "MyApp.dll"]

Nie jest wymagany kontener Windows. Brak oddzielnej dystrybucji plików binarnych. Ten sam obraz Docker działa na dowolnym hoście kontenerowym opartym na systemie Linux.

Problem 6: OCR plików PDF wymaga dwóch pakietów NuGet

Patagames: Dodanie funkcji OCR do aplikacji Patagames wymaga drugiego pakietu NuGet do renderowania plików PDF (PdfiumViewer, iTextSharp.LGPLv2.Core lub podobnego). Każde z nich ma własne warunki licencji, częstotliwość aktualizacji i potencjalne problemy z kompatybilnością. W przypadku konfliktu między wersją renderera PDF a wersją Patagames, oba zespoły muszą współpracować w celu jego rozwiązania.

**Rozwiązanie:**IronOCR obsługuje dane wejściowe w formacie PDF natywnie, bez konieczności stosowania dodatkowego pakietu. Całkowicie usuń zależność od renderera PDF:

# Remove the PDF rendering shim
dotnet remove package PdfiumViewer

#IronOCR handles PDF natively
var result = new IronTesseract().Read("document.pdf");

# Remove the PDF rendering shim
dotnet remove package PdfiumViewer

#IronOCR handles PDF natively
var result = new IronTesseract().Read("document.pdf");

Lista kontrolna migracji Patagames Tesseract.NET SDK

Przed migracją

Przed rozpoczęciem pracy należy przeprowadzić audyt kodu źródłowego w celu zidentyfikowania wszystkich odniesień do Patagames:

# Find all files using Patagames namespaces
grep -r "Patagames.Ocr" --include="*.cs" . -l

# Find all OcrApi usage patterns
grep -r "OcrApi\|GetTextFromImage\|api\.Init\|SetVariable" --include="*.cs" .

# Find tessdata path references
grep -r "tessdata\|TessDataPath\|traineddata" --include="*.cs" .

# Find System.Drawing.Bitmap usage tied to OCR
grep -r "new Bitmap\|System\.Drawing" --include="*.cs" . -l

# Find any PDF rendering libraries used to feed Patagames
grep -r "PdfiumViewer\|iTextSharp\|PdfSharp" --include="*.csproj" .

# Find all files using Patagames namespaces
grep -r "Patagames.Ocr" --include="*.cs" . -l

# Find all OcrApi usage patterns
grep -r "OcrApi\|GetTextFromImage\|api\.Init\|SetVariable" --include="*.cs" .

# Find tessdata path references
grep -r "tessdata\|TessDataPath\|traineddata" --include="*.cs" .

# Find System.Drawing.Bitmap usage tied to OCR
grep -r "new Bitmap\|System\.Drawing" --include="*.cs" . -l

# Find any PDF rendering libraries used to feed Patagames
grep -r "PdfiumViewer\|iTextSharp\|PdfSharp" --include="*.csproj" .

Dokument: łączna liczba miejsc wywołań OcrApi.Create(), liczba różnych konfiguracji językowych api.Init(), lokalizacja katalogu tessdata w każdym środowisku wdrożeniowym oraz wszelki kod przetwarzania wstępnego napisany w System.Drawing lub ImageSharp, który opakowuje wywołania Patagames.

Migracja kodu

1. Usuń odniesienie do pakietu NuGet Tesseract.Net.SDK z wszystkich projektów.
2. Usuń wszelkie pakiety renderowania PDF NuGet (PdfiumViewer, iText, itd.), używane wyłącznie do przekazywania danych do Patagames.
3. Zainstaluj pakiet NuGet IronOcr.
4. Zainstaluj IronOcr.Languages.English i wszelkie inne wymagane pakiety językowe.
5. Dodaj IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY" przy uruchamianiu aplikacji.
6. Zastąp using Patagames.Ocr; i using Patagames.Ocr.Enums; przez using IronOcr;.
7. Zastąp każdy blok OcrApi.Create() + api.Init(path, lang) przez new IronTesseract() + ocr.Language = OcrLanguage.[Language].
8. Zastąp każde wywołanie api.GetTextFromImage(bitmap) przez ocr.Read(imagePath).Text (usuwając konstruktor Bitmap).
9. Zastąp każde wywołanie api.SetVariable("tessedit_pageseg_mode", value) przez typizowane ocr.Configuration.PageSegmentationMode = TesseractPageSegmentationMode.[Value].
10. Usuń wszelkie tworzenia System.Drawing.Bitmap, które istniały wyłącznie w celu przekazywania obrazów do Patagames.
11. Zastąp pętle renderowania PDF (jeśli istnieją) przez input.LoadPdf(pdfPath).
12. Zastąp pętle wieloklatkowych TIFF używających Image.SelectActiveFrame() przez input.LoadImageFrames(tiffPath).
13. Zastąp wszelki własny kod przetwarzania wstępnego (System.Drawing resize, contrast, threshold) równoważnymi wywołaniami filtrów OcrInput.
14. Usuń katalog tessdata ze wszystkich manifestów wdrożeniowych, plików Dockerfile oraz etapów kopiowania w CI.
15. Zaktualizuj testy integracyjne, aby działały na środowiskach CI w systemie Linux (GitHub Actions ubuntu-latest itp.) w celu weryfikacji działania na różnych platformach.

Po migracji

• Uruchom pełną Suite testów w systemie Linux (nie tylko w Windows), aby potwierdzić, że odblokowanie wdrożenia międzyplatformowego działa.
• Sprawdź, czy dokładność OCR jest równa lub lepsza od poziomu odniesienia Patagames na tym samym zestawie obrazów testowych.
• Potwierdź, że dokumenty wielojęzyczne produkują poprawne wyniki przy użyciu podejścia enum OcrLanguage.
• Przetestuj dane wejściowe PDF bezpośrednio bez zewnętrznej biblioteki renderującej i porównaj dokładność wyników z poprzednią ścieżką renderowania bitmap.
• Sprawdź, czy przetwarzanie plików TIFF z wieloma ramkami daje taką samą liczbę stron i treść tekstową jak poprzednia pętla wyliczania ramek.
• Sprawdź, czy katalog tessdata nie występuje w artefakcie wdrożeniowym i czy nie występują żadne błędy ścieżki uruchomieniowej.
• Uruchom budowę Docker skierowaną na linux/amd64 i wykonaj co najmniej jedno wywołanie OCR wewnątrz kontenera.
• Sprawdź, czy potok CI (GitHub Actions, GitLab CI, Azure DevOps) kończy się pomyślnie na domyślnym środowisku uruchomieniowym Linux.
• Sprawdź, czy wyniki zawierają oceny pewności i czy logika filtrowania oparta na pewności działa zgodnie z oczekiwaniami.
• Potwierdź, że inicjalizacja klucza licencyjnego odbywa się przed stworzeniem pierwszej instancji IronTesseract w kodzie startowym produkcji.

Kluczowe korzyści z migracji do IronOCR

Wdrażanie na wielu platformach bez zmian w kodzie. Po migracji ten sam plik binarny działa na Windows Server, kontenerach Ubuntu Docker, komputerach programistów z systemem macOS, usłudze Azure App Service na systemie Linux oraz AWS Lambda. Nie ma warunków platformowych, flag identyfikatorów środowiska uruchomieniowego ani oddzielnych artefaktów wdrożeniowych dla poszczególnych systemów operacyjnych. Migracja do chmury, która wcześniej była blokowana przez bibliotekę OCR dostępną wyłącznie dla systemu Windows, staje się standardowym wdrożeniem kontenerowym. Przewodniki wdrożeniowe dotyczące systemów Linux, Docker, Azure i AWS obejmują konfiguracje produkcyjne dla każdego z tych środowisk.

Zarządzanie tessdata znika z operacji. Katalog tessdata — jego lokalizacja, zawartość, obecność w każdym środowisku — nie stanowi już problemu operacyjnego. Dane językowe to zależność NuGet rozwiązywana w czasie budowy. Pojawia się w wyjściu dotnet publish automatycznie. Nie ma żadnych instrukcji wdrażania do aktualizacji przy dodawaniu nowego języka, żadnej warstwy Docker do unieważnienia w przypadku zmiany plików tessdata ani żadnego incydentu produkcyjnego związanego z brakującymi plikami tessdata do zbadania.

Struktura danych zastępuje analizę ciągów. Aplikacje, które wcześniej analizowały płaski ciąg znaków z GetTextFromImage w celu wyodrębnienia pól, sprawdzenia poprawności treści czy obliczenia poziomu zaufania, teraz bezpośrednio uzyskują te dane z OcrResult. Współrzędne WORD, granice wierszy, grupowanie akapitów oraz wyniki pewności dla poszczególnych słów są właściwościami pierwszej klasy. Wyodrębnianie pól według ramki ograniczającej — podstawa przetwarzania faktur i form OCR — to bezpośrednie wywołanie CropRectangle zamiast kruchego wyszukiwania podciągu.

Wbudowane przetwarzanie wstępne zastępuje niestandardowe ścieżki obrazów. Wszelki kod przetwarzania wstępnego, napisany w celu zrekompensowania braku wbudowanych filtrów Patagames, można zastąpić wywołaniami metod OcrInput. Korygowanie przekrzywienia, usuwanie szumów, wzmacnianie kontrastu, binaryzacja i normalizacja rozdzielczości to operacje wykonywane w jednej linii. Zespoły, które poświęciły 20-40 godzin na budowę i dostrajanie jednej ścieżki przetwarzania System.Drawing, mogą ją zastąpić pięcioma wywołaniami metod i przekierować ten wysiłek w inne miejsce. Pełny katalog filtrów można znaleźć w przeglądzie funkcji przetwarzania wstępnego.

Wbudowana obsługa plików PDF eliminuje klasę zależności. Biblioteki renderowania plików PDF dodane wyłącznie w celu wypełnienia luki w obsłudze plików PDF w Patagames zostały wyeliminowane. System OCR w produkcji, który wcześniej wymagał skoordynowania aktualizacji na trzech pakietach — Tesseract.Net.SDK, rendererze PDF i ich wspólnej zależności System.Drawing — teraz ma jeden pakiet OCR bez zależności łączących. Pliki PDF, w tym dokumenty chronione hasłem i wielostronicowe, są typem danych wejściowych pierwszej klasy. Dla przypadków użycia związanego z przestrzeganiem przepisów i zarządzaniem zapisami, result.SaveAsSearchablePdf() produkuje wyjście PDF z warstwą tekstową w jednym wywołaniu bez dodatkowych bibliotek.

Przezroczyste ceny i wsparcie komercyjne. Wieczysta licencja Lite IronOCR pokrywa jednego dewelopera i jedno miejsce wdrażania z rokiem aktualizacji wliczonym. Ceny są jawne, struktura poziomów jest przejrzysta, a wsparcie techniczne jest dostępne bez konieczności zawierania umowy Enterprise. Zespoły, które płaciły stawki Patagames za opakowanie Tesseract przeznaczone wyłącznie dla systemu Windows, zyskują wdrożenie wielopłatformowe, przetwarzanie wstępne, obsługę plików PDF oraz ponad 125 języków — przechodząc jednocześnie na model cenowy, w którym koszt jest znany przed zakończeniem oceny. Pełne informacje na temat poziomów licencji można znaleźć w sekcji Licencjonowanie IronOCR, a bezpłatną licencję próbną — na stronie produktu IronOCR.