JSON 및 C ABI 작업의 외부 OCR

ocr.layer 연산은 builtin-ascii, tesseract-cli, tesseract-dll, rapidocr-cli, rapidocr-dll을 받으며, engine을 생략하면 기본값인 내장 ASCII 엔진을 유지합니다

기능 조회는 지원되는 어댑터 목록을 보여줄 뿐, 실행 호스트에 외부 프로그램, 라이브러리, 언어 데이터, ONNX 모델이 설치돼 있다는 보장까지는 하지 않습니다

Tesseract 예제

{"schemaVersion":1,"type":"ocr.layer","pages":[0],"dpi":300,
 "minimumConfidence":0.7,"skipPagesWithText":true,"replaceExisting":false,
 "engine":"tesseract-cli",
 "engineOptions":{"executablePath":"C:/OCR/tesseract.exe",
   "tessDataDirectory":"C:/OCR/tessdata","language":"eng",
   "pageSegMode":6,"engineMode":3,"timeoutMilliseconds":30000,
   "maxPixels":16777216}}

이 객체를 파일 작업의 operations 배열에 넣고 input과 output 경로를 추가하거나, 로드된 핸들과 binary/result 콜백을 붙여 hpdf_document_execute_json_v1에 바로 넘겨도 됩니다

옵션과 로컬 리소스

외부 엔진에는 객체 값의 engineOptions를 명시해야 하며, 알 수 없는 키, 잘못된 JSON 타입, NUL이 포함된 경로나 언어 문자열, 빈 필수 값은 거부됩니다

Tesseract의 기본값은 language=eng, pageSegMode=3, engineMode=3이고, 세그먼테이션 모드 0과 2는 텍스트를 인식하지 못해 거부되며, 나머지 모드는 13까지 허용됩니다

engineMode는 0부터 3까지 받습니다. 학습 데이터 파일이 선택한 모드를 지원해야 하고, eng+fra 같은 다국어 Tesseract 언어 표현에는 해당하는 로컬 모델이 필요합니다

RapidOCR CLI는 기본 THPDFRapidOCROptions.Default 모델 이름을 쓰고 두 스레드 상한을 모두 1로 맞춥니다. 명시적으로 지정한 사전과 폰트 경로는 받아들이며, 구성된 bridge는 로컬 TSV 계약을 구현해야 합니다

RapidOCR DLL은 THPDFRapidOCRDLLOptions.ForLanguage(language)로 시작하며 기본 언어는 ch입니다. 언어 프로파일이 인식 모델, 사전, 읽기 방향을 고르고, 명시적 옵션으로 이 선택을 덮어쓸 수 있습니다

모델 파일 이름은 네이티브 어댑터 규칙에 따라 modelDirectory 아래에서 해석됩니다. 라이브러리 비트 수는 호스트 프로세스와 일치해야 하고, CLI 엔진은 별도의 로컬 프로세스로 실행됩니다

이 리소스들은 직접 준비해서 선택해야 합니다. 이 연산은 엔진을 설치하거나, 모델을 내려받거나, 임의의 실행 파일을 찾거나, 원격 OCR 서비스를 쓰지 않습니다

예산과 취소

timeoutMilliseconds의 기본값은 60,000이고 1부터 3,600,000까지의 정수를 받으며, 실제 어댑터 타임아웃은 budget.timeMilliseconds가 상한이 됩니다

maxPixels의 기본값은 16,777,216이고 1부터 67,108,864까지의 정수를 받으며, 실제 상한은 요청값, budget.pixels, budget.memoryBytes / 16 중 최솟값입니다

엔진 픽셀 상한은 인식 전 OCR 페이지 렌더링에도 그대로 적용되고, 단어·콘텐츠·UTF-16 텍스트 예산은 연산의 메모리 허용량으로 제한됩니다

이 제한들은 구성된 버퍼와 연산 리소스를 묶을 뿐, 외부 DLL 모델 할당까지 엄격한 프로세스 RSS 할당량으로 강제하지는 않습니다

네이티브 호출은 렌더링과 인식에 Document.OperationCancellationToken을 빌려 쓰고, C 콜백 취소는 협력적 연산·입력·출력 체크포인트에서 폴링됩니다. 실행 중인 외부 엔진은 타임아웃이나 다음 콜백 체크포인트까지 계속 돌 수 있습니다

로컬 CLI 실패, 잘못됐거나 불완전한 TSV 출력, 어댑터 타임아웃은 연산을 거부하며, 구성된 연산 시간과 픽셀 한도 초과는 구조화된 budget 실패 범주를 그대로 유지합니다

출력과 트랜잭션 동작

결과는 engine, recognizedPages, skippedPages, acceptedWords, droppedWords를 보고하며, engine 필드에는 네이티브 어댑터의 설명용 이름이 들어갑니다

minimumConfidence는 0부터 1 사이의 숫자여야 하고, skipPagesWithText와 replaceExisting은 JSON 불리언이어야 합니다

받아들여진 Unicode 단어는 ToUnicode 매핑과 원본 페이지 지오메트리를 갖춘 보이지 않는 텍스트로 들어갑니다. 스캔 이미지는 출력에 그대로 남고, 호출자가 같은 파일 경로로 의도적으로 발행하지 않는 한 원본 파일은 변경되지 않습니다

파일 작업은 실패 시 기존 대상을 보존하고 같은 디렉터리의 staging 파일을 통해 발행합니다. C ABI 변경은 PDF 바이트와 JSON 결과 전달이 모두 성공한 뒤에 커밋되며, 실패하면 롤백하고 이미 전달된 바이트는 호출자가 해제합니다

검증

Tests/Delphi/Run-JobOCRTests.ps1는 Win32와 Win64에서 어댑터 디스패치 프로파일 4가지, 잘못된 구성, 픽셀 및 경과 시간 예산, 부분 단어 거부, 프로세스 실패, 타임아웃, 대상/원본 보존을 실행합니다

실제 Tesseract 실행 파일과 모델 경로를 넣으면 라이브 인식까지 검증합니다. 독립적인 pypdf와 MuPDF 리더로 Unicode 검색 텍스트와 변하지 않은 가시 스캔 픽셀을 확인하고, 선택적인 실제 Win64 ABI DLL 점검은 부분 콜백과 실패 연산 롤백을 확인합니다

문서 연산, Tesseract 어댑터, 로컬 RapidOCR 모델, 네이티브 RapidOCR 라이브러리, 검색 가능한 OCR 텍스트 레이어를 보십시오