PdfCompare

Comparing large PDFs can consume significant memory because images are held in RAM. To prevent OutOfMemoryError, use specialized CompareResult implementations that swap pages to disk.

Available Implementations

• CompareResultWithPageOverflow: Swaps every 10 pages (default) into a partial PDF and merges them at the end. This is a good balance of performance and memory.
• CompareResultWithMemoryOverflow: Swaps pages to disk when the JVM heap reaches a critical threshold (default is 70% of max heap).

Usage:

new PdfComparator("expected.pdf", "actual.pdf", new CompareResultWithPageOverflow()).compare();

Advanced Memory Tuning (via application.conf)

If using the overflow implementations, you can tune these settings in an application.conf file:

• imageCacheSizeCount: Number of images cached by PdfBox.
• maxImageSizeInCache: Max size of an image to be cached.
• mergeCacheSizeMB: Memory cache for the merge process.
• swapCacheSizeMB: Memory cache for partial writes.
• documentCacheSizeMB: Cache for loaded documents.
• overallTimeoutInMinutes: Safety timeout to detect deadlocks.
• executorTimeoutInSeconds: Timeout for executors after overall timeout is reached.

You can define rectangular areas to ignore during comparison using either a configuration file or the programmatic API.

Using an Exclusion File

Create a file in HOCON/JSON format. Entries without units are treated as pixels (default rendering is 300DPI). Units like mm, cm, or pt (1/72 inch) are supported.

Exclusion File Format:

exclusions: [
    {
        page: 2
        x1: 300
        y1: 1000
        x2: 550
        y2: 1300
    },
    {
        // page is optional; if omitted, applies to all pages
        x1: 130.5mm
        y1: 3.3cm
        x2: 190mm
        y2: 3.7cm
    },
    {
        page: 7
        // coordinates are optional; if omitted, the whole page is excluded
    }
]

Apply the file via the API:

new PdfComparator("expected.pdf", "actual.pdf").withIgnore("ignore.conf").compare();

Using the Programmatic API

Add exclusions directly in your code using PageArea objects:

new PdfComparator("expected.pdf", "actual.pdf")
    .withIgnore(new PageArea(1, 230, 350, 450, 420))
    .withIgnore(new PageArea(2))
    .compare();

You can override settings programmatically using withEnvironment and a SimpleEnvironment. SimpleEnvironment delegates unassigned settings to the default environment.

new PdfComparator("expected.pdf", "actual.pdf")
    .withEnvironment(new SimpleEnvironment()
        .setActualColor(Color.green)
        .setExpectedColor(Color.blue))
    .compare();

Available Configuration Options

The primary way to use PdfCompare is as an embedded library. It renders PDF pages to bitmaps and performs a pixel-by-pixel comparison.

Basic Comparison and Output:

// Compares files and writes a diff PDF to 'diffOutput'
new PdfComparator("expected.pdf", "actual.pdf").compare().writeTo("diffOutput");

Querying Results: Use the CompareResult object returned by .compare() to inspect the outcome:

final CompareResult result = new PdfComparator("expected.pdf", "actual.pdf").compare();
if (result.isNotEqual()) {
    System.out.println("Differences found!");
}
if (result.isEqual()) {
    System.out.println("No Differences found!");
}
if (result.hasDifferenceInExclusion()) {
    System.out.println("Differences in excluded areas found!");
}
// Returns page areas where differences were found
result.getDifferences();

Note on Input Types: The compare method accepts filenames as String, File, Path, or InputStream.