PDFIDIFF(1)

NAME
pdfidiff - compare two PDF files and write differences to a third file file.

SYNOPSIS
pdfidiff [-h(elp)] [-f fuzz_dist] [-g(hostscript)] [-m mode] [-o(ptimize)] [-q(uiet)] [-r resolution] [-s(ingle_threaded)] oldfile newfile deltafile

DESCRIPTION
pdfidiff reads in any two PDF files readable by poppler (or ghostscript) and write out an image-based "delta" file that represents the differences between the two files. This is accomplished by using the pdftocairo (or gs), imagdiff, img2pdf, and tempname utilities.

OPTIONS

-h  Print help and quit.

-g  Use ghostscript (gs) instead of poppler (pdftocairo) as the PDF rendering engine.

-f fuzz_dist
    When performing a grayscale difference analysis, any pixel values within the distance specified by -f option are considered equal. This option has no effect on a color difference analysis. The default value is 15.

-m mode
    Set of the mode of the difference analysis. At present, five modes are available, as described in the MODES section. The default mode is 2.

-o  Use opt-pdf to minimize the filesize of intermediate PNG files before assembling the final PDF file.

-q  Cause pdfidiff to silence the progress information normally printed during operation.

-r resolution
    Use the specified resolution (in DPI) when converting from PDF to intermediate PNG. The default value is 300.

-s  The pdfidiff utility will normally utilize GNU parallel (if present on the system) to perform operations in parallel to reduce computation time. Using this option will force single-threaded operation.

MODES

1   Grayscale: In this mode, both input files are converted to grayscale PNG files. Any pixels that are darker (when comparing old to new) are highlighted in BLUE, and any pixels that are brighter are highlighted in RED. [On a B&W drawing with a white background, this results in additions being highlighted in BLUE, and subtractions being highlighted in RED.]

2   Grayscale (lightened): This works much like the Grayscale analysis of mode 1, except that all unchanged pixels are shifted halfway towards white. This makes it easier to identify changes on files where the background is predominantly white.

3   Grayscale (darkened): This works much like the Grayscale analysis of mode 1, except that all unchanged pixels are shifted halfway towards black. This makes it easier to identify changes on files where the background is predominantly black.

4   Color: Here, the differences between the two files are computed on a per-RED, per-GREEN, and per-BLUE basis and are shifted and scaled such that unchanged pixels will show up as 50% gray.

5   Color (stretched): Again, differences between the two files are computed on a per-channel and are shifted that unchanged pixels will show up as 50% gray, but here the scaling is maximimized to emphasize differences.

NOTES
The pdfidiff utility uses pdftocairo or gs to convert both input files into a series of PNG image files. These files are then compared using imagdiff, and the resulting image "deltas" are reassemblied into a final PDF file using img2pdf.

CAVEATS
Because the input files are converted from PDF to PNG and are manipulated as bitmaps, the final PDF output will not contains any searchable string information, even if the input files did. If you need to compare the text found in two different PDF files, you may have better luck with an alternate tool such as diffpdf or pdf-diff.

SEE ALSO
gs(1), img2pdf(1), parallel(1), imagdiff(1), diffpdf(1), pdf-diff(1), pdftocairo(1)

COPYRIGHT
Copyright (C) 2018-2026 by Brian Lindholm. This program is free software; you can use it, redistribute it, and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.