Native headless document comparison
HPDFHeadlessCompare compares two loaded native documents via 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 normalised catalog, information and unreachable object graphs |
| hcmFull | full | Page and object counts, normalised graphs, Unicode text and rendered pixels |
Structural equivalence
Structural comparison resolves indirect references and sorts dictionary entries, normalises PDF names and literal or hexadecimal string representations, and decodes ordinary stream filters before hashing the content with SHA-256
Object numbers, serialisation order and ordinary stream compression do not change structural equivalence; terminal image encodings retain their filter and decode policy, whilst unreachable objects are compared as a multiset
Encryption dictionaries and cross-reference or object-stream storage containers are excluded from the 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 may differ when equivalent content uses different storage layouts
Rendered comparison
Each page is actually rendered with the native Cairo device at the selected DPI; decoded image pixels are composed on white and compared in RGB or luminance
Reports include 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 threshold values
Rendering requires the same supported fonts, image codecs and graphics semantics as native page rendering; an unsupported page fails the comparison instead of producing an identical report
Bounded execution
Comparison options bound traversal, depth, objects, decoded streams, text preparation, result storage and rendered pixels; cancellation applies to traversal, text extraction and rendering
Keep both document instances alive and exclusively owned throughout a Pascal comparison; their original content and resource options are preserved on success, failure and cancellation
The Linux ABI takes the six lowercase mode names above together with 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 follow the existing stable lock ordering
Report fields · Semantic contract comparison · Native Linux C ABI