Native headless document comparison
HPDFHeadlessCompare compares two loaded native documents through HPDFCompareHeadlessDocuments; the Linux callback ABI exposes the same implementation through hpdf_document_compare_json_v1 with type:compare
| Pascal mode | JSON mode | Compared content |
|---|---|---|
| hcmPageCount | pagecount | Page-tree leaf counts |
| hcmPageText | pagetext | Page counts and extracted Unicode text |
| hcmObjectCount | objectcount | Page counts and physical in-use cross-reference object counts |
| hcmRenderedImage | renderedimage | Page counts, rendered dimensions and native Cairo pixels |
| hcmStructural | structural | Page counts and normalized catalog, information and unreachable object graphs |
| hcmFull | full | Page and object counts, normalized graphs, Unicode text and rendered pixels |
Structural equivalence
Structural comparison resolves indirect references and sorts dictionary entries, normalizes PDF names and literal or hexadecimal string representations, and decodes ordinary stream filters before hashing content with SHA-256
Object numbers, serialization order and ordinary stream compression do not change structural equivalence; terminal image encodings retain their filter and decode policy, while unreachable objects are compared as a multiset
Encryption dictionaries and cross-reference or object-stream storage containers are excluded from semantic structure; authenticated AES R5/R6 content is compared after decryption, with extraction permission enforced
A structural difference reports the document-level path $Document; physical object counts remain a separate mode and can differ when equivalent content uses different storage layouts
Rendered comparison
Each page is actually rendered using the native Cairo device at the selected DPI; decoded image pixels are composed on white and compared in RGB or luminance
Reports contain dimensions, changed pixel counts, maximum channel delta, mean absolute error, changed pixel ratio and similarity; similarity is 1 - meanAbsoluteError / 255
A pixel changes when its maximum channel delta exceeds ColorTolerance; a page passes only when dimensions match and both similarity and changed pixel ratio meet the configured thresholds
Rendering requires the same supported fonts, image codecs and graphics semantics as native page rendering; an unsupported page fails the comparison rather than producing an identical report
Bounded execution
Comparison options bound traversal, depth, objects, decoded streams, text preparation, result storage and rendered pixels; cancellation reaches traversal, text extraction and rendering
Keep both document instances alive and exclusively owned during a Pascal comparison; their original content and resource options are preserved on success, failure and cancellation
The Linux ABI accepts the six lowercase mode names above and strict options members matching the Pascal limits, plus dpi, colorTolerance, minimumSimilarity, maxChangedPixelRatio and colorSpace:rgb or luminance
ABI results are fully prepared and bounded before synchronous callback publication; same-handle calls and opposite-order concurrent calls use the existing stable lock ordering
Report fields · Semantic contract comparison · Native Linux C ABI