RapidOCR ネイティブ DLL アダプタ

HPDFRapidOCRRecognition は、HotPDFRapidOCR.dll をバックエンドとするインプロセスの IHPDFOCREngine を公開します。公開 API は Delphi、C++Builder、Windows 版 FPC/Lazarus の Win32 / Win64 ビルドで共通です

この DLL はメモリスナップショットに対して直接 CPU ONNX 推論を実行し、初期化済みモデルをエンジンインターフェースが解放されるまで保持します。ランタイムの配置に必要なのは、対応するネイティブ DLL と互換性のあるローカルモデル・辞書だけです

従来の Python プロセスアダプタも、元のファクトリオーバーロードのまま引き続き利用できます

ファクトリとオプション

function HPDFCreateRapidOCRDLLOCREngine(const LibraryPath,
  ModelDirectory: string): IHPDFOCREngine; overload;
function HPDFCreateRapidOCRDLLOCREngine(const LibraryPath,
  ModelDirectory: string; const Options: THPDFRapidOCRDLLOptions): IHPDFOCREngine; overload;

THPDFRapidOCRDLLOptions = record
  DetectionModel: string;
  RecognitionModel: string;
  ClassificationModel: string;
  CharacterDictionary: string;
  UseAngleClassifier: Boolean;
  RightToLeft: Boolean;
  Threads: Integer;
  MaxPixels: Integer;
  TimeoutMilliseconds: Cardinal;
  class function Default: THPDFRapidOCRDLLOptions; static;
  class function ForLanguage(const Language: string): THPDFRapidOCRDLLOptions; static;
end;

オプションは THPDFRapidOCRDLLOptions.Default で初期化します。既定値は次のローカルファイルを使用します

相対ファイル名は ModelDirectory 基準で解決され、絶対パスなら別途用意したファイルを選択できます

ファクトリはモデルの初期化前に、ファイルの存在・オプション・必要なエクスポート・ABI バージョンを検証します。不正な設定では EArgumentException、モデルのロード失敗ではネイティブの診断情報付き EInvalidOperation が発生します

モデルの初期化はファクトリ内で行われ、認識デッドラインの対象外です。辞書のクラス数は認識モデルと一致しなければならず、クラス数が同じだからといって文字順や前処理に互換性があるとは限りません

同梱のパイプラインは、最大検出辺 1,024 ピクセル・白パディング 50 ピクセルの DB 検出を使用します。認識器は入力の高さが 32 または 48 で固定された互換 NCHW モデルを受け入れ、動的高さの場合は 48 を使用します

動的幅モデルでは認識時にアスペクト比を維持し、パディング済み入力は最小幅 320 で正規化します。固定幅モデルではリサイズ後のクロップ幅に上限が付き、長いテキスト行が圧縮されることがあります

角度分類は、モデル入力幅の範囲でクロップのアスペクト比を維持し、余ったピクセルを正規化したゼロで埋めます。クロップが 180 度回転されるのは、逆さま判定のスコアが 0.9 を超えたときだけです。これにより、弱い方向予測で短いテキストが反転されるのを防ぎます

辞書はモデルの文字順と出力クラス数に一致しなければなりません。CRLF の辞書行末は受け入れますが、UTF-8 BOM は拒否されます

モデルが文字メタデータを埋め込んでいる場合、ファクトリは辞書の全エントリとその順序も検証します。辞書サイズの一致だけでは不十分です

中国語・ロシア語と主要言語

THPDFRapidOCRDLLOptions.ForLanguage は、共有の検出器・分類器・スレッド・ピクセル・タイムアウトの既定値を保ったまま、ローカルモデルディレクトリ以下から認識モデルと対応する辞書を選択します

このメソッドは大文字小文字を区別しない言語エイリアスを受け入れ、アンダースコアをハイフンに置き換え、前後の空白を除去します。空または未対応のタグは、モデルのロード前に EArgumentException を発生させます

すべてのプロファイルは <profile>/recognition.onnx と <profile>/dictionary.txt を使用します。プロファイル名はそのまま指定でき、受け付けられる地域エイリアスは任意の接頭辞からの推測ではなく、明示的に定義されています

選択したモデルセットは、デプロイ前に SHA256 固定のプロビジョニングヘルパーでインストールしてください

& tools/Install-RapidOCRModels.ps1 `
  -Destination C:/OCR/models `
  -Language ch,chinese_cht,en,latin,japan,korean,cyrillic,arabic,devanagari

