技術記事

HotPDF Tesseract DLL OCR:Delphi から C API を呼ぶ

インプロセスの Tesseract 呼び出しに 5,000 ms の認識タイムアウトを設定しても、5 秒後に呼び出しが返ってくる意味にはなりません。大きな多言語モデルセットでは、呼び出しスレッドはその刻限をはるかに過ぎてもネイティブライブラリーの中にとどまれます。デッドラインを強制するプログレスモニターは単語認識の最中にポーリングされるのであり、モデルのロードもページレイアウト解析も最初のポーリングの前に起きるからです。この隙間と、C の戻り値型が 1 バイトのキャンセルコールバックと、絶対に解放してはいけないメモリーを渡してくるイテレーターが、Tesseract C API を Delphi に結合する本当の仕事です。あとは配管です

Tesseract DLL を HotPDF のテキストレイヤーに繋ぐ

HotPDF はインプロセス経路を、HPDFTesseractRecognition ユニットの HPDFCreateTesseractDLLOCREngine として公開します。ファクトリーは C API をエクスポートする Tesseract DLL をロードし、TessBaseAPIInit2、TessBaseAPIRecognize、結果イテレーターを駆動して、IHPDFOCREngine を返します。THotPDF.ApplyLoadedOCRTextLayer がそのエンジンを受け取り、スキャンページに不可視で検索可能な Unicode テキストレイヤーを追加します。HotPDF の全 OCR エンジンが通るのと同じ呼び出しです

ファクトリーは前向きに検証します。DLL ファイルと tessdata ディレクトリーが存在すること。言語識別子には ASCII の英字、数字、_、+ しか入れられず、chi_sim+eng のような組み合わせの各モデルには対応する .traineddata ファイルが必要です。21 個の必須エクスポートすべてが解決して、ようやくエンジンが返ってきます。設定エラーは EArgumentException を上げ、欠けたエクスポートやモデルは名前で報告されます。ロードできない DLL は、Windows エラーコードと、アーキテクチャーと依存物を確認せよというヒントを運ぶ EOSError を上げます

uses
  SysUtils, HPDFDoc, HPDFTesseractRecognition;

procedure MakeSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // Win64 アプリケーションには 64 ビット DLL が必要。ファイル名はビルドにより異なり、
  // 依存 DLL は同じフォルダーに置く
  Engine := HPDFCreateTesseractDLLOCREngine('C:\OCR\Win64\libtesseract.dll',
    'C:\OCR\tessdata', 'chi_sim+eng');   // THPDFTesseractOptions.Default を使用
  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
    // 空のページリストは全ページの意味。テキストを既に持つページはスキップされる
    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 を tpsAuto、EngineMode を temDefault、TimeoutMilliseconds を 60,000、MaxPixels を 16,777,216 に設定します。このピクセル予算は人が思うより早く効いてきます。デフォルトの 300 DPI での US Letter ページは 2,550 × 3,300 ピクセル、およそ 840 万にレンダリングされ、収まります。同じページを 600 DPI に上げると 5,100 × 6,600、約 3,370 万ピクセルになり、エンジンは Tesseract が画像を見る前に Invalid Tesseract DLL OCR request or pixel budget で拒否します。MaxPixels を上げるか(上限は 67,108,864)、300 DPI にとどまるかです。本文テキストには 300 DPI で十分で、各辺も 32,767 ピクセルで打ち切られます

DLL は LoadLibraryEx と、DLL 自身のフォルダーとデフォルトの安全なディレクトリーをカバーする検索フラグでロードされます。したがって Tesseract が依存するイメージライブラリーは隣に置けてよく、PATH に触れることもカレントディレクトリーに頼ることもありません。HotPDF は OCR ランタイムも言語モデルも同梱せず、ダウンロードもしません。両方ともあなたが調達します

tesseract.exe と比べて DLL 経路が変えるもの

同じ認識器には、BMP を書いて TSV を解析する外部 tesseract.exe アダプターからも辿り着けます。両アダプターは 1 つのテキストレイヤーパイプラインに供給するので、座標マッピング、信頼度フィルタリング、全か無かのコミットは同じに振る舞います。違うのはピクセルの入り方、単語の出てき方、認識器が変な振る舞いをしたときに何が起きるかです

