IMGDIFF(1)

NAME

imgdiff - compare two images and report or visualize their differences

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

imgdiff [options] img1 img2 [output]

imgdiff compares two images, img1 and img2, on a per-channel, per-pixel basis and reports how many channels match exactly, differ by one unit, or differ by more than one unit. Input images are read through the libicv image library, so any format libicv understands (such as pix(5), bw(5), and PNG) may be compared, and the two inputs need not share the same format.

The image format is normally inferred from each file’s extension. For raw formats that carry no embedded dimensions (pix(5) and bw(5)), imgdiff attempts to deduce the width and height from the file size; when that fails, the dimensions must be supplied explicitly.

If an output path is given (either with -o or as a third positional argument) and the images differ, a difference image is written highlighting the disagreeing pixels. When PNG render metadata is present, imgdiff can additionally compare that metadata and emit nirt(1) shotline scripts that re-trace the differing pixels for debugging renders.

OPTIONS

-h, --help, -?: Print a usage summary and exit.
-o file, --output file: Write the difference image to file. The file must not already exist. Equivalent to supplying output as a third positional argument.
-n prefix, --nirt-output prefix: Write nirt(1) shotline scripts for the differing pixels. One file is produced per image that carries PNG render metadata: prefix_img1.nirt and/or _prefix_\_img2.nirt.
--width-img1 #: Width in pixels of the first image (for raw formats lacking embedded size).
--height-img1 #: Height in pixels of the first image.
--width-img2 #: Width in pixels of the second image.
--height-img2 #: Height in pixels of the second image.
--format-img1 format: Override the auto-detected file format of the first input image.
--format-img2 format: Override the auto-detected file format of the second input image.
--output-format format: Override the auto-detected file format of the output image.
-A, --approximate: Instead of the per-channel report, compute an approximate perceptual difference metric and print the Hamming distance between the two images.
-m, --metadata: Compare embedded render metadata (PNG only) and report whether it is identical or differs.

EXAMPLES

Example 1. Visualize the difference between two renders

imgdiff -o changed.png baseline.png current.png

Compares two PNG renders pixel by pixel, prints how many channels match or differ, and, if they differ, writes changed.png highlighting exactly which pixels changed — useful for spotting regressions in rt(1) output.

Example 2. Compare raw pix images of known size and trace differing pixels

imgdiff --width-img1 512 --height-img1 512 \
        --width-img2 512 --height-img2 512 \
        -n shots ref.pix new.pix

Compares two 512x512 pix(5) images whose dimensions cannot be inferred from the file, and, for any image carrying render metadata, writes nirt(1) shotline scripts (shots_img1.nirt, shots_img2.nirt) that re-fire rays through the differing pixels.