-Language All は 9 つのプロファイルをすべてインストールします。-SkipClassifier は省略可能な分類器を省きます。その場合はエンジン作成時に UseAngleClassifier := False を設定してください

ヘルパーは固定された SHA256 ハッシュを検証し、Default が使用するルートファイル名で共有の多言語検出器と分類器をインストールします。認識はオフラインで実行され、欠けたモデルを自動ダウンロードすることはありません

エンジンの言語はページや領域ごとに選択してください。1 つのエンジンが言語を自動判定したり、異なる文字体系向けの認識器を組み合わせたりすることはありません

固定されたパッケージは互換性のある PP-OCRv3 / PP-OCRv4 モデルを使用します。認識精度はモデル・フォント・解像度・クロップに依存し、ラテン系モデルは入力がきれいでも ñ のようなアクセント記号を誤認することがあります

より新しい PP-OCRv5 モデルは、DLL のビルドに使われた静的ライブラリよりも新しい ONNX Runtime を要求することがあります。未対応のモデル形式は、診断情報とともに初期化失敗となります

検出モデルは、リサイズ後の入力解像度で 1 つの float32 画像テンソルを受け付け、形状 [1, 1, H, W] の float32 確率マップを出力しなければなりません。互換性のない型や次元、非有限値、[0, 1] を float32 の機械イプシロン 4 つ分以上外れる確率は、検出結果を使用する前に診断付きで失敗します

この許容範囲内の小さな sigmoid の丸め誤差は、しきい値処理と輪郭スコアリングの前に [0, 1] にクランプされます。正常なモデルが従来どおりの検出挙動を保てるようにするためです

中国語の例

uses SysUtils, HPDFDoc, HPDFRapidOCRRecognition;

procedure AddNativeRapidOCRText(PDF: THotPDF);
var
  Engine: IHPDFOCREngine;
  Models: THPDFRapidOCRDLLOptions;
  Layer: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  Models := THPDFRapidOCRDLLOptions.ForLanguage('zh-CN');
  Models.UseAngleClassifier := False;
  Engine := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
  Layer := THPDFOCRTextLayerOptions.Default;
  if not PDF.ApplyLoadedOCRTextLayer([0], Engine, Layer, Info) then
    raise Exception.Create('Native RapidOCR text layer was not added');
end;

モデルを再利用するには、リクエストをまたいでエンジンインターフェースを保持してください。DLL は呼び出し側アプリケーションのアーキテクチャに一致するものを使い、依存 DLL はその隣か標準の Windows ローダーディレクトリに置いてください

ロシア語の例

