| 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 "Pamarith User Manual" 1 "24 October 2020" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
pamarith - perform arithmetic on two Netpbm images |
| 10 |
|
| 11 |
.UN synopsis |
| 12 |
.SH SYNOPSIS |
| 13 |
|
| 14 |
\fBpamarith\fP |
| 15 |
\fB-add\fP | \fB-subtract\fP | \fB-multiply\fP | \fB-divide\fP | |
| 16 |
\fB-difference\fP | |
| 17 |
\fB-minimum\fP | \fB-maximum\fP | \fB-mean\fP | |
| 18 |
\fB-equal\fP | \fB-compare\fP | |
| 19 |
\fB-and\fP | \fB-or\fP | \fB-nand\fP | \fB-nor\fP | \fB-xor\fP | |
| 20 |
\fB-shiftleft\fP | \fB-shiftright\fP |
| 21 |
[\fB-closeness=\fP\fIN\fP] |
| 22 |
\fIpamfile1\fP \fIpamfile2\fP ... |
| 23 |
.PP |
| 24 |
All options can be abbreviated to their shortest unique prefix. |
| 25 |
You may use two hyphens instead of one. You may separate an option |
| 26 |
name and its value with white space instead of an equals sign. |
| 27 |
|
| 28 |
.UN description |
| 29 |
.SH DESCRIPTION |
| 30 |
.PP |
| 31 |
This program is part of |
| 32 |
.BR "Netpbm" (1)\c |
| 33 |
\&. |
| 34 |
.PP |
| 35 |
\fBpamarith\fP reads two or more PBM, PGM, PPM, or PAM images as input. |
| 36 |
It performs the specified binary arithmetic operation on their sample |
| 37 |
values and produces an output of a format which is the more general of |
| 38 |
the two input formats. The two input images must be of the same width |
| 39 |
and height. The arithmetic is performed on each pair of identically |
| 40 |
located tuples to generate the identically located tuple of the |
| 41 |
output. |
| 42 |
.PP |
| 43 |
For functions that are commutative and associative, \fBpamarith\fP applies |
| 44 |
the binary function repetitively on as many input images as you supply. For |
| 45 |
example, for \fB-add\fP , the output is the sum of all the inputs. For |
| 46 |
other functions (e.g. \fB-subtract\fP), the program fails if you supply |
| 47 |
more than two input images. (Before Netpbm 10.93 (December 2020), the |
| 48 |
program always failed with more than two input images). |
| 49 |
.PP |
| 50 |
For some other functions, \fBpamarith\fP could theoretically compute a |
| 51 |
meaningful result for multiple arguments, but it fails nonetheless if you |
| 52 |
give more than two input images. \fB-mean\fP and \fB-equal\fP are in that |
| 53 |
category. |
| 54 |
|
| 55 |
.PP |
| 56 |
Most of what \fBpamarith\fP does is not meaningful for visual images. It |
| 57 |
works toward Netpbm's secondary purpose of just manipulating arbitrary |
| 58 |
matrices of numbers. |
| 59 |
|
| 60 |
.PP |
| 61 |
For the purpose of the calculation, it assumes any PBM, PGM, or PPM |
| 62 |
input image is the equivalent PAM image of tuple type |
| 63 |
\fBBLACKANDWHITE\fP, \fBGRAYSCALE\fP, or \fBRGB\fP, respectively, |
| 64 |
and if it produces a PBM, PGM, or PPM output, produces the equivalent |
| 65 |
of the PAM image which is the result of the calculation. |
| 66 |
.PP |
| 67 |
The first \fIpamfile\fP argument identifies the "left" |
| 68 |
argument image; the second \fIpamfile\fP argument identifies the |
| 69 |
"right" one. |
| 70 |
.PP |
| 71 |
If the output is PAM, the tuple type is the same as the tuple type of |
| 72 |
the left input image. |
| 73 |
.PP |
| 74 |
\fBpamarith\fP performs the arithmetic on each pair of identically |
| 75 |
located tuples in the two input images. |
| 76 |
.PP |
| 77 |
The arithmetic operation is in all cases fundamentally a function from two |
| 78 |
integers to an integer (but see below - the functions are defined in ways that |
| 79 |
you can effectively e.g. add real numbers). The operation is performed on two |
| 80 |
tuples as follows. The two input images must have the same depth, or one of |
| 81 |
them must have depth one. \fBpamarith\fP fails if one of these is not the |
| 82 |
case. |
| 83 |
.PP |
| 84 |
If they have the same depth, \fBpamarith\fP simply carries out the |
| 85 |
arithmetic one sample at a time. I.e. if at a particular position the |
| 86 |
left input image contains the tuple (s1,s2,...,sN) and the right |
| 87 |
input image contains the tuple (t1,t2,...tN), and the function is f, |
| 88 |
then the output image contains the tuple |
| 89 |
(f(s1,t1),f(s2,t2),...,f(sN,tN)). |
| 90 |
.PP |
| 91 |
If one of the images has depth 1, the arithmetic is performed |
| 92 |
between the one sample in that image and each of the samples in the |
| 93 |
other. I.e. if at a particular position the left input image |
| 94 |
contains the tuple (s) and the right input image contains the tuple |
| 95 |
(t1,t2,...tN), and the function is f, then the output image contains |
| 96 |
the tuple (f(s,t1),f(s,t2),...,f(s,tN)). |
| 97 |
|
| 98 |
|
| 99 |
.UN pbmoddness |
| 100 |
.SS PBM Oddness |
| 101 |
.PP |
| 102 |
If you're familiar with the PBM format, you may find \fBpamarith\fP's |
| 103 |
operation on PBM images to be nonintuitive. Because in PBM black is |
| 104 |
represented as 1 and white as 0, you might be expecting black minus black |
| 105 |
to be white. |
| 106 |
.PP |
| 107 |
But the PBM format is irrelevant, because \fBpamarith\fP operates on the |
| 108 |
numbers found in the PAM equivalent (see above). In a PAM black and white |
| 109 |
image, black is 0 and white is 1. So black minus black is black. |
| 110 |
|
| 111 |
|
| 112 |
.UN maxval |
| 113 |
.SS Maxval |
| 114 |
.PP |
| 115 |
The meanings of the samples with respect to the maxval varies |
| 116 |
according to the function you select. |
| 117 |
.PP |
| 118 |
In PAM images in general, the most usual meaning of a sample (the |
| 119 |
one that applies when a PAM image represents a visual image), is that |
| 120 |
it represents a fraction of some maximum. The maxval of the image |
| 121 |
corresponds to some maximum value (in the case of a visual image, it |
| 122 |
corresponds to "full intensity."), and a sample value |
| 123 |
divided by the maxval gives the fraction. |
| 124 |
.PP |
| 125 |
For \fBpamarith\fP, this interpretation applies to the regular |
| 126 |
arithmetic functions: \fB-add\fP, \fB-subtract\fP, \fB-multiply\fP, |
| 127 |
\fB-divide\fP, |
| 128 |
\fB-difference\fP, \fB-minimum\fP, \fB-maximum\fP, \fB-mean\fP, |
| 129 |
\fB-equal\fP, |
| 130 |
and \fB-compare\fP. For those, you should think of the arguments and |
| 131 |
result as numbers in the range [0,1). For example, if the maxval of |
| 132 |
the left argument image is 100 and the maxval of the right argument |
| 133 |
image is 200 and the maxval of the output image is 200, and the left |
| 134 |
sample value in an \fB-add\fP calculation is 50 and the right sample |
| 135 |
is 60, the actual calculation is 50/100 + 60/200 = 160/200, and |
| 136 |
the output sample value is 160. |
| 137 |
.PP |
| 138 |
For these functions, \fBpamarith\fP makes the output image's |
| 139 |
maxval the maximum of the two input maxvals, except with |
| 140 |
\fB-equal \fP and \fB-compare\fP. For \fB-equal\fP, the output maxval is |
| 141 |
always 1. For \fB-compare\fP, it is always 2. (Before Netpbm 10.14 |
| 142 |
(February 2003), there was no exception for \fB-compare\fP; in 10.14, the |
| 143 |
exception was just that the maxval was \fIat least\fP 2, and sometime |
| 144 |
between 10.18 and 10.26 (January 2005), it changed to being exactly 2). |
| 145 |
.PP |
| 146 |
If the result of a calculation falls outside the range [0, 1), |
| 147 |
\fBpamarith\fP clips it -- i.e. considers it to be zero or 1-. |
| 148 |
.PP |
| 149 |
In many cases, where both your input maxvals are the same, you can |
| 150 |
just think of the operation as taking place between the sample values |
| 151 |
directly, with no consideration of the maxval except for the clipping. |
| 152 |
E.g. an \fB-add\fP of sample value 5 to sample value 8 yields sample |
| 153 |
value 13. |
| 154 |
.PP |
| 155 |
But with \fB-multiply\fP, this doesn't work. Say your two input |
| 156 |
images have maxval 255, which means the output image also has maxval |
| 157 |
255. Consider a location in the image where the input sample values |
| 158 |
are 5 and 10. You might think the multiplicative product of those |
| 159 |
would yield 50 in the output. But \fBpamarith\fP carries out the |
| 160 |
arithmetic on the fractions 5/255 and 10/255. It multiplies those |
| 161 |
together and then rescales to the output maxval, giving a sample value |
| 162 |
in the output PAM of 50/255 rounded to the nearest integer: 0. |
| 163 |
.PP |
| 164 |
With the bit string operations, the maxval has a whole different |
| 165 |
meaning. The operations in question are: \fB-and\fP, \fB-or\fP, |
| 166 |
\fB-nand\fP, \fB-nor\fP, \fB-xor\fP, and \fB-shiftleft\fP, |
| 167 |
\fB-shiftright\fP. |
| 168 |
.PP |
| 169 |
With these, each sample value in one or both input images, and in |
| 170 |
the output image, represents a bit string, not a number. The maxval |
| 171 |
tells how wide the bit string is. The maxval must be a full binary |
| 172 |
count (a power of two minus one, such as 0xff) and the number of ones |
| 173 |
in it is the width of the bit string. For the dyadic bit string |
| 174 |
operations (that's everything but the shift functions), the maxvals of |
| 175 |
the input images must be the same and \fBpamarith\fP makes the maxval |
| 176 |
of the output image the same. |
| 177 |
.PP |
| 178 |
For the bit shift operations, the output maxval is the same as the |
| 179 |
left input maxval. The right input image (which contains the shift |
| 180 |
counts) can have any maxval and the maxval is irrelevant to the |
| 181 |
interpretation of the samples. The sample value is the actual shift |
| 182 |
count. But it's still required that no sample value exceed the |
| 183 |
maxval. |
| 184 |
|
| 185 |
|
| 186 |
.UN note |
| 187 |
.SH NOTE: UNARY FUNCTIONS |
| 188 |
.PP |
| 189 |
\fBpamarith\fP applies only binary functions. If you want to apply a |
| 190 |
unary function, e.g. "halve", to a single image, use \fBpamfunc\fP. |
| 191 |
|
| 192 |
|
| 193 |
.UN options |
| 194 |
.SH OPTIONS |
| 195 |
.PP |
| 196 |
In addition to the options common to all programs based on libnetpbm |
| 197 |
(most notably \fB-quiet\fP, see |
| 198 |
.UR index.html#commonoptions |
| 199 |
Common Options |
| 200 |
.UE |
| 201 |
\&), \fBpamarith\fP recognizes the following |
| 202 |
command line options: |
| 203 |
|
| 204 |
.UN function |
| 205 |
.SS The Function |
| 206 |
.PP |
| 207 |
These options select the function that \fBpamarith\fP applies. |
| 208 |
.PP |
| 209 |
You must specify one of these, and cannot specify more than one. |
| 210 |
|
| 211 |
|
| 212 |
|
| 213 |
.TP |
| 214 |
\fB-add\fP |
| 215 |
Adds the two values. If the result is larger than maxval, it is |
| 216 |
clipped. |
| 217 |
|
| 218 |
.TP |
| 219 |
\fB-subtract\fP |
| 220 |
Subtracts a value in the right input image from a value in the left input |
| 221 |
image. |
| 222 |
|
| 223 |
.TP |
| 224 |
\fB-minimum\fP |
| 225 |
Chooses the smaller value of the two. |
| 226 |
|
| 227 |
.TP |
| 228 |
\fB-maximum\fP |
| 229 |
Chooses the larger value of the two. |
| 230 |
|
| 231 |
.TP |
| 232 |
\fB-difference\fP |
| 233 |
Calculates the absolute value of the difference. |
| 234 |
|
| 235 |
.TP |
| 236 |
\fB-multiply\fP |
| 237 |
Does an ordinary arithmetic multiplication, but tends to produce |
| 238 |
nonobvious results because of the way \fBpamarith\fP interprets |
| 239 |
sample values. See |
| 240 |
.UR #maxval |
| 241 |
Maxval |
| 242 |
.UE |
| 243 |
\&. |
| 244 |
|
| 245 |
.TP |
| 246 |
\fB-divide\fP |
| 247 |
Divides a value in the left input image by the value in the right |
| 248 |
input image. But like \fB-multiply\fP, it tends to produce nonobvious |
| 249 |
results. Note that \fBpamarith\fP clipping behavior makes this of |
| 250 |
little use when the left argument (dividend) is greater than the right |
| 251 |
argument (divisor) -- the result in that case is always the maxval. |
| 252 |
If the divisor is 0, the result is the maxval. |
| 253 |
.sp |
| 254 |
\fB-divide\fP was new in Netpbm 10.30 (October 2005). |
| 255 |
|
| 256 |
.TP |
| 257 |
\fB-equal\fP |
| 258 |
Produces maxval when the values in the two images are equal and |
| 259 |
zero when they are not. Note that the output maxval is always 1 for |
| 260 |
\fB-equal\fP. |
| 261 |
.sp |
| 262 |
If the maxvals of the input images are not identical, \fBpamarith\fP may |
| 263 |
claim two values are not equal when in fact they are, because of the precision |
| 264 |
with which it does the arithmetic. |
| 265 |
.sp |
| 266 |
You can make the equality test approximate with the \fB-closeness\fP |
| 267 |
option. This gives the percentage of maxval by which the samples can |
| 268 |
differ and still be considered equal. |
| 269 |
.sp |
| 270 |
\fB-equal\fP was new in Netpbm 10.93 (December 2020). |
| 271 |
|
| 272 |
.TP |
| 273 |
\fB-compare\fP |
| 274 |
Produces the value \fB0\fP when the value in the |
| 275 |
left input image is less than the value in the right input image, |
| 276 |
\fB1\fP when the values are equal, and \fB2\fP when the left is |
| 277 |
greater than the right. |
| 278 |
.sp |
| 279 |
If the maxvals of the input images are not identical, \fBpamarith\fP |
| 280 |
may claim two values are not equal when in fact they are, because of |
| 281 |
the precision with which it does the arithmetic. However, it will never |
| 282 |
say A is greater than B if A is less than B. |
| 283 |
.sp |
| 284 |
\fB-compare\fP was new in Netpbm 10.13 (December 2002). |
| 285 |
|
| 286 |
.TP |
| 287 |
\fB-and\fP, \fB-nand\fP, \fB-or\fP, \fB-nor\fP, \fB-xor\fP |
| 288 |
These consider the input and output images to contain bit strings; |
| 289 |
they compute bitwise logic operations. Note that if the maxval is 1, |
| 290 |
you can also look at these as logic operations on boolean input values. |
| 291 |
See section |
| 292 |
.UR #maxval |
| 293 |
Maxval |
| 294 |
.UE |
| 295 |
\& for the special meaning of |
| 296 |
maxval with respect to bit string operations such as these. |
| 297 |
|
| 298 |
.TP |
| 299 |
\fB-shiftleft\fP, \fB-shiftright\fP |
| 300 |
These consider the left input image and output image to contain |
| 301 |
bit strings. They compute a bit shift operation, with bits falling |
| 302 |
off the left or right end and zeroes shifting in, as opposed to bits |
| 303 |
off one end to the other. The right input image sample value is the |
| 304 |
number of bit positions to shift. |
| 305 |
.sp |
| 306 |
Note that the maxval (see |
| 307 |
.UR #maxval |
| 308 |
Maxval |
| 309 |
.UE |
| 310 |
\&) determines |
| 311 |
the width of the frame within which you are shifting. |
| 312 |
|
| 313 |
|
| 314 |
|
| 315 |
.UN otheroptions |
| 316 |
.SS Other |
| 317 |
|
| 318 |
|
| 319 |
|
| 320 |
.TP |
| 321 |
\fB-closeness\fP |
| 322 |
This changes the meaning of \fB-equal\fP. It is not valid with any |
| 323 |
other function. See the description of \fB-equal\fP. |
| 324 |
|
| 325 |
|
| 326 |
|
| 327 |
.UN seealso |
| 328 |
.SH SEE ALSO |
| 329 |
.BR "\fBpamfunc\fP" (1)\c |
| 330 |
\&, |
| 331 |
.BR "\fBpamsummcol\fP" (1)\c |
| 332 |
\&, |
| 333 |
.BR "\fBpamsumm\fP" (1)\c |
| 334 |
\&, |
| 335 |
.BR "\fBpnminvert\fP" (1)\c |
| 336 |
\&, |
| 337 |
.BR "\fBpambrighten\fP" (1)\c |
| 338 |
\&, |
| 339 |
.BR "\fBppmdim\fP" (1)\c |
| 340 |
\&, |
| 341 |
.BR "\fBpnmconvol\fP" (1)\c |
| 342 |
\&, |
| 343 |
.BR "\fBpamdepth\fP" (1)\c |
| 344 |
\&, |
| 345 |
.BR "\fBpnmpsnr\fP" (1)\c |
| 346 |
\&, |
| 347 |
.BR "\fBpnm\fP" (1)\c |
| 348 |
\&, |
| 349 |
.BR "\fBpam\fP" (1)\c |
| 350 |
\& |
| 351 |
|
| 352 |
|
| 353 |
.UN history |
| 354 |
.SH HISTORY |
| 355 |
.PP |
| 356 |
\fBpamarith\fP replaced \fBpnmarith\fP in Netpbm 10.3 (June 2002). |
| 357 |
.PP |
| 358 |
In Netpbm 10.3 through 10.8, though, \fBpamarith\fP was not |
| 359 |
backward compatible because it required the input images to be of the |
| 360 |
same depth, so you could not multiply a PBM by a PPM as is often done |
| 361 |
for masking. (It was not intended at the time that \fBpnmarith\fP |
| 362 |
would be removed from Netpbm -- the plan was just to rewrite it to use |
| 363 |
\fBpamarith\fP; it was removed by mistake). |
| 364 |
.PP |
| 365 |
But starting with Netpbm 10.9 (September 2002), \fBpamarith\fP allows |
| 366 |
the images to have different depths as long as one of them has depth 1, and |
| 367 |
that made it backward compatible with \fBpnmarith\fP. |
| 368 |
.PP |
| 369 |
The original \fBpnmarith\fP did not have the \fB-mean\fP option. |
| 370 |
.PP |
| 371 |
The \fB-compare\fP option was added in Netpbm 10.13 (December 2002). |
| 372 |
.PP |
| 373 |
The bit string operations were added in Netpbm 10.27 (March 2005). |
| 374 |
.PP |
| 375 |
The \fB-divide\fP option was added in Netpbm 10.30 (October 2005). |
| 376 |
.PP |
| 377 |
The ability to have more than one input (operand) was added in Netpbm |
| 378 |
10.93 (December 2020). |
| 379 |
.PP |
| 380 |
The \fB-equal\fP option was added in Netpbm 10.93 (December 2020). |
| 381 |
.SH DOCUMENT SOURCE |
| 382 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 383 |
source. The master documentation is at |
| 384 |
.IP |
| 385 |
.B http://netpbm.sourceforge.net/doc/pamarith.html |
| 386 |
.PP |