Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DilwoarH/pdf-visual-regression/llms.txt

Use this file to discover all available pages before exploring further.

​
Comparing identical PDFs

The most basic use case is verifying that two PDFs are visually identical. This is useful for regression testing after code changes.
1

Run the comparison

python pdf_visual_diff.py example-pdfs/test1_original.pdf example-pdfs/test1_identical.pdf
2

Review the output

When PDFs are identical, you’ll see:
All pages are visually identical.
No diff images are generated, and the tool exits successfully.
When PDFs are identical, no output directory is created since there are no diff images to save.

​
Detecting visual differences

When comparing PDFs with visual differences, the tool highlights the changed areas. 
python pdf_visual_diff.py example-pdfs/example-working-gov-letter.pdf example-pdfs/example-broken-gov-letter.pdf

​
Expected output

Visual differences found on pages: 1
Diff images saved to: /path/to/diff_output/20261202_171728_diff/

​
What gets generated

The tool creates a timestamped output directory containing: 
diff_output/20261202_171728_diff/
├── diff_page_1.png
└── results.json

​
Specifying output directory

By default, diff images are saved to diff_output/. You can customize this location: 
python pdf_visual_diff.py file1.pdf file2.pdf --output my_custom_output
The tool will create a timestamped subdirectory within your specified output directory: 
my_custom_output/20261202_171728_diff/
Timestamped directories prevent overwriting previous comparison results, allowing you to maintain a history of test runs. The format is YYYYMMDD_HHMMSS_diff.

​
Visual difference highlighting

Differences are highlighted in red on the diff images:
The original or expected version of your PDF serves as the baseline for comparison.Working PDF

​
Command-line help

View all available options: 
python pdf_visual_diff.py --help

usage: pdf_visual_diff.py [-h] [--output OUTPUT] [--threshold THRESHOLD] pdf1 pdf2

Compare two PDFs for visual differences.

positional arguments:
  pdf1                 Path to the first PDF file.
  pdf2                 Path to the second PDF file.

optional arguments:
  -h, --help           show this help message and exit
  --output OUTPUT      Directory to save difference images.
  --threshold THRESHOLD
                       Similarity threshold for SSIM (0.0 to 1.0).

Build docs developers (and LLMs) love

Get started for freeTalk to us