Teknik Makale

HotPDF Tesseract DLL OCR: C API'yi Delphi'ye Bağlamak

Süreç içi bir Tesseract çağrısı üzerindeki 5.000 ms'lik recognition timeout'u, çağrının beş saniye sonra geri geleceği anlamına gelmez. Büyük bir çok dilli model setiyle çağıran thread, o sınırı hayli aşan sürelerde native kütüphanenin içinde kalabilir; çünkü deadline'ı zorunlu kılan progress monitor, kelimeler tanınırken poll edilir ve model yükleme ile sayfa düzeni analizi ilk poll'den önce gerçekleşir. O boşluk, C dönüş tipi tek bayt olan bir cancel callback'i ve asla serbest bırakmamanız gereken bellek dağıtan bir iterator, Tesseract C API'sini Delphi'ye bağlamanın gerçek işidir. Gerisi tesisat işidir

Tesseract DLL'yi bir HotPDF metin katmanına bağlamak

HotPDF süreç içi yolu, HPDFTesseractRecognition unit'indeki HPDFCreateTesseractDLLOCREngine olarak açar. Factory, C API'sini export eden bir Tesseract DLL yükler, TessBaseAPIInit2, TessBaseAPIRecognize ve result iterator'ü sürer ve bir IHPDFOCREngine döndürür. THotPDF.ApplyLoadedOCRTextLayer o engine'i alır ve taranmış sayfalara görünmez, aranabilir bir Unicode metin katmanı ekler; her HotPDF OCR engine'inin geçtiği çağrının aynısıdır

Factory her şeyi en başta doğrular. DLL dosyası ile tessdata dizini var olmalıdır. Dil tanımlayıcısı yalnızca ASCII harfleri, rakamları, _ ve + içerebilir ve chi_sim+eng gibi bir kombinasyondaki her model, eşleşen bir .traineddata dosyası ister. Size bir engine dönmeden önce 21 zorunlu export'un tümü çözümlenmiş olmalıdır. Yapılandırma hataları EArgumentException fırlatır; eksik export ya da model adıyla bildirilir. Yüklenmeyen bir DLL, Windows hata kodunu ve mimari ile bağımlılıkları kontrol etme ipucunu taşıyan EOSError fırlatır

uses
  SysUtils, HPDFDoc, HPDFTesseractRecognition;

procedure MakeSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // Bir Win64 uygulaması 64 bitlik DLL ister; dosya adı build'inize bağlıdır,
  // bağımlılık DLL'leri de aynı klasöre gider
  Engine := HPDFCreateTesseractDLLOCREngine('C:\OCR\Win64\libtesseract.dll',
    'C:\OCR\tessdata', 'chi_sim+eng');   // THPDFTesseractOptions.Default kullanır
  Doc := THotPDF.Create(nil);
  try
    Doc.AutoLaunch := False;
    if Doc.LoadFromFile(SourceFile) < 1 then
      raise Exception.Create('Cannot load ' + SourceFile);
    Options := THPDFOCRTextLayerOptions.Default;   // 300 DPI, MinimumConfidence 0.5
    // Boş sayfa listesi her sayfa demektir; zaten metin taşıyan sayfalar atlanır
    if not Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info) then
      raise Exception.Create(string(Info.Diagnostic));
    Writeln(string(Info.EngineName), ': ', Info.AcceptedWordCount,
      ' words accepted, ', Info.DroppedWordCount, ' dropped');
    Doc.SaveLoadedDocument(TargetFile);
  finally
    Doc.Free;
  end;
end;

THPDFTesseractOptions.Default; PageSegMode'i tpsAuto'ya, EngineMode'u temDefault'a, TimeoutMilliseconds'i 60.000'e ve MaxPixels'i 16.777.216'ye set eder. O piksel bütçesi, insanların beklediğinden erken ısırır. Varsayılan 300 DPI'da bir US Letter sayfası 2.550 × 3.300 piksele render olur, kabaca 8,4 milyon, ve sığar. Aynı sayfayı 600 DPI'ya çıkardığınızı düşünün: 5.100 × 6.600 olur, yaklaşık 33,7 milyon piksel; engine, görüntü Tesseract'a ulaşmadan Invalid Tesseract DLL OCR request or pixel budget ile reddeder. Ya MaxPixels'i yükseltin (tavan 67.108.864) ya da 300 DPI'da kalın; gövde metni için fazlasıyla yeterlidir. Her kenar ayrıca 32.767 piksele sınırlıdır

