Debian Codegraph @

upstream/debian-unstable/man1/pnmpsnr.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pnmpsnr User Manual" 1 "06 January 2018" "netpbm documentation"
7
8 .SH NAME
9 pnmpsnr - compute the difference between two images (the PSNR)
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpnmpsnr\fP
15
16 [\fIpnmfile1\fP]
17
18 [\fIpnmfile2\fP]
19
20 [\fB-rgb\fP]
21 [\fB-machine\fP]
22 [\fB-max=\fP\fIn\fP]
23 [\fB-target=\fP\fIn\fP]
24 [\fB-target1=\fP\fIn\fP]
25 [\fB-target2=\fP\fIn\fP]
26 [\fB-target3=\fP\fIn\fP]
27 .PP
28 Minimum unique abbreviations of options are acceptable. You may use
29 double hyphens instead of single hyphen to denote options. You may use
30 white space in place of the equals sign to separate an option name
31 from its value.
32
33
34 .UN description
35 .SH DESCRIPTION
36 .PP
37 This program is part of
38 .BR "Netpbm" (1)\c
39 \&.
40 .PP
41 \fBpnmpsnr\fP reads two PBM, PGM, or PPM files, or PAM equivalents, as
42 input and computes the magnitude of difference between the two images as a peak
43 signal-to-noise ratio (PSNR) This metric is typically used in image
44 compression papers to rate the distortion between original and decoded image.
45 .PP
46 \fBpnmpsnr\fP either prints these values or compares them to thresholds
47 you specify.
48
49 .PP
50 The PSNR of a given component is the ratio of the maximum mean square
51 difference of component values that could exist between the two images (a
52 measure of the information content in an image) to the actual mean square
53 difference for the two subject images. It is expressed as a decibel value.
54 .PP
55 The mean square difference of a component for two images is the
56 mean square difference of the component value, comparing each pixel
57 with the pixel in the same position of the other image. For the
58 purposes of this computation, components are normalized to the scale
59 [0..1].
60 .PP
61 The maximum mean square difference is identically 1.
62 .PP
63 So the higher the PSNR, the closer the images are. A luminance
64 PSNR of 20 means the mean square difference of the luminances of the
65 pixels is 100 times less than the maximum possible difference,
66 i.e. 0.01.
67 .PP
68 Note that the word "peak" is a misnomer; there is no maximum involved; the
69 metric is a mean. But "peak signal to noise ratio" is for some reason the
70 common term for this measurement.
71 .PP
72 If the inputs are PBM or PGM, \fBpnmpsnr\fP computes the PSNR of the
73 luminance only. Otherwise, it computes three separate PSNRs: either the
74 luminance, and chrominance (Cb and Cr) components of the colors or the
75 red, green, and blue components.
76 .PP
77 By default, the program prints the PSNRs to Standard Output in
78 human-friendly form.
79 .PP
80 With the \fB-machine\fP option, the program prints the PSNRs, but
81 in machine-friendly form.
82 .PP
83 With a \fB-target\fP[\fIx\fP] option, the program just prints
84 \&'match' or 'nomatch', depending on whether the PSNRs
85 exceed targets you specify.
86
87 .PP
88 \fBpnmpsnr\fP reports the PSNR either in human-friendly form or in
89 machine-friendly form (see \fB-machine\fP).
90
91
92 .UN options
93 .SH OPTIONS
94 .PP
95 In addition to the options common to all programs based on libnetpbm
96 (most notably \fB-quiet\fP, see
97 .UR index.html#commonoptions
98 Common Options
99 .UE
100 \&), \fBpnmpsnr\fP recognizes the following
101 command line options:
102
103
104 .TP
105 \fB-rgb\fP
106 This option causes \fBpnmpsnr\fP to compare the red, green, and blue
107 components of the color rather than the luminance and chrominance components.
108 It has no effect on a monotone image.
109 .sp
110 This option was new in Netpbm 10.71 (June 2015).
111
112 .TP
113 \fB-machine\fP
114 This option causes \fBpnmpsnr\fP to report the PSNRs in machine-friendly
115 form, so another program can easily use the information.
116 .sp
117 The output is a single line. It contains one floating point decimal number
118 for each color component, with a single space between every two. (This means
119 there are either 1 or 3 numbers). For the YCbCr color space (no \fB-rgb\fP),
120 they are in the order Y, Cb, Cr. For the RGB color space (\fB-rgb\fP), they
121 are in R, G, B order. For a monotone image, there is one number.
122 .sp
123 Where the component does not differ between the images, so the PSNR is
124 infinite, the number is \fBinf\fP
125 .sp
126 But note that the number displayed is also modified by the effect of
127 \fB-max\fP. In particular, with \fB-max\fP, you will never see \fBinf\fP.
128 .sp
129 This option has no effect when you also specify \fB-target\fP[\fIn\fP].
130 .sp
131 This option was new in Netpbm 10.74 (March 2016).
132
133 .TP
134 \fB-max=\fP\fIn\fP
135 This is meaningful only with \fB-machine\fP.
136 .sp
137 It specifies the maximum number \fBpnmpsnr\fP will print as a PSNR.
138 If the PSNR is greater than \fIn\fP, \fBpnmpsnr\fP just prints \fIn\fP.
139 \fIn\fP is a decimal floating point number. An infinite PSNR is considered
140 greater than any number.
141 .sp
142 This is mainly useful to deal with infinite PSNRs. It is often much more
143 convenient to have a program process only numbers than to make it deal with
144 infinity, and often a very large number has the same effect on a program as
145 infinity.
146 .sp
147 Note that the output is logarithmic, which means you will not see really
148 large but finite numbers. If you specify \fB-max=1000\fP, the only way you
149 will see 1000 in the output is if the PSNR is really infinite. Two images
150 with as many pixels as there are electrons in the universe, differing in only
151 one pixel, and only in the smallest amount representable in the Netpbm format,
152 have a PSNR less than 1000.
153 .sp
154 This option was new in Netpbm 10.74 (March 2016).
155
156 .TP
157 \fB-target\fP=\fIn\fP
158
159 This option causes \fBpnmpsnr\fP to run in comparison mode - rather than
160 print the PSNRs, it just tells you whether the PSNRs exceed
161 \fIn\fP (a floating point number), i.e. whether the compared images are the
162 same within a given margin of error. If all the computed PSNRs (luminance for
163 a PBM or PGM; luminance and chrominance or red, green, and blue for PPM)
164 exceed \fIn\fP, the program prints 'match' to Standard Output.
165 Otherwise, it prints 'nomatch'.
166 .sp
167 If you also specify any of \fB-target1\fP, \fB-target2\fP, or
168 \fB-target3\fP, and the images are color, \fBpnmpsnr\fP ignores
169 \fB-target\fP.
170 .sp
171 This is mainly useful for use in a program. If you're
172 running \fBpnmpsnr\fP manually, you could just run \fBpnmpsnr\fP
173 without \fB-target\fP and compare the PSNRs to your targets yourself.
174 .sp
175 This option was new in Netpbm 10.82 (March 2018).
176
177 .TP
178 \fB-target\fP{\fB1\fP,\fB2\fP,\fB3\fP}=\fIn\fP
179 Like \fB-target\fP, these options cause \fBpnmpsnr\fP to run in comparison
180 mode. But they provide separate targets for the individual color component
181 PSNRs. \fB-target1\fP, \fBtarget-2\fP, and \fB-target3\fP are for either
182 the Y, Cb, and Cr components, respectively, or the red, green, and blue
183 components, respectively, depending upon whether you specified \fB-rgb\fP.
184 .sp
185 If you don't specify the corresponding \fB-target\fP\fIn\fP option for a
186 component, \fBpnmpsnr\fP ignores the PSNR of that component in deciding
187 whether the images match.
188 .sp
189 If the image is a PBM or PGM, these options have no effect, except that it
190 stilll selects comparison mode, so if you don't \fIalso\fP
191 specify \fB-target\fP, and the image is PBM or PGM, the program fails.
192 .sp
193 Note that the options are defined so that you could code a
194 \fBpnmpsnr\fP command in a program that works on both color and monotone
195 images, specifying individual PSNR targets for use on the color images and the
196 single target for use on the monotone images.
197 .sp
198 These options were new in Netpbm 10.82 (March 2018).
199
200
201
202
203 .UN seealso
204 .SH SEE ALSO
205 .BR "pnm" (1)\c
206 \&
207 .SH DOCUMENT SOURCE
208 This manual page was generated by the Netpbm tool 'makeman' from HTML
209 source. The master documentation is at
210 .IP
211 .B http://netpbm.sourceforge.net/doc/pnmpsnr.html
212 .PP