RapidOCR 네이티브 DLL 어댑터

HPDFRapidOCRRecognition은 HotPDFRapidOCR.dll이 뒤받는 in-process IHPDFOCREngine을 노출하며, Delphi, C++Builder, Windows FPC/Lazarus Win32 및 Win64 빌드에서 같은 public API를 씁니다

DLL은 메모리 스냅샷에 CPU ONNX 추론을 직접 수행하고 엔진 인터페이스가 해제될 때까지 초기화된 모델을 유지합니다. 런타임 배포는 짝이 맞는 네이티브 DLL과 호환되는 로컬 모델·사전으로 이뤄집니다

기존 Python 프로세스 어댑터는 원래 팩토리 overload 그대로 계속 사용할 수 있습니다

팩토리와 options

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;

options는 THPDFRapidOCRDLLOptions.Default로 초기화하며, 기본값은 다음 로컬 파일을 씁니다

상대 파일 이름은 ModelDirectory를 기준으로 해석되며, 절대 경로는 별도로 준비한 파일을 고를 수 있습니다

팩토리는 모델을 초기화하기 전에 파일 가용성, options, 필요한 export, ABI 버전을 검사합니다. 잘못된 구성은 EArgumentException을, 모델 로딩 실패는 네이티브 진단을 담은 EInvalidOperation을 발생시킵니다

모델 초기화는 팩토리에서 일어나며 인식 기한 밖입니다. 사전 클래스 수는 인식 모델과 맞아야 하고, 클래스 수만 같다고 문자 순서나 전처리가 호환되는 것은 아닙니다

제공되는 파이프라인은 최대 검측 변 1,024픽셀과 흰 패딩 50픽셀을 쓰는 DB detection입니다. 인식기는 입력 높이가 32나 48로 고정된 호환 NCHW 모델을 받아들이며, 동적 높이에는 48을 씁니다

인식은 동적 폭 모델의 종횡비를 유지하고, 패딩한 입력은 최소 폭 320으로 정규화합니다. 고정 폭 모델은 리사이즈된 crop 폭을 제한하므로 긴 텍스트 행이 눌릴 수 있습니다

angle classification은 모델 입력 폭 안에서 crop 종횡비를 유지하고 남는 픽셀을 정규화된 0으로 채웁니다. crop은 거꾸로 점수가 0.9를 넘을 때만 180도 회전하므로, 약한 방향 예측이 짧은 텍스트를 뒤집지 못합니다

사전은 모델의 문자 순서와 출력 클래스 수와 맞아야 합니다. CRLF 사전 줄바꿈은 받아들이지만 UTF-8 BOM은 거부합니다

모델이 문자 메타데이터를 내장하면 팩토리가 모든 사전 항목과 그 순서까지 검증합니다. 사전 크기만으로는 부족합니다

중국어, 러시아어, 주요 언어

THPDFRapidOCRDLLOptions.ForLanguage는 공유 검출기, 분류기, 스레드, 픽셀, timeout 기본값을 유지하면서 로컬 모델 디렉터리 아래에서 인식 모델과 짝이 맞는 사전을 고릅니다

이 메서드는 대소문자를 구분하지 않는 언어 별칭을 받고, 밑줄을 하이픈으로 바꾸며, 앞뒤 공백을 제거합니다. 빈 태그나 미지원 태그는 모델을 불러오기 전에 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 모델을 씁니다. 인식 정확도는 모델, 폰트, 해상도, crop에 좌우되며, 라틴 모델은 깨끗한 입력에서도 ñ 같은 악센트를 혼동할 수 있습니다

더 새로운 PP-OCRv5 모델은 DLL을 빌드한 정적 라이브러리보다 새 ONNX Runtime을 요구할 수 있습니다. 미지원 모델 형식은 진단을 남기며 초기화에 실패합니다

검출 모델은 float32 이미지 tensor 하나를 받아 리사이즈된 입력 해상도에서 [1, 1, H, W] 모양의 float32 확률 맵을 내야 합니다. 호환되지 않는 타입·차원, 비유한 값, float32 machine epsilon 네 개를 넘게 [0, 1]을 벗어나는 확률은 검출 결과를 쓰기 전에 진단과 함께 실패합니다

그 허용 오차 안의 미세한 sigmoid 반올림 오차는 threshold와 contour 채점 전에 [0, 1]로 clamp되므로, 정상적인 모델은 기존 검출 동작을 그대로 유지합니다

중국어 예제

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 인식 모델과 사전을 고릅니다

결과와 수명

어댑터는 현재 bitmap을 독립적인 top-down BGR 스냅샷으로 복사합니다. 할당 전에 크기와 픽셀 예산을 검사하고 빌린 bitmap을 바꾸지 않습니다

네이티브 파이프라인은 인식된 텍스트 행마다 결과 하나를 내놓으며, 원본 이미지 픽셀 경계와 문자 신뢰도 평균을 담습니다. 각 행은 MaxWords 슬롯 하나를 소비하고 네이티브 baseline은 제공되지 않습니다

