Адаптер нативной DLL RapidOCR

HPDFRapidOCRRecognition открывает внутрипроцессный IHPDFOCREngine поверх HotPDFRapidOCR.dll с тем же публичным 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 с нативной диагностикой

Инициализация моделей происходит в фабрике и не входит в дедлайн распознавания; число классов словаря должно совпадать с моделью распознавания, а одно лишь совпадение числа классов ещё не гарантирует совместимого порядка символов или предобработки

Поставляемый конвейер использует детекцию DB с максимальной стороной детекции 1,024 пикселя и белым полем в 50 пикселей; распознаватель принимает совместимые NCHW-модели с фиксированной высотой входа 32 или 48, а для динамической высоты использует 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 устанавливает все девять профилей; -SkipClassifier пропускает опциональный классификатор — в этом случае при создании движка задайте UseAngleClassifier := False

Помощник сверяет зафиксированные SHA256-хэши и устанавливает общий многоязычный детектор и классификатор под корневыми именами файлов, которые использует Default; распознавание идёт офлайн и никогда не докачивает отсутствующие модели автоматически

Язык движка выбирайте для каждой страницы или области отдельно; один движок не определяет язык автоматически и не комбинирует отдельные распознаватели для разных письменностей

Зафиксированные пакеты используют совместимые модели PP-OCRv3 и PP-OCRv4; точность распознавания зависит от модели, шрифта, разрешения и фрагмента, а латинская модель может путать диакритику вроде ñ даже на чистом входе

Более новые модели PP-OCRv5 могут требовать более свежий ONNX Runtime, чем статические библиотеки, которыми собрана DLL; неподдерживаемый формат модели валит инициализацию с диагностикой

Модели детекции должны принимать один float32-тензор изображения и выдавать float32-карту вероятностей формы [1, 1, H, W] в разрешении масштабированного входа; несовместимые типы, размерности, нечисловые значения или вероятности вне [0, 1] больше чем на четыре машинных эпсилона float32 завершаются диагностикой до использования результатов детекции

Мелкие ошибки округления сигмоиды в пределах этого допуска прижимаются к [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 под архитектуру вызывающего приложения и кладите её зависимости рядом с ней или в стандартные каталоги загрузчика 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

Результаты и время жизни

Адаптер копирует текущий bitmap в независимый BGR-снимок с порядком строк сверху вниз; он проверяет размеры и бюджет пикселей до выделения памяти и не меняет одолженный bitmap

Нативный конвейер выдаёт один результат на распознанную текстовую строку — с границами в пикселях исходного изображения и средней уверенностью по символам; каждая строка занимает один слот MaxWords, а нативная базовая линия не передаётся

Найденные боксы следуют порядку чтения горизонтальных строк: по умолчанию слева направо, а при включённом RightToLeft — справа налево; пресет арабского включает эту опцию

Классификация угла корректирует отдельные текстовые фрагменты; она не определяет ориентацию всей страницы и не переставляет отдельные боксы детекции перевёрнутой страницы в логический порядок чтения

Распознанный текст остаётся в логическом Unicode-порядке модели; адаптер сам не разворачивает арабские строки и не применяет двунаправленный шейпинг

Адаптер валидирует UTF-8, управляющие символы Unicode, границы, уверенность и лимит MaxTextCodeUnits запроса с жёстким потолком текста в 1,048,576 единиц UTF-16; дополнительные символы расходуют по две единицы

Пустая страница завершается успешно с пустым массивом результатов; сбой очищает частичные результаты, а публикация PDF с поддержкой поиска сохраняет существующее атомарное поведение страничных транзакций

Вызовы одного движка сериализуются; ожидание блокировки движка каждые 25 миллисекунд проверяет отмену и дедлайн распознавания

Нативные callback-и проверяют отмену и дедлайны до и после детекции, классификации и каждой распознанной строки; отдельный вызов ONNX-инференса нельзя прервать принудительно, поэтому отмена может вернуться только после завершения текущей стадии

Лимиты входа и текста ограничивают выделения адаптера и принимаемый вывод, но не накладывают жёсткого потолка на память моделей, детекции, фрагментов или инференса

Сборка и ABI

Native/RapidOCR содержит C++-мост, совместимый распознаватель моделей, версионируемый C-заголовок, определение экспортов и CMake-проект; подготовьте совместимые исходники CPU-сетей с DbNet, AngleNet и OcrUtils, плюс соответствующие библиотеки ONNX Runtime и OpenCV

Собирайте Windows MSVC с C++17, Windows SDK и CMake 3.20 или новее; сборка по умолчанию использует статический release 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 по-прежнему обслуживают запросы слева направо

Callback-и одалживают свой текст только на время вызова; адаптер копирует провалидированный текст перед возвратом, а деструктор движка уничтожает модели до выгрузки DLL

Валидация

С Python-пакетом onnx и нативной сборкой с BUILD_TESTING запустите python tools/test_rapidocr_detector.py <build>/Release/NativeDetectorTests.exe, чтобы проверить корректный пустой вывод, неверные ранги, каналы и типы тензоров, несовпадающие пространственные размерности и неверные вероятности через ABI DLL; несколько путей раннера позволяют провалидировать обе архитектуры за один запуск

Добавьте -RapidOCRLanguageModelDirectory и один или оба параметра библиотеки нативной DLL в раннер адаптеров Delphi или FPC, чтобы провалидировать все установленные пресеты на образцах китайского, русского, японского, корейского, распространённых латинских языков, арабского и хинди; для русского и традиционного китайского дополнительно проверяются сохранение PDF с поддержкой поиска, перезагрузка, извлечение текста и сравнение пикселей

Раннеры адаптеров Delphi и FPC проверяют постоянное время жизни моделей, построчный BGR-расклад, Unicode и дополнительные символы, проверки ABI, невалидные результаты, бюджеты, кооперативную отмену, сериализованное ожидание блокировки и очистку

Передайте -RapidOCRNativeWin32Library, -RapidOCRNativeWin64Library и -RapidOCRNativeModelDirectory в Tests/Delphi/Run-TesseractRecognitionTests.ps1 или Tests/Delphi/Run-TesseractFPCRecognitionTests.ps1 для проверки на настоящих моделях, пустых страниц, обработки повреждённых моделей, распознавания английского и китайского и полного цикла PDF с поддержкой поиска без изменений отрисованных пикселей

Рендеринг страниц, отображение Unicode-текста в PDF, группировку в optional content и ограничения соответствия смотрите в разделе Текстовые слои OCR с поддержкой поиска