.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH IDIFF 1 "Dec 11, 2012"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
idiff \- compare two images
.SH SYNOPSIS
.B idiff
.RI [ options ] " image1 image2"
.SH DESCRIPTION
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
.\" respectively.
The \fBidiff\fP utility is invoked as follows:

.B idiff
.RI [ options ] " image1 image2"

Where input1 and input2 are the names of two image files that should
be compared. They may be of any format recognized by OpenImageIO
(i.e., for which image-reading plugins are available).
.PP
If the two input images are not the same resolutions, or do not have
the same number of channels, the comparison will return FAILURE
immediately and will not attempt to compare the pixels of the two
images. If they are the same dimensions, the pixels of the two images
will be compared, and a report will be printed including the mean and
maximum error, how many pixels were above the warning and failure
thresholds, and whether the result is PASS, WARNING, or FAILURE. For
example:

.nf
$ idiff a.jpg b.jpg
Comparing "a.jpg" and "b.jpg"
  Mean error = 0.00450079
  RMS error = 0.00764215
  Peak SNR = 42.3357
  Max error = 0.254902 @ (700, 222, B)
  574062 pixels (82.1%) over 1e-06
  574062 pixels (82.1%) over 1e-06
FAILURE
.fi

The "mean error" is the average difference (per channel, per
pixel). The "max error" is the largest difference in any pixel
channel, and will point out on which pixel and channel it was
found. It will also give a count of how many pixels were above the
warning and failure thresholds.
.PP
The metadata of the two images (e.g., the comments) are not currently
compared; only differences in pixel values are taken into
consideration.
.PP
For a complete description, see
.IR /usr/share/doc/openimageio-doc/openimageio.pdf.gz .
.SH OPTIONS
.TP
.B \-\-help
Print help message
.TP
.B \-v
Verbose status messages
.TP
.B \-a
Compare all subimages/miplevels
.SS Thresholding and comparison options
.TP
.BI \-fail\  %g
Failure threshold difference (0.000001)
.TP
.BI \-failpercent\  %g
Allow this percentage of failures (0)
.TP
.BI \-hardfail\  %g
Fail if any one pixel exceeds this error (infinity)
.TP
.BI \-warn\  %g
Warning threshold difference (0.00001)
.TP
.BI \-warnpercent\  %g
Allow this percentage of warnings (0)
.TP
.BI \-hardwarn\  %g
Warn if any one pixel exceeds this error (infinity)
.TP
.B \-p
Perform perceptual (rather than numeric) comparison
.SS Difference image options
.TP
.BI \-o\  %s
Output difference image
.TP
.B \-od
Output image only if nonzero difference
.TP
.B \-abs
Output image of absolute value, not signed difference
.TP
.BI \-scale\  %g
Scale the output image by this factor
.SH SEE ALSO
.BR iconvert (1),
.BR igrep (1),
.BR iinfo (1),
.BR iv (1),
.BR maketx (1),
.BR oiiotool (1).
.SH AUTHOR
OpenImageIO was written by Larry Gritz and the other authors and contributors.
.PP
This manual page was written by IRIE Shinsuke <irieshinsuke@yahoo.co.jp>,
for the Debian project (and may be used by others).