검출 박스는 가로 행 읽기 순서를 따릅니다. 기본은 왼쪽에서 오른쪽이고 RightToLeft가 켜지면 오른쪽에서 왼쪽이며, 아랍어 프리셋이 이 옵션을 켭니다

인식 텍스트는 모델의 논리적 Unicode 순서를 유지합니다. 어댑터가 아랍어 문자열을 자동으로 뒤집거나 쌍방향 셰이핑을 적용하지 않습니다

angle classification은 개별 텍스트 crop을 교정할 뿐, 페이지 전체 방향을 판단하거나 거꾸로 된 페이지의 별개 검출 박스를 논리적 읽기 순서로 재배열하지 않습니다

어댑터는 UTF-8, Unicode 제어 문자, 경계, 신뢰도, 요청의 MaxTextCodeUnits 한도를 검증하며 텍스트 상한은 1,048,576 UTF-16 unit입니다. 보충 문자는 unit 두 개를 소비합니다

빈 페이지는 빈 결과 배열로 성공합니다. 실패는 부분 결과를 지우고, 검색 가능 PDF 공개는 기존 원자적 페이지 트랜잭션 동작을 유지합니다

같은 엔진에 대한 호출은 직렬화됩니다. 엔진 잠금 대기는 25밀리초마다 취소와 인식 기한을 검사합니다

네이티브 콜백은 검출, 분류, 인식된 각 행 앞뒤로 취소와 기한을 검사합니다. 개별 ONNX 추론 호출은 강제로 끊을 수 없으므로 취소는 현재 단계가 끝난 뒤에야 반환될 수 있습니다

입력·텍스트 한도는 어댑터 할당과 받아들이는 출력을 묶을 뿐, 모델, 검출, crop, 추론 메모리에 hard cap을 거는 것은 아닙니다

빌드와 ABI

Native/RapidOCR에는 C++ bridge, 호환 모델 인식기, 버전화 C 헤더, export 정의, CMake 프로젝트가 있습니다. DbNet, AngleNet, OcrUtils를 노출하는 호환 CPU 네트워크 소스와 짝이 맞는 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 생성기를 바꿀 수 있습니다

bridge는 C++ 예외를 감싸고 HPDFRapidOCRAbiVersion, HPDFRapidOCRCreate, HPDFRapidOCRRecognize, HPDFRapidOCRDestroy로 ABI 버전 1을 노출합니다. 모두 cdecl, 32비트 상태 값, 명시적 UTF-8 바이트 길이를 씁니다

ABI 버전 1은 선택적 HPDFRapidOCRSetReadingDirection export도 정의합니다. 어댑터는 RightToLeft가 켜졌을 때만 이를 요구하므로 기존 DLL도 왼쪽→오른쪽 요청은 계속 처리합니다

콜백은 호출 동안에만 텍스트를 빌려 씁니다. 어댑터는 검증된 텍스트를 반환 전에 복사하고, 엔진 소멸자는 DLL을 언로드하기 전에 모델을 파괴합니다

검증

Python onnx 패키지와 네이티브 BUILD_TESTING 빌드가 있으면 python tools/test_rapidocr_detector.py <build>/Release/NativeDetectorTests.exe를 실행해 DLL ABI를 통과하는 정상 빈 출력, 잘못된 tensor rank, channel·타입, 어긋난 공간 차원, 잘못된 확률을 검사합니다. runner 경로를 여러 개 지정하면 한 번의 호출로 두 아키텍처를 모두 검증할 수 있습니다

Delphi나 FPC 어댑터 runner에 -RapidOCRLanguageModelDirectory와 네이티브 DLL 라이브러리 파라미터를 하나 이상 지정하면 중국어, 러시아어, 일본어, 한국어, 주요 라틴 언어, 아랍어, 힌디어 샘플로 설치된 프리셋 전부를 검증합니다. 러시아어와 번체 중국어는 검색 가능 PDF 저장, 다시 로드, 텍스트 추출, 픽셀 비교까지 거칩니다

Delphi·FPC 어댑터 runner는 지속 모델 수명, BGR 행 레이아웃, Unicode와 보충 문자, ABI 검사, 잘못된 결과, 예산, 협력적 취소, 직렬화된 잠금 대기, 정리를 검사합니다

실제 모델 검증, 빈 페이지, 손상된 모델 처리, 영어·중국어 인식, 렌더링 픽셀이 바뀌지 않는 검색 가능 PDF 왕복에는 Tests/Delphi/Run-TesseractRecognitionTests.ps1이나 Tests/Delphi/Run-TesseractFPCRecognitionTests.ps1에 -RapidOCRNativeWin32Library, -RapidOCRNativeWin64Library, -RapidOCRNativeModelDirectory를 지정합니다

페이지 렌더링, Unicode PDF 텍스트 매핑, optional-content 그룹화, conformance 제약은 검색 가능한 OCR 텍스트 레이어를 보십시오