観点tesseract.exe アダプターTesseract DLL アダプター
ファクトリーHPDFCreateTesseractOCREngineHPDFCreateTesseractDLLOCREngine
ピクセルの入力プライベートな一時ディレクトリーの BMP ファイルメモリー上の 8 ビットグレースケールバッファー
単語の出力単語レベルの TSV、64 MiB で打ち切り結果イテレーター、単語ごとの UTF-8
ベースラインTSV にはない。パイプラインが推定するTessPageIteratorBaseline から素通り
ページセグメンテーションとエンジンモードTHPDFTesseractOptions オーバーロード、--psm と --oem として送信THPDFTesseractOptions、TessBaseAPISetPageSegMode と TessBaseAPIInit2 へ送信
ピクセル予算オプションを渡したときの MaxPixels常に MaxPixels、加えて 1 辺 32,767 ピクセル
タイムアウトハード:子プロセスを終了させる協調的:Tesseract が気付く必要がある
クラッシュとメモリーの隔離独立したプロセスなし。あなたのアドレス空間を共有する

1 つの代償は DLL の側に残ります。各 Recognize 呼び出しは自分の API インスタンスを作り TessBaseAPIInit2 を走らせるので、言語モデルはページごとに初期化されます。ファイルキャッシュが再ロードの痛みを和らげるものの、大きな多言語モデルセットではページあたりの最大の固定コストであり続け、しかも認識デッドラインに請求されます。インプロセス RapidOCR DLL エンジンは正反対の選択をして、ONNX モデルをエンジンの生涯中メモリーに常駐させます。境界の問題(C ABI、借り物バッファー、中断できないネイティブ処理)は同じ一族ですが

ではどちらを本番に置くべきか。数百枚のスキャンを処理するデスクトップツールやバッチジョブには DLL が似合います。ページごとのプロセス起動がなく、ディスク上の一時ビットマップがなく、傾いた行への本当のベースラインが得られます。見知らぬ人から PDF を受け取る長時間稼働のサーバーは tesseract.exe にとどまるべきです。ネイティブのクラッシュや暴走した確保がそこでは 1 つの子プロセスを落とすだけで済み、あなたのサービスを落としません

なぜ Delphi は Tesseract のモニター構造体をコピーできないのか

Delphi が Tesseract のプログレスモニターを安全に写せないのは、ETEXT_DESC が Tesseract のビルド間で変わる内部フィールドを抱えているからです。1 つのヘッダーから手で翻訳したレコードは、キャンセルコールバックとデッドラインをそのヘッダーが使っていたオフセットに置きます。別のビルドに対して走らせると、Tesseract は今は別の意味を持つフィールドからあなたのコールバックポインターを読み出すか、デッドラインをまったく見つけられず、認識はただ最後まで走ります

そこで HotPDF アダプターはモニターをオペークなポインターとして扱い、エクスポートされた関数を通してだけ触ります。TessMonitorCreate、TessMonitorSetCancelThis、TessMonitorSetCancelFunc、TessMonitorSetDeadlineMSecs、TessMonitorDelete です。下のスケッチは HotPDF API ではなくあなた自身のバインディングコードであり、宣言はアダプターが GetProcAddress で解決するものと一致します

