Tesseract OCR 어댑터

HPDFTesseractRecognition은 검색 가능한 OCR 텍스트 레이어용으로 IHPDFOCREngine을 구현하는 선택적 Windows 엔진을 제공합니다

네이티브 DLL 팩토리

function HPDFCreateTesseractDLLOCREngine(const LibraryPath,
  TessDataDirectory, Language: string): IHPDFOCREngine; overload;
function HPDFCreateTesseractDLLOCREngine(const LibraryPath,
  TessDataDirectory, Language: string;
  const Options: THPDFTesseractOptions): IHPDFOCREngine; overload;

Tesseract 5 호환 C API를 노출하는 기존 Tesseract DLL, tessdata 디렉터리, eng, chi_sim, chi_sim+eng 같은 ASCII 언어 식별자나 조합을 준비합니다

라이브러리 아키텍처는 애플리케이션과 맞아야 합니다. Win32 애플리케이션은 32비트 DLL을, Win64 애플리케이션은 64비트 DLL을 로드합니다

필요한 의존 DLL은 선택한 라이브러리 옆이나 표준 Windows 로더 디렉터리에 둡니다. 어댑터는 현재 디렉터리나 프로세스 검색 경로를 바꾸지 않고 명시된 라이브러리 경로를 로드합니다

팩토리는 요청된 모든 .traineddata 파일을 검증하고 라이브러리를 로드해 필요한 export를 전부 해석한 뒤 반환합니다. 잘못된 경로, 모델, options와 없는 export, 아키텍처 불일치, 의존성 부재는 예외를 발생시킵니다

OCR 런타임이나 모델은 번들되지 않고 자동으로 다운로드되지도 않습니다

두 팩토리는 Delphi와 C++Builder 빌드뿐 아니라 Windows FPC/Lazarus 패키지에서도 사용할 수 있습니다. HPDFTesseractRecognition을 쓰기 전에 대상 아키텍처로 Lib/FPC/HotPDFLaz.lpk를 다시 빌드하십시오

네이티브 FPC 어댑터는 scanline으로 기록한 픽셀을 포함해 현재 LCL raw 이미지를 읽고, 시스템 ANSI 코드 페이지와 무관하게 Unicode 단어를 보존합니다

Options

THPDFTesseractOptions = record
  PageSegMode: THPDFTesseractPageSegMode;
  EngineMode: THPDFTesseractEngineMode;
  TimeoutMilliseconds: Cardinal;
  MaxPixels: Integer;
  class function Default: THPDFTesseractOptions; static;
end;

필드를 재정의하기 전에 THPDFTesseractOptions.Default를 호출합니다. 같은 record로 네이티브 DLL 팩토리와 로컬 CLI options overload를 모두 설정할 수 있습니다

THPDFTesseractPageSegMode = (
  tpsOSDOnly, tpsAutoOSD, tpsAutoOnly, tpsAuto, tpsSingleColumn,
  tpsSingleBlockVertical, tpsSingleBlock, tpsSingleLine, tpsSingleWord,
  tpsCircleWord, tpsSingleCharacter, tpsSparseText, tpsSparseTextOSD,
  tpsRawLine);
THPDFTesseractEngineMode = (
  temLegacyOnly, temLSTMOnly, temLegacyAndLSTM, temDefault);

tpsOSDOnly와 tpsAutoOnly는 단어 인식을 하지 않아 어댑터가 거부하고, tpsAutoOSD와 tpsSparseTextOSD는 추가로 osd.traineddata를 요구합니다

텍스트 한 줄에는 tpsSingleLine, 균질한 블록에는 tpsSingleBlock, 흩어진 텍스트에는 tpsSparseText를 씁니다. 이 모드들이 스캔본의 원근을 교정하거나 일반적인 레이아웃 보장을 주지는 않습니다

temLSTMOnly는 LSTM 모델을 요구하고 legacy 모드는 대응하는 legacy 모델 구성 요소를 요구합니다. 지원되지 않는 조합은 네이티브 초기화 중 실패합니다

검색 가능 PDF 예제

PDF는 이미 로드된 상태여야 하고, DLL, 의존성, 언어 모델은 표시된 위치에 설치돼 있어야 합니다

uses SysUtils, HPDFDoc, HPDFTesseractRecognition;

procedure AddNativeOCRText(PDF: THotPDF);
var
  Engine: IHPDFOCREngine;
  NativeOptions: THPDFTesseractOptions;
  LayerOptions: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  NativeOptions := THPDFTesseractOptions.Default;
  NativeOptions.EngineMode := temLSTMOnly;
  NativeOptions.PageSegMode := tpsAuto;
  Engine := HPDFCreateTesseractDLLOCREngine(
    'C:\OCR\libtesseract-5.dll', 'C:\OCR\tessdata',
    'chi_sim+eng', NativeOptions);
  LayerOptions := THPDFOCRTextLayerOptions.Default;
  if not PDF.ApplyLoadedOCRTextLayer([0], Engine, LayerOptions, Info) then
    raise Exception.Create(string(Info.Diagnostic));
end;

결과와 소유권

어댑터는 빌린 bitmap을 top-down grayscale 버퍼로 복사하고, 요청 DPI를 그대로 전달하며, 요청별 네이티브 API 인스턴스로 인식합니다

단어는 네이티브 읽기 순서, 검증된 UTF-8 Unicode 텍스트, 왼쪽 위 픽셀 경계, 0~100을 0~1로 조정한 신뢰도를 유지합니다. 보충 문자는 UTF-16 unit 두 개를 소비합니다