procedure AddRussianRapidOCRText(PDF: THotPDF);
var
  Engine: IHPDFOCREngine;
  Models: THPDFRapidOCRDLLOptions;
  Layer: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  Models := THPDFRapidOCRDLLOptions.ForLanguage('ru-RU');
  Engine := HPDFCreateRapidOCRDLLOCREngine(
    'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
  Layer := THPDFOCRTextLayerOptions.Default;
  if not PDF.ApplyLoadedOCRTextLayer([0], Engine, Layer, Info) then
    raise Exception.Create('Russian RapidOCR text layer was not added');
end;

ru、ru-RU、rus はすべて同じ cyrillic の認識モデルと辞書を選択します

結果とライフタイム

アダプタは現在のビットマップを独立したトップダウン BGR スナップショットにコピーします。割り当て前に寸法とピクセル予算を確認し、借用したビットマップを変更することはありません

ネイティブパイプラインは、認識したテキスト行ごとに 1 つの結果を、元画像ピクセル単位の境界と平均文字 confidence 付きで出力します。各行は MaxWords スロットを 1 つ消費し、ネイティブのベースラインは供給されません

検出ボックスは水平行の読み順に従います。既定では左から右、RightToLeft 有効時は右から左です。アラビア語プリセットはこのオプションを有効にします

角度分類が補正するのは個々のテキストクロップです。ページ全体の向きを判定したり、逆さまのページで別々に検出されたボックスを論理的な読み順へ並べ替えたりすることはありません

認識テキストはモデルの論理的な Unicode 順のままです。アダプタがアラビア語文字列を自動で反転したり、双方向のシェーピングを適用したりすることはありません

アダプタは UTF-8・Unicode 制御文字・境界・confidence・リクエストの MaxTextCodeUnits 上限を検証します。テキストのハード上限は 1,048,576 UTF-16 単位で、サロゲート文字は 2 単位消費します

空のページは空の結果配列で成功します。失敗時には部分的な結果がクリアされ、検索可能 PDF の公開は既存の原子的ページトランザクション動作をそのまま保ちます

同じエンジンへの呼び出しは直列化されます。エンジンロックの待機中は、25 ミリ秒ごとにキャンセルと認識デッドラインを確認します

ネイティブのコールバックは、検出・分類・認識行ごとの前後でキャンセルとデッドラインを確認します。個々の ONNX 推論呼び出しを強制的に中断することはできないため、キャンセルは現在のステージ完了後に反映されることがあります

入力とテキストの上限はアダプタの割り当てと受け入れる出力を制約しますが、モデル・検出・クロップ・推論のメモリに対するハード上限ではありません

ビルドと ABI

Native/RapidOCR には、C++ ブリッジ・互換モデル認識器・バージョン付き C ヘッダー・エクスポート定義・CMake プロジェクトが含まれます。DbNet、AngleNet、OcrUtils を公開する互換 CPU ネットワークソースと、対応する ONNX Runtime・OpenCV ライブラリを用意してください

ビルドには C++17 対応の Windows MSVC、Windows SDK、CMake 3.20 以降を使用します。既定のビルドは静的リリース CRT を使うため、用意したライブラリと一致していなければなりません

& tools/Build-HotPDFRapidOCR.ps1 `
  -NativeSourceDirectory C:/OCR/native-sources `
  -OnnxRuntimeDirectory C:/OCR/onnxruntime/windows-x64 `
  -OpenCVDirectory C:/OCR/opencv/x64/vc16/staticlib `
  -Platform Win64

OnnxRuntimeDirectory には OnnxRuntimeConfig.cmake が必要で、OpenCVDirectory はアーキテクチャ固有のライブラリ設定を指す必要があります。32 ビット DLL には Win32 と一致する x86 ライブラリを選択してください

ビルドヘルパーは Lib/Native/RapidOCR/<Platform>/HotPDFRapidOCR.dll を書き出します。-BuildDirectory、-OutputDirectory、-Generator でビルド出力先と Visual Studio ジェネレーターを変更できます

ブリッジは C++ 例外を内包し、ABI バージョン 1 を HPDFRapidOCRAbiVersion、HPDFRapidOCRCreate、HPDFRapidOCRRecognize、HPDFRapidOCRDestroy として公開します。いずれも cdecl 呼び出し規約・32 ビットのステータス値・明示的な UTF-8 バイト長を使用します

ABI バージョン 1 は省略可能な HPDFRapidOCRSetReadingDirection エクスポートも定義します。アダプタがこれを要求するのは RightToLeft 有効時だけで、既存の DLL でも左から右へのリクエストは処理できます

コールバックがテキストを借用するのはその呼び出しの間だけです。アダプタは検証済みテキストを返す前にコピーし、エンジンのデストラクタは DLL のアンロード前にモデルを破棄します

検証

Python の onnx パッケージとネイティブの BUILD_TESTING ビルドがあれば、python tools/test_rapidocr_detector.py <build>/Release/NativeDetectorTests.exe を実行して、DLL ABI 経由で正常な空出力、不正なテンソルランク、チャンネルと型、空間次元の不一致、不正な確率をチェックできます。ランナーのパスを複数渡せば、1 回の実行で両アーキテクチャを検証できます

Delphi または FPC のアダプタランナーに -RapidOCRLanguageModelDirectory とネイティブ DLL のライブラリパラメータを 1 つまたは両方追加すると、中国語・ロシア語・日本語・韓国語・主要ラテン系言語・アラビア語・ヒンディー語のサンプルで、インストール済みの全プリセットを検証できます。ロシア語と繁体字中国語では、さらに検索可能 PDF の保存・再読み込み・テキスト抽出・ピクセル比較も行われます

Delphi / FPC アダプタランナーは、モデルの永続ライフタイム・BGR 行レイアウト・Unicode とサロゲート文字・ABI チェック・不正な結果・予算・協調的キャンセル・直列化されたロック待ち・後始末をテストします

実モデルの検証・空ページ・破損モデルの扱い・英語と中国語の認識・レンダリング結果が変わらない検索可能 PDF のラウンドトリップには、Tests/Delphi/Run-TesseractRecognitionTests.ps1 または Tests/Delphi/Run-TesseractFPCRecognitionTests.ps1 に -RapidOCRNativeWin32Library、-RapidOCRNativeWin64Library、-RapidOCRNativeModelDirectory を指定してください

ページレンダリング・Unicode PDF テキストマッピング・オプショナルコンテンツのグループ化・適合上の制約については、検索可能な OCR テキストレイヤーを参照してください