JSON 및 C ABI 문서 비교

로드된 문서 두 개는 THPDFJobProcessor.ExecuteLoadedOperationWithComparison으로, C ABI 핸들 두 개는 hpdf_document_compare_json_v1로, 파일 두 개는 JSON 잡 프로세서로 비교합니다

일반 모드

type=compare는 mode 값으로 pageCount, pageText, objectCount, renderedImage, full, structural을 받고 기본값은 structural입니다

이 모드들은 페이지 정렬과 구조적 객체 시그니처를 포함해 네이티브 THPDFDocComparison 동작을 그대로 유지하며, objectCount는 페이지와 객체 구조도 함께 비교합니다

{
  "schemaVersion": 1,
  "type": "compare",
  "mode": "full",
  "render": {"dpi": 72, "colorSpace": "rgb", "colorTolerance": 8},
  "options": {"maxDifferences": 1000, "maxStreamBytes": 1048576},
  "budget": {"memoryBytes": 268435456, "resultBytes": 16777216,
             "outputBytes": 67108864, "timeMilliseconds": 60000, "pixels": 10000000}
}

결과 엔벨로프에는 comparison, comparisonComplete, identical, documentUpdated=false, 경과 시간, 출력 크기가 들어가고, 선택적 바이너리 출력에는 엔벨로프를 뺀 비교 JSON이 담깁니다

순회, 스트림, 값, 보관 차이, 렌더링 한도에 걸리면 검사한 부분집합이 같아도 status=incomplete, comparisonComplete=false, identical=false가 됩니다

계약 검토

type=compare.contract는 문단을 정렬하고 이동을 탐지하며, 단어·문장 단위 삽입, 삭제, 교체를 문맥과 위치와 함께 보고합니다

{
  "schemaVersion": 1,
  "type": "compare.contract",
  "format": "pdf",
  "side": "after",
  "options": {"granularity": "word", "ignoreRepeatedHeadersFooters": true,
              "excludedLineTexts": ["CONFIDENTIAL COPY"], "maxWorkUnits": 50000000}
}

format은 json, html, pdf를 받고 기본값은 JSON이며, HTML이나 PDF는 출력 스트림이나 콜백이 필요합니다

변경 종류는 insert, delete, replace, move입니다. 페이지와 문단 인덱스는 0부터 시작하고 문자 시작 위치는 1부터 시작하는 UTF-16 위치이며, 사각형은 정확한 글리프 사변형이 아니라 PDF 사용자 공간의 의미 행을 덮습니다

PDF는 side=before 또는 side=after를 고르고, 선택한 문서를 모든 의미 페이지 스냅샷과 대조해 검증한 뒤 하이라이트와 Before/After 주석을 더하고 검토 사본을 저장하며, 소스 그래프 트랜잭션은 항상 롤백합니다

검토 PDF는 완전히 다시 쓴 결과라 서명 검증이 별도로 필요하고, 비교 자체는 빌린 소스 문서와 서명을 그대로 둡니다

옵션과 상한

일반 options는 maxObjects, maxEdges, maxPages, maxDepth, maxDifferences, maxStreamBytes, maxTotalStreamBytes, maxValueBytes, maxPathBytes를 받습니다

렌더링은 dpi, colorSpace(rgb 또는 luminance), colorTolerance, minimumSimilarity, maxChangedPixelRatio, tileSize, maxChangedRegions를 받고, 콜백 연산은 히트맵을 파일시스템에 쓰지 않습니다

계약 options는 THPDFContractCompareOptions의 불리언, 마진, 유사도, 상용구, 리소스 필드를 camelCase 이름으로 받고, granularity는 word 또는 sentence입니다

공유 예산은 memoryBytes, outputBytes, resultBytes, timeMilliseconds, pixels, objectCount, pageCount이며, 옵션은 이 예산 안으로 잘립니다

메모리 예산은 두 디코드 경로, 렌더링 픽셀, 정렬 저장소, 비공개 출력에 보수적으로 여유를 잡습니다. 운영체제 RSS 상한이 아니라 작업량 한도이고, 이미 로드된 객체 그래프의 소유권은 호출자에게 그대로 있습니다

JSON 할당은 보수적인 이스케이프 크기 추정으로 검사하므로, 최종 UTF-8 표현이 들어갈 결과도 거절될 수 있습니다. HTML은 출력 바이트 예산 안에서 보수적인 문자 허용량을 씁니다

예산 실패는 ABI 상태 8, 취소는 상태 4를 반환하고, 취소는 페이지, 객체, 스트림 블록, 렌더링 객체, 픽셀 행, 정렬 경계에서 협력적으로 처리됩니다

C ABI 오류 컨트롤 엔벨로프는 독립적인 8 KiB 최대치를 두고 상세 정보를 1,024 UTF-16 코드 유닛으로 자르므로, 요청한 결과 예산이 오류 응답을 담기에 너무 작을 때도 예산 오류를 보고할 수 있습니다

빌린 C ABI 핸들

각 핸들은 자체 hpdf_io_v1 소스로 로드하고 hpdf_document_compare_json_v1(handle_a, handle_b, operation)을 호출합니다. ABI v1 레코드 레이아웃과 기존 execute 익스포트는 그대로입니다

operation.input_io는 NULL이어야 하고 result_io는 쓰기를 제공해야 하며, 선택적 output_io가 아티팩트를 공급합니다. JSON 파일 키 input, otherInput, output은 거절됩니다

두 독립 소스 모두 짧은 랜덤 액세스 읽기를 돌려줄 수 있고, 디코딩된 객체가 캐시되어 있어도 두 취소 콜백은 폴링됩니다. 같은 핸들을 두 번 넘겨 자기 자신과 비교할 수도 있습니다

입력 콜백과 그 컨텍스트는 핸들 수명과 진행 중인 호출 동안 살려 두고, 각 핸들에서 연산은 직렬화하세요. 핸들 참조는 비교가 돌아올 때까지 유지됩니다

아티팩트는 콜백 발행 전에 비공개 유한 버퍼에서 만들고 검증합니다. 발행 중 실패한 콜백은 이미 받아들인 바이트를 남길 수 있지만 소스 문서는 그대로입니다

파일 작업

{"operations":[{"type":"compare.contract","input":"before.pdf",
  "otherInput":"after.pdf","format":"html","output":"review.html"}]}

password와 otherPassword는 두 파일을 각각 따로 잠금 해제하고, JSON 출력은 출력 경로를 생략해 결과 엔벨로프에만 담길 수 있습니다