> ## 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.

# Basic comparison

> Learn how to perform basic PDF visual comparisons with pdf-visual-diff

## Quick start

The most basic comparison requires two PDF files:

```bash theme={null}
python pdf_visual_diff.py document1.pdf document2.pdf
```

This will compare the two PDFs page-by-page and output any differences to the default `diff_output` directory.

## Understanding the output

When differences are detected, the tool will:

1. Print a summary to the console
2. Create a timestamped output directory
3. Generate diff images highlighting visual differences
4. Save a JSON report with detailed results

### Console output examples

<Tabs>
  <Tab title="Identical PDFs">
    ```bash theme={null}
    All pages are visually identical.
    ```
  </Tab>

  <Tab title="Differences found">
    ```bash theme={null}
    Visual differences found on pages: 1, 3, 5
    Diff images saved to: /path/to/diff_output/20260304_143052_diff
    ```
  </Tab>

  <Tab title="Different page counts">
    ```bash theme={null}
    Warning: PDFs have different page counts. PDF1: 10 pages, PDF2: 8 pages.
    Comparing up to the lower page count.
    Visual differences found on pages: 2
    Extra pages only in PDF1: 9, 10
    Diff images saved to: /path/to/diff_output/20260304_143052_diff
    ```
  </Tab>
</Tabs>

## Specifying an output directory

To save results to a custom location, use the `--output` flag:

```bash theme={null}
python pdf_visual_diff.py old.pdf new.pdf --output ./reports
```

The tool will create a timestamped subdirectory within your specified path:

```
reports/
└── 20260304_143052_diff/
    ├── diff_page_1.png
    ├── diff_page_3.png
    └── results.json
```

<Note>
  The timestamp format is `YYYYDDMM_HHMMSS`, ensuring each comparison run creates a unique output directory.
</Note>

## Adjusting sensitivity

Control how strict the comparison is using the `--threshold` parameter:

```bash theme={null}
# Very strict (default): only flag significant differences
python pdf_visual_diff.py doc1.pdf doc2.pdf --threshold 1

# More sensitive: detect subtle differences
python pdf_visual_diff.py doc1.pdf doc2.pdf --threshold 0.95

# Very sensitive: detect minor variations
python pdf_visual_diff.py doc1.pdf doc2.pdf --threshold 0.85
```

The threshold value ranges from 0.0 to 1.0, where:

* `1.0` = Pixel-perfect match required
* `0.999` = Internal default when comparing
* Lower values = More tolerant of differences

See [Configuration options](/usage/configuration-options) for detailed threshold guidance.

## Common usage patterns

<Accordion title="Comparing reports from different dates">
  ```bash theme={null}
  python pdf_visual_diff.py report_2024-01.pdf report_2024-02.pdf \
    --output monthly_comparisons \
    --threshold 0.99
  ```
</Accordion>

<Accordion title="Testing PDF generation changes">
  ```bash theme={null}
  # Before code changes
  python generate_pdf.py --output baseline.pdf

  # After code changes
  python generate_pdf.py --output updated.pdf

  # Compare
  python pdf_visual_diff.py baseline.pdf updated.pdf \
    --output test_results
  ```
</Accordion>

<Accordion title="Batch comparison with shell script">
  ```bash theme={null}
  #!/bin/bash
  for file in baseline/*.pdf; do
    filename=$(basename "$file")
    python pdf_visual_diff.py \
      "baseline/$filename" \
      "updated/$filename" \
      --output "batch_results/$filename"
  done
  ```
</Accordion>

## What gets compared

The tool performs visual comparison by:

1. Rendering each PDF page to an image at 144 DPI (2x zoom)
2. Converting images to RGB arrays
3. Computing Structural Similarity Index (SSIM) between pages
4. Flagging pages below the threshold
5. Generating highlighted diff images for flagged pages

<Note>
  The comparison is purely visual. Changes to PDF metadata, embedded fonts, or internal structure are ignored unless they affect the rendered appearance.
</Note>

## Handling different page sizes

If PDFs have different dimensions, the tool automatically:

* Resizes images to match for comparison (using LANCZOS interpolation)
* Continues the comparison without error

This allows comparing PDFs with different page sizes or orientations.

## Next steps

<CardGroup cols={2}>
  <Card title="Command reference" icon="terminal" href="/usage/command-reference">
    Complete documentation of all CLI options
  </Card>

  <Card title="Output formats" icon="file-image" href="/usage/output-formats">
    Understanding generated files and JSON reports
  </Card>
</CardGroup>