사용 가능한 단어 baseline은 양 끝점과 함께 전달되고, baseline이 없으면 기존 text-layer 지오메트리 폴백이 적용됩니다

세로 방향 baseline이 지배적이면 네이티브 어댑터는 단어 box 폭을 TextHeightPixels로 씁니다. 가로 baseline은 읽기 방향이 반대여도 box 높이를 쓰므로, 세로 단어의 길이가 곧 폰트 크기가 되는 일은 없습니다

이는 지배 축 추정입니다. 축에 정렬된 단어 box와 baseline만으로는 임의의 기울기 각도에서 정확한 텍스트 높이를 복원할 수 없습니다

빈 페이지는 빈 단어 배열로 성공합니다. 잘못된 UTF-8, 내장 제어 문자, 잘못된 지오메트리나 신뢰도, 소진된 단어·텍스트 예산, 취소, 인식 실패는 False를 반환하고 모든 부분 단어를 지우며 진단을 채웁니다

각 요청은 자기 iterator, 할당한 네이티브 문자열, monitor, API 인스턴스를 해제합니다. 어댑터를 해제하면 라이브러리 참조가 언로드됩니다

한도와 취소

입력 크기는 각각 최대 32,767픽셀이고 MaxPixels 안에 들어야 합니다. 인식 텍스트는 요청의 MaxTextCodeUnits 예산과 어댑터의 1,048,576 UTF-16 unit 한도 안에, 단어 수는 MaxWords 안에 들어야 합니다

어댑터는 bitmap 변환과 결과 반복 중에 취소와 경과 시간을 검사하고, 인식 중에는 남은 기한과 취소 콜백을 담은 네이티브 monitor를 넘깁니다

네이티브 취소는 협력적입니다. Tesseract의 monitor는 단어 인식을 커버할 뿐 모든 초기화나 레이아웃 분석 단계를 끊지 못하므로, 이런 호출들은 요청된 취소나 만료된 기한이 보고되기 전에 끝날 수 있습니다

픽셀·출력 예산이 네이티브 라이브러리의 모델이나 인식 메모리 사용에 hard limit을 거는 것은 아닙니다. 별도로 종료 가능한 worker가 필요하면 프로세스 어댑터를 쓰십시오

ApplyLoadedOCRTextLayer는 모든 결과를 검증하고 선택된 모든 페이지를 원자적으로 공개하므로, 어댑터 실패는 로드된 문서를 그대로 둡니다

DLL 어댑터는 잘못된 UTF-8을 거부하고 디코딩된 단어 텍스트를 다듬으며, 결과를 반환하기 전에 남은 C0, DEL, C1 제어 문자를 거부합니다. 잘못된 텍스트는 PDF text layer에 조용히 빠지는 대신 요청을 실패시킵니다

로컬 CLI 팩토리

function HPDFCreateTesseractOCREngine(const ExecutablePath,
  TessDataDirectory, Language: string;
  TimeoutMilliseconds: Cardinal = 60000): IHPDFOCREngine; overload;
function HPDFCreateTesseractOCREngine(const ExecutablePath,
  TessDataDirectory, Language: string;
  const Options: THPDFTesseractOptions): IHPDFOCREngine; overload;

options overload는 PageSegMode를 --psm으로, EngineMode를 --oem으로 전달하고, 설정된 타임아웃을 쓰며, 빌린 bitmap을 저장하거나 worker를 시작하기 전에 MaxPixels를 검사합니다

기존 타임아웃 overload는 새 어댑터 픽셀 한도를 두지 않고 자동 페이지 분할과 실행 파일이 고르는 engine mode를 유지합니다. 명시적인 입력 한도가 필요하면 options overload를 쓰세요

두 overload 모두 요청 DPI, TSV 출력, 제한된 상속 handle, 취소 폴링, 실패 시 worker 종료를 유지합니다. CLI에는 네이티브 baseline 정보가 없고, TSV 출력은 64MiB, 진단 파일 출력은 1MiB로 제한됩니다

잘못된 분할 모드, engine mode, 타임아웃, 픽셀 한도는 설정된 엔진을 만들 때 EArgumentException을 발생시킵니다. 방향 모드용 osd.traineddata를 포함한 모델 가용성과 모델·엔진 호환성은 인식 중 실행 파일이 검사합니다

var
  CLIOptions: THPDFTesseractOptions;
  Engine: IHPDFOCREngine;
begin
  CLIOptions := THPDFTesseractOptions.Default;
  CLIOptions.PageSegMode := tpsSingleLine;
  CLIOptions.EngineMode := temLSTMOnly;
  CLIOptions.MaxPixels := 8000000;
  Engine := HPDFCreateTesseractOCREngine(
    'C:\OCR\tesseract.exe', 'C:\OCR\tessdata', 'eng', CLIOptions);
end;

단독 단어에는 tpsSingleWord, 흩어진 텍스트에는 tpsSparseText, 세로 블록 하나에는 적합한 세로쓰기 모델과 함께 tpsSingleBlockVertical을 씁니다. 팩토리가 페이지를 잘라내거나 모델을 자동으로 고르지는 않습니다

CLI 어댑터는 UTF-8을 엄격히 검증하고, 인식된 단어 안의 NUL 바이트와 C0/C1 제어 문자를 거부하며, 멀쩡한 단어 뒤에 잘못된 출력이 이어지면 모든 결과를 지웁니다

CLI 예제, 렌더링 options, optional-content 그룹화, conformance 한도는 검색 가능한 OCR 텍스트 레이어를 보십시오