HotPDF Tesseract DLL のモニター扱いを示す図。バージョン依存の ETEXT_DESC レコードをコピーするとキャンセルコールバックとデッドラインが誤ったオフセットに置かれ黙って失敗します。HotPDF はモニターをオペークとして扱い、TessMonitorCreate、TessMonitorSetCancelThis、TessMonitorSetCancelFunc、TessMonitorSetDeadlineMSecs を駆動し、cdecl コールバックを例外フリーに保ちます
オペークなポインターと 5 つのエクスポートで契約はすべてです。コールバックはフラグと時計を読むだけの 1 バイト Boolean であり続けます
type
  // C: typedef bool (*TessCancelFunc)(void *cancel_this, int words);
  TTessCancelFunc = function(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
  TTessMonitorCreate = function: Pointer; cdecl;   // ETEXT_DESC*、決してデリファレンスしない
  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;

  // 自分のジョブ状態であり HotPDF の型ではない
  TOCRJob = record
    CancelRequested: Boolean;
    DeadlineTick: UInt64;
  end;
  POCRJob = ^TOCRJob;

function ShouldCancel(CancelThis: Pointer; Words: Integer): Boolean; cdecl;
begin
  // Tesseract のスタック上で走る:フラグと時計を読むだけで、raise しない
  Result := (CancelThis = nil) or POCRJob(CancelThis)^.CancelRequested or
    (GetTickCount64 >= POCRJob(CancelThis)^.DeadlineTick);
end;

// 使い方。関数ポインターは GetProcAddress で解決済み:
//   Monitor := MonitorCreate();
//   try
//     MonitorSetCancelThis(Monitor, @Job);
//     MonitorSetCancelFunc(Monitor, ShouldCancel);
//     MonitorSetDeadlineMSecs(Monitor, RemainingMs);
//     RC := BaseAPIRecognize(API, Monitor);
//   finally
//     MonitorDelete(Monitor);
//   end;

スケッチはコールバックを Boolean と型付けます。Delphi と Free Pascal の両方で 1 バイトであり、TessCancelFunc の C の bool と一致します。4 バイトの Windows BOOL と Delphi の LongBool は互換的に見えて別の型です。片側が 1 バイトを書きもう一方が 4 バイトを読むと、上位 3 バイトはレジスターが以前に保持していた何者かになり、false が true として届きます。TessPageIteratorBoundingBox は int を返し、Pascal 側では Integer と宣言します。API 全体に 1 つの規則を仮定するのでなく、戻り値ごとに C の型を読んでください

コールバックは決して raise もしません。Tesseract の C++ フレームを Delphi の例外がアンワインドするのは未定義動作です。HotPDF のコールバックはキャンセルトークンと単調な GetTickCount64 値だけを読み、アダプターは TessBaseAPIRecognize が返った後でその結果をキャンセルかタイムアウトの診断に変換します。この検査はネイティブの戻りコードが 0 か否かに関係なく走ります

Delphi 側が所有するネイティブポインターはどれか

HotPDF Tesseract DLL アダプターはリクエストごとに 3 つのネイティブオブジェクト(API インスタンス、モニター、結果イテレーター)を所有し、それ以外はすべて借り物です。各 Recognize 呼び出しは自分のセットを作り、finally ブロックの中で固定の順序——TessResultIteratorDelete、次に TessMonitorDelete、次に TessBaseAPIDelete——で解放します。エンジンインターフェースの解放は DLL に FreeLibrary を呼びます

Recognize 呼び出しごとの HotPDF Tesseract DLL オブジェクト所有を示す図。結果イテレーター、モニター、API インスタンスが所有され finally の中でこの順に解放され、TessResultIteratorGetPageIterator のページイテレーターは決して解放してはいけない借り物のビューであり、GetUTF8Text の文字列はコピーして TessDeleteText で返されます
所有するのは 3 つのオブジェクト、他はすべて借り物です。固定の順序で解放し、ページイテレーターを二重解放せず、アロケーターを混ぜません
  • TessResultIteratorGetPageIterator は新しいオブジェクトではなく結果イテレーターへのビューを返します。アダプターは TessPageIteratorBoundingBox と TessPageIteratorBaseline に使うだけで決して解放せず、これも解放すると同じメモリーを 2 回解放することになります
  • TessResultIteratorGetUTF8Text は DLL 自身のランタイムが確保した文字列を返します。アダプターはそれをデコードし、finally ブロックの中で TessDeleteText を通して返します。Pascal の FreeMem では間違ったヒープから解放することになるからです
  • 単語テキストはまず長さ検査付きの厳格な UTF-8 デコードを通ります。制御文字を含む単語、不正な UTF-8、画像の外のボックス、反転した矩形、0〜100 の外の信頼度はリクエストを失敗させます。アダプターは後付けで直したりしません
  • リクエストあたりのテキストは 1,048,576 UTF-16 コード単位で打ち切られ、単語数は ApplyLoadedOCRTextLayer がページごとに引き渡す予算に収まらなければなりません

信頼度は 0〜100 で届き、0〜1 へスケールされるので、THPDFOCRTextLayerOptions.MinimumConfidence はどのエンジンでも同じ意味を持ちます。Tesseract がベースラインを報告するときは両端が素通りし、縦書き寄りの単語ではボックス幅がテキスト高さとして使われます。ベースラインがないとき、テキストレイヤーパイプラインは幾何学的推定へフォールバックします。TSV 入力のときとまったく同じです

DLL に届く前に enum オプションを範囲検査する

ファクトリーは範囲検査の前に PageSegMode と EngineMode の生バイトを Integer へコピーします。コンパイラーは enum 変数が常に宣言済みの値を保持すると仮定する権利を持つため、enum に直接書いた Ord(X) > Ord(High(T)) のようなテストは定数 false へ折りたたまれかねません。これらの序数は素の整数として DLL へ届きます。THPDFTesseractPageSegMode は Tesseract のページセグメンテーション番号 0 から 13 に従い、THPDFTesseractEngineMode はエンジンモード番号 0 から 3 に従います。FillChar でクリアされたオプションレコード、ストリームから読まれたもの、C++Builder から整数キャストで詰められたものは、200 のようなバイトを運べます。コピーを検証すれば、それはファクトリー時点の EArgumentException に変わります。ファクトリーはさらに、単語を 1 つも返さない tpsOSDOnly と tpsAutoOnly を拒否し、tpsAutoOSD と tpsSparseTextOSD には osd.traineddata を要求します

認識タイムアウトが実際に保証するものとは

Tesseract DLL のタイムアウトは協調的です。HotPDF は自分の仕事を止めて Tesseract にも止まるよう頼めますが、ネイティブコードに強制的に返らせることはできません。時計は Recognize が始まったときに動き始めるので、グレースケール変換とモデル初期化は認識そのものと同じ予算から引かれます。アダプターは経過時間とキャンセルトークンを、グレースケール変換中は 64 行ごとに、初期化の後で、結果をたどる間は単語ごとの前に確認します。TessBaseAPIRecognize の直前には残りミリ秒を TessMonitorSetDeadlineMSecs へ渡します

隙間はネイティブ呼び出しの内側にあります。Tesseract がモニターに相談するのは単語認識の最中だけなので、TessBaseAPIInit2 やページレイアウト解析の内側では、遅いモデルロードや病理的なレイアウトがタイムアウトの報告より先にデッドラインを走り抜けられます。ピクセルと出力の予算はネイティブライブラリー自身のメモリー使用量も上限化しません。丸ごと殺せるワーカーが必要なら、そのための道具はプロセスアダプターです

HotPDF Tesseract DLL の協調的タイムアウトの解剖を示す図。時計は Recognize の開始とともに動き始めグレースケール変換、TessBaseAPIInit2、レイアウト解析をカバーしますが、モニターに相談されるのは単語認識の最中だけなので、モデルのロードやレイアウトは HotPDF が otlsEngineError や otlsCancelled を報告する前に走り過ぎられます
ここでのデッドラインは保証ではなく要求です。init とレイアウト解析は長く走れ、本当に殺せるワーカーにはプロセスアダプターが必要です

ページセグメンテーションは、扱いにくい入力で DLL アダプターが効果を発揮する場所です。散らばったフィールドを持つフォーム、ラベル、スキャンされた表は、存在しない段組みや段落を組み立てようとする自動セグメンテーションより tpsSparseText のほうがよく認識されがちです。下のタイムアウトはフォームページには短めで、それでもモデル初期化をカバーしなければなりません

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;  // 散らばったフィールド、段組みの組立てなし
  TessOptions.EngineMode := temLSTMOnly;     // tessdata に LSTM モデルが必要
  TessOptions.TimeoutMilliseconds := 20000;  // モデル初期化を含む
  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;

タイムアウトは診断に Tesseract DLL OCR timed out を載せた otlsEngineError として表面化します。THPDFOCRTextLayerOptions.CancellationToken で渡されたトークンは otlsCancelled として表面化します。どちらの場合も ApplyLoadedOCRTextLayer はコミットを始める前に選択された全ページを認識し終えるため、50 ページ中 40 ページでの失敗はロードされたドキュメントを寸分違わず元のままにします。tpsSingleLine、tpsSingleBlock、tpsSparseText はセグメンテーションだけを変えます。傾いたスキャンをまっすぐにはどれもしてくれません

Free Pascal と Lazarus:古いピクセルと消えた中国語

両方の Tesseract ファクトリーは、ターゲットアーキテクチャー向けに Lazarus パッケージを再ビルドすれば、Windows の Free Pascal と Lazarus の Win32 と Win64 ビルドで動きます。移植の全般はHotPDF on Free Pascal and Lazarus Win64 で扱っています。FPC の振る舞いが違うのは入力処理です

スキャンライン経由で書かれた LCL の TBitmap は、Windows ビットマップハンドルを更新しないまま生画像を更新でき、そのハンドルへの GetDIBits は古いピクセルを返します。症状は不可解です。ビットマップに直接描いたテキストは認識され、スキャンライン経由でレンダリングされたページは単語を 1 つも返しません。FPC では DLL アダプターは CreateIntfImage 経由でフォーマットを考慮したスナップショットを読み、生画像のピクセルフォーマットと行順を尊重します。Delphi ビルドはプライベートな 24 ビットコピー上の GetDIBits 経路を保ち、どちらのビルドも呼び出し元のビットマップを変更しません

tesseract.exe アダプターは別の問題に遭います。FPC の TStringList は ANSI 文字列を保存するため、デコード済みの UTF-8 TSV テキストを Lines.Text へ代入すると、システム ANSI コードページが表せない中国語や補助平面の文字が全部落ちます。FPC 経路は TSV を UTF-8 バイトのまま保持し、BOM をバイトレベルで剥ぎ、各単語を自分で UnicodeString へデコードします。DLL アダプターはこの問題に遭いません。各単語をイテレーターから直接デコードするからです

Tesseract DLL アダプターは、プロセスアダプターと組み込み OCR エンジンと並んで、Delphi、C++Builder、Free Pascal 向けの HotPDF に同梱されています。エディションとダウンロードは HotPDF Delphi PDF コンポーネントのページに一覧があります