DLL, LoadLibraryEx ile ve DLL'in kendi klasörünü artı varsayılan güvenli dizinleri kapsayan arama bayraklarıyla yüklenir. Böylece Tesseract'ın bağımlandığı image kütüphaneleri yanında durabilir ve PATH'e dokunmanıza ya da geçerli dizine bel bağlamanıza gerek kalmaz. HotPDF bir OCR runtime'ını ya da herhangi bir dil modelini paketlemez, indirmiyor da; ikisini siz sağlarsınız

DLL yolu, tesseract.exe'ye kıyasla neyi değiştirir?

Aynı tanıyıcıya BMP yazıp TSV ayrıştıran harici tesseract.exe adaptörü üzerinden de ulaşılır. İki adaptör de tek metin katmanı hattını besler; koordinat eşleme, confidence filtresi ve ya hep ya hiç commit aynı davranır. Farklı olan, piksellerin nasıl girdiği, kelimelerin nasıl çıktığı ve tanıyıcı kötü davrandığında ne olduğudur

Yöntesseract.exe adaptörüTesseract DLL adaptörü
FabrikaHPDFCreateTesseractOCREngineHPDFCreateTesseractDLLOCREngine
Pikseller girişteÖzel geçici bir dizinde BMP dosyasıBellekte 8 bitlik gri tonlama tamponu
Kelimeler çıkıştaKelime düzeyi TSV, 64 MiB tavanlıResult iterator, kelime başına UTF-8
Taban çizgileriTSV'de yok; hattın tahmin ederTessPageIteratorBaseline'dan aynen geçirilir
Sayfa bölümlendirme ve engine moduTHPDFTesseractOptions overload'u, --psm ve --oem olarak gönderilirTHPDFTesseractOptions, TessBaseAPISetPageSegMode ile TessBaseAPIInit2'ye gönderilir
Piksel bütçesiOptionlar geçildiğinde MaxPixelsDaima MaxPixels, artı kenar başına 32.767 piksel
Zaman aşımıSert: child process sonlandırılırİşbirlikçi: Tesseract'ın fark etmesi gerekir
Çökme ve bellek yalıtımıAyrı processYok, adres alanınızı paylaşır

Tek maliyet DLL'de kalır. Her Recognize çağrısı kendi API örneğini kurar ve TessBaseAPIInit2 çalıştırır; dil modelleri böylece her sayfa için ilklendirilir. Dosya önbelleği yeniden yüklemenin ucunu törpüler, yine de büyük bir çok dilli model setiyle sayfa başına en büyük sabit maliyet olmayı sürdürür ve recognition deadline'ına yazılır. Süreç içi RapidOCR DLL engine'i tam tersini seçer ve ONNX modellerini engine'in ömrü boyunca bellekte tutar; sınır problemleri (C ABI, ödünç tamponlar, kesintiye uğratamayacağınız native iş) ise aynı ailedendir

Peki hangisi üretime girer? Birkaç yüz taramayla uğraşan bir masaüstü aracı ya da toplu iş için DLL daha uygundur: sayfa başına process başlatma yok, diskte geçici bitmap yok ve eğik satırlar için gerçek taban çizgileri var. Yabancılardan PDF kabul eden uzun ömürlü bir sunucu tesseract.exe'de kalmalı; çünkü oradaki bir native çökme ya da kontrolden çıkan ayırma, service'inizi değil tek bir child process götürür

Delphi Tesseract monitor yapısını neden kopyalayamaz?

Delphi, Tesseract'ın progress monitor'ünü güvenle aynalayamaz; çünkü ETEXT_DESC, Tesseract build'leri arasında değişen dâhilî alanlar taşır. Bir header'dan elle çevrilmiş bir record, cancel callback'ini ile deadline'ı o header'ın kullandığı ofsetlere koyar. Farklı bir build'e karşı çalıştırın ve Tesseract ya callback pointer'ınızı artık başka bir şey ifade eden bir alandan okur ya da deadline'ı hiç bulamaz; recognition da sonuna kadar koşar gider

HotPDF adaptörü bu yüzden monitor'ü opak bir pointer olarak görür ve ona yalnızca export edilen fonksiyonlar üzerinden dokunur: TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc, TessMonitorSetDeadlineMSecs ve TessMonitorDelete. Aşağıdaki taslak HotPDF API'si değil sizin kendi binding kodunuzdur; bildirimleri, adaptörün GetProcAddress ile çözdükleriyle uyuşur

HotPDF Tesseract DLL monitor yönetimi: sürüme bağlı ETEXT_DESC record'unu kopyalamak cancel callback'ini ile deadline'ı yanlış ofsetlere koyar ve sessizce başarısız olur; HotPDF ise monitor'ü opak görür, TessMonitorCreate, TessMonitorSetCancelThis, TessMonitorSetCancelFunc ve TessMonitorSetDeadlineMSecs'i sürer ve cdecl callback'ini istisnasız tutar
Opak bir pointer artı beş export bütün sözleşmedir; callback, yalnızca bir bayrak ve bir saat okuyan tek baytlık Boolean olarak kalır
type
  // C: typedef bool (*TessCancelFunc)(void *cancel_this, int words);
  TTessCancelFunc = function(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
  TTessMonitorCreate = function: Pointer; cdecl;   // ETEXT_DESC*, asla dereference edilmez
  TTessMonitorDelete = procedure(Monitor: Pointer); cdecl;
  TTessMonitorSetCancelFunc = procedure(Monitor: Pointer; Func: TTessCancelFunc); cdecl;
  TTessMonitorSetCancelThis = procedure(Monitor, CancelThis: Pointer); cdecl;
  TTessMonitorSetDeadlineMSecs = procedure(Monitor: Pointer; MSecs: Integer); cdecl;
  TTessBaseAPIRecognize = function(Handle, Monitor: Pointer): Integer; cdecl;

  // Kendi iş durumunuz, HotPDF tipi değil
  TOCRJob = record
    CancelRequested: Boolean;
    DeadlineTick: UInt64;
  end;
  POCRJob = ^TOCRJob;

function ShouldCancel(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
begin
  // Tesseract'ın stack'inde çalışır: bir bayrak ve saati okur, asla raise etmez
  Result := (CancelThis = nil) or POCRJob(CancelThis)^.CancelRequested or
    (GetTickCount64 >= POCRJob(CancelThis)^.DeadlineTick);
end;

// Kullanım; fonksiyon pointer'ları GetProcAddress ile çözülür:
//   Monitor := MonitorCreate();
//   try
//     MonitorSetCancelThis(Monitor, @Job);
//     MonitorSetCancelFunc(Monitor, ShouldCancel);
//     MonitorSetDeadlineMSecs(Monitor, RemainingMs);
//     RC := BaseAPIRecognize(API, Monitor);
//   finally
//     MonitorDelete(Monitor);
//   end;

Taslak, callback'i Boolean olarak tipler; Delphi'de de Free Pascal'da da tek bayttır ve TessCancelFunc'teki C bool ile uyuşur. Dört baytlık Windows BOOL ile Delphi LongBool birbirinin yerine geçiyormuş gibi görünür ama farklı tiptir: bir taraf tek bayt yazıp öteki dört bayt okuduğunda üst üç bayt, register'ın daha önce tuttuğu her ne ise odur ve false, true olarak gelebilir. TessPageIteratorBoundingBox bir int döndürür; Pascal tarafında Integer olarak bildirilir. Tüm API için tek bir kural varsaymak yerine her dönüş değerinin C tipini okuyun

Callback ayrıca asla raise etmez. Delphi istisnasının Tesseract'ın C++ çerçevelerinden geriye sarılması tanımsız davranıştır. HotPDF callback'i yalnızca cancellation token'ı ve monotonik bir GetTickCount64 değeri okur; adaptör sonucu, TessBaseAPIRecognize döndükten sonra bir iptal ya da zaman aşımı tanısına çevirir. Bu kontrolü, native dönüş kodu 0 olmasa da çalıştırır

Delphi tarafı hangi native işaretçilere sahiptir?

HotPDF Tesseract DLL adaptörü istek başına üç native object'e sahiptir (API örneği, monitor ve result iterator) ve gerisini ödünç alır. Her Recognize çağrısı kendi setini kurar ve sabit bir sırada bir finally bloğunda bırakır: önce TessResultIteratorDelete, sonra TessMonitorDelete, sonra TessBaseAPIDelete. Engine arayüzünü bırakmak, DLL üzerinde FreeLibrary çağırır

Recognize çağrısı başına HotPDF Tesseract DLL object sahipliği: result iterator, monitor ve API örneği o sırayla finally içinde sahiplenilip bırakılır; TessResultIteratorGetPageIterator'dan gelen page iterator, asla bırakılmaması gereken ödünç bir görünümdür; GetUTF8Text string'leri kopyalanır ve TessDeleteText ile geri verilir
Üç object sahiplenilir, gerisi ödünçtir: sabit sırada bırakın, page iterator'ü asla iki kez bırakmayın, ayırıcıları asla karıştırmayın
  • TessResultIteratorGetPageIterator yeni bir object değil, result iterator içine bir görünüm döndürür. Adaptör onu TessPageIteratorBoundingBox ve TessPageIteratorBaseline için kullanır ve asla bırakmaz; onu da silmek aynı belleği iki kez serbest bırakır
  • TessResultIteratorGetUTF8Text, DLL'in kendi runtime'ının ayırdığı bir string döndürür. Adaptör onu decode eder ve finally bloğunda TessDeleteText ile geri verir; Pascal FreeMem'i yanlış heap'te serbest bırakırdı
  • Kelime metni, önce uzunluk kontrolüyle sıkı UTF-8 decodinginden geçer. Kontrol karakterli, bozuk UTF-8'li, görüntü dışında kutusu olan, ters çevrilmiş dikdörtgenli ya da confidence'ı 0–100 dışında olan bir kelime isteği düşürür; adaptör onu yamamaz
  • İstek başına metin 1.048.576 UTF-16 code unit ile sınırlıdır ve kelime sayısı, ApplyLoadedOCRTextLayer'ın her sayfayla aşağı geçtiği bütçeye sığmalıdır

Confidence 0–100 olarak gelir ve 0–1'e ölçeklenir; böylece THPDFOCRTextLayerOptions.MinimumConfidence her engine için aynı anlama taşır. Tesseract bir taban çizgisi bildirdiğinde iki ucu da aynen geçirilir ve ağırlıklı dikey bir kelime için kutu genişliği metin yüksekliği olarak kullanılır. Taban çizgisi yoksa metin katmanı hattı, TSV girdisinde yaptığı gibi geometrik tahmine döner

Enum option'ları DLL'e ulaşmadan aralık kontrolünden geçirmek

Factory, PageSegMode ile EngineMode'un ham baytlarını aralık kontrolünden önce bir Integer'a kopyalar. Derleyici, enum değişkeninin daima bildirilmiş bir değer tuttuğunu varsayma hakkına sahiptir; enum'a doğrudan yazılmış Ord(X) > Ord(High(T)) gibi bir test, sabit false'a katlanabilir. O sıra numaraları DLL'e düz tamsayı olarak gider: THPDFTesseractPageSegMode, Tesseract'ın 0'dan 13'e sayfa bölümlendirme numaralandırmasını, THPDFTesseractEngineMode ise 0'dan 3'e engine modu numaralandırmasını izler. FillChar ile sıfırlanmış, bir stream'den okunmuş ya da C++Builder'dan integer cast'iyle doldurulmuş bir options record'u, 200 gibi bir bayt taşıyabilir; kopyayı doğrulamak bunu factory anında bir EArgumentException'ye çevirir. Factory ayrıca kelime döndürmeyen tpsOSDOnly ile tpsAutoOnly'yi reddeder ve tpsAutoOSD ile tpsSparseTextOSD için osd.traineddata ister

Tanıma zaman aşımı aslında neyi garanti eder?

Tesseract DLL zaman aşımı işbirlikçidir: HotPDF kendi işini durdurabilir ve Tesseract'a da durmasını söyleyebilir ama native kodu dönmeye zorlayamaz. Saat, Recognize başladığında işler; gri tonlama dönüşümü ile model initialization'ı, recognition ile aynı bütçeyi tüketir. Adaptör geçen süreyi ile cancellation token'ı, gri tonlama dönüşümü sırasında her 64 satırda bir, initialization'dan sonra ve sonuçları gezerken her kelimeden önce kontrol eder. TessBaseAPIRecognize'i çağırmadan hemen önce kalan milisaniyeleri TessMonitorSetDeadlineMSecs'e geçirir

Boşluk native çağrıların içindedir. Tesseract monitor'üne yalnızca kelime tanıma sırasında danışır; TessBaseAPIInit2 ya da sayfa düzeni analizi içinde yavaş bir model yüklemesi ya da patolojik bir düzen, zaman aşımı bildirilmeden deadline'ı aşabilir. Piksel ile çıktı bütçeleri de native kütüphanenin kendi bellek kullanımını sınırlamaz. Dışarıdan öldürebileceğiniz bir worker gerektiğinde doğru araç process adaptörüdür

HotPDF Tesseract DLL işbirlikçi zaman aşımı anatomisi: saat Recognize başladığında işler ve gri tonlama dönüşümünü, TessBaseAPIInit2'yi ile düzen analizini kapsar; ama monitor'üne yalnızca kelime tanıma sırasında danışılır, bu yüzden model yüklemeleri ile düzen, HotPDF otlsEngineError ya da otlsCancelled bildirmeden önce taşabilir
Buradaki deadline bir taleptir, garanti değil: init ile düzen analizi uzun sürebilir ve gerçekten öldürebileceğiniz bir worker process adaptörü ister

Sayfa bölümlendirme, DLL adaptörünün dağınık girdide kazandığı yerdir. Dağınık alanlı formlar, etiketler ve taranmış tablolar, olmayan sütunlar ve paragraflar kurmaya çalışan otomatik bölümlendirmeden çok tpsSparseText ile daha iyi tanınır. Aşağıdaki zaman aşımı bir form sayfası için kısa olur ve yine de model initialization'ını kapsamak zorundadır

procedure OCRFormPages(Doc: THotPDF; const Pages: array of Integer);
var
  Engine: IHPDFOCREngine;
  TessOptions: THPDFTesseractOptions;
  LayerOptions: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  TessOptions := THPDFTesseractOptions.Default;
  TessOptions.PageSegMode := tpsSparseText;  // dağınık alanlar, sütun kurulumu yok
  TessOptions.EngineMode := temLSTMOnly;     // tessdata'da LSTM modelleri ister
  TessOptions.TimeoutMilliseconds := 20000;  // model initialization'ını kapsar
  Engine := HPDFCreateTesseractDLLOCREngine('C:\OCR\Win64\libtesseract.dll',
    'C:\OCR\tessdata', 'eng+deu', TessOptions);

  LayerOptions := THPDFOCRTextLayerOptions.Default;
  LayerOptions.MinimumConfidence := 0.6;
  if not Doc.ApplyLoadedOCRTextLayer(Pages, Engine, LayerOptions, Info) then
    case Info.Status of
      otlsCancelled:
        Writeln('OCR cancelled, document unchanged');
      otlsEngineError:
        if Pos('timed out', string(Info.Diagnostic)) > 0 then
          Writeln('Tesseract timed out, document unchanged')
        else
          Writeln('Tesseract failed: ', string(Info.Diagnostic));
    else
      Writeln(string(Info.Diagnostic));
    end;
end;

Zaman aşımı, teşhiste Tesseract DLL OCR timed out ile otlsEngineError olarak yüzeye çıkar. THPDFOCRTextLayerOptions.CancellationToken üzerinden set edilen token otlsCancelled olarak çıkar. Her iki durumda da ApplyLoadedOCRTextLayer, commit'e başlamadan önce seçilen her sayfayı tanır; 50 sayfanın 40.'sındaki bir başarısızlık, yüklenmiş belgeyi tam olarak bırakıldığı yerde bırakır. tpsSingleLine, tpsSingleBlock ve tpsSparseText yalnızca bölümlendirmeyi değiştirir; hiçbiri eğik bir taramayı düzeltmez

Free Pascal ve Lazarus: bayat pixel'ler ve kaybolan Çince

Her iki Tesseract fabrikası da, Lazarus paketi hedef mimari için yeniden derlendikten sonra Windows Free Pascal ile Lazarus Win32 ve Win64 derlemelerinde çalışır; genel port Free Pascal ve Lazarus Win64'te HotPDF yazısında kapsanır. Girdi yönetimi, FPC'nin farklı davrandığı yerdir

Scanline'lar üzerinden yazılan bir LCL TBitmap, Windows bitmap handle'ını tazelemeden ham image'ini güncelleyebilir; o handle üzerindeki GetDIBits eski pikselleri döndürür. Belirti şaşırtır: doğrudan bitmap üzerine çizilen metin tanınır, scanline'lar üzerinden render edilen bir sayfa kelime üretmez. FPC altında DLL adaptörü, ham image'in pixel formatini ve satır sırasına saygı duyan format-farkında bir anlık görüntüyü CreateIntfImage üzerinden okur. Delphi derlemesi GetDIBits yolunu özel bir 24 bitlik kopya üzerinde tutar ve hiçbir derleme çağıranın bitmap'ini değiştirmez

tesseract.exe adaptörü başka bir problemle karşılaşır. FPC'nin TStringList'i ANSI string'ler tutar; decode edilmiş UTF-8 TSV metnini Lines.Text'e atamak, sistem ANSI code page'inin temsil edemediği her Çince ya da yardımcı düzlem karakterini düşürür. FPC yolu TSV'yi UTF-8 baytlar olarak tutar, BOM'u bayt düzeyinde kırpar ve her kelimeyi kendi başına UnicodeString'e decode eder. DLL adaptörü probleme hiç karşılaşmaz; her kelimeyi doğrudan iterator'den decode eder

Tesseract DLL adaptörü, Delphi, C++Builder ve Free Pascal için HotPDF içinde process adaptörleriyle ve yerleşik OCR engine'yle birlikte gelir. Sürümler ve indirmeler HotPDF Delphi PDF component sayfasında listelenir