diff options
Diffstat (limited to 'upstream/opensuse-leap-15-6/man1/pamarith.1')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man1/pamarith.1 | 275 |
1 files changed, 275 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man1/pamarith.1 b/upstream/opensuse-leap-15-6/man1/pamarith.1 new file mode 100644 index 00000000..7f8acdcc --- /dev/null +++ b/upstream/opensuse-leap-15-6/man1/pamarith.1 @@ -0,0 +1,275 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Pamarith User Manual" 0 "03 January 2015" "netpbm documentation" + +.SH NAME +pamarith - perform arithmetic on two Netpbm images + +.UN synopsis +.SH SYNOPSIS + +\fBpamarith\fP +\fB-add\fP | \fB-subtract\fP | \fB-multiply\fP | \fB-divide\fP | +\fB-difference\fP | +\fB-minimum\fP | \fB-maximum\fP | \fB-mean\fP | \fB-compare\fP | +\fB-and\fP | \fB-or\fP | \fB-nand\fP | \fB-nor\fP | \fB-xor\fP | +\fB-shiftleft\fP | \fB-shiftright\fP +\fIpamfile1\fP \fIpamfile2\fP +.PP +All options can be abbreviated to their shortest unique prefix. +You may use two hyphens instead of one. You may separate an option +name and its value with white space instead of an equals sign. + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBpamarith\fP reads two PBM, PGM, PPM, or PAM images as input. +It performs the specified binary arithmetic operation on their sample +values and produces an output of a format which is the more general of +the two input formats. The two input images must be of the same width +and height. The arithmetic is performed on each pair of identically +located tuples to generate the identically located tuple of the +output. +.PP +For the purpose of the calculation, it assumes any PBM, PGM, or PPM +input image is the equivalent PAM image of tuple type +\fBBLACKANDWHITE\fP, \fBGRAYSCALE\fP, or \fBRGB\fP, respectively, +and if it produces a PBM, PGM, or PPM output, produces the equivalent +of the PAM image which is the result of the calculation. +.PP +The first \fIpamfile\fP argument identifies the "left" +argument image; the second \fIpamfile\fP argument identifies the +"right" one. +.PP +If the output is PAM, the tuple type is the same as the tuple type of +the left input image. +.PP +\fBpamarith\fP performs the arithmetic on each pair of identically +located tuples in the two input images. +.PP +The arithmetic operation is in all cases fundamentally a function from two +integers to an integer (but see below - the functions are defined in ways that +you can effectively e.g. add real numbers). The operation is performed on two +tuples as follows. The two input images must have the same depth, or one of +them must have depth one. \fBpamarith\fP fails if one of these is not the +case. +.PP +If they have the same depth, \fBpamarith\fP simply carries out the +arithmetic one sample at a time. I.e. if at a particular position the +left input image contains the tuple (s1,s2,...,sN) and the right +input image contains the tuple (t1,t2,...tN), and the function is f, +then the output image contains the tuple +(f(s1,t1),f(s2,t2),...,f(sN,tN)). +.PP +If one of the images has depth 1, the arithmetic is performed +between the one sample in that image and each of the samples in the +other. I.e. if at a particular position the left input image +contains the tuple (s) and the right input image contains the tuple +(t1,t2,...tN), and the function is f, then the output image contains +the tuple (f(s,t1),f(s,t2),...,f(s,tN)). + +.UN maxval +.SS Maxval +.PP +The meanings of the samples with respect to the maxval varies +according to the function you select. +.PP +In PAM images in general, the most usual meaning of a sample (the +one that applies when a PAM image represents a visual image), is that +it represents a fraction of some maximum. The maxval of the image +corresponds to some maximum value (in the case of a visual image, it +corresponds to "full intensity."), and a sample value +divided by the maxval gives the fraction. +.PP +For \fBpamarith\fP, this interpretation applies to the regular +arithmetic functions: \fB-add\fP, \fB-subtract\fP, \fB-multiply\fP, +\fB-divide\fP, +\fB-difference\fP, \fB-minimum\fP, \fB-maximum\fP, \fB-mean\fP, +and \fB-compare\fP. For those, you should think of the arguments and +result as numbers in the range [0,1). For example, if the maxval of +the left argument image is 100 and the maxval of the right argument +image is 200 and the maxval of the output image is 200, and the left +sample value in an \fB-add\fP calculation is 50 and the right sample +is 60, the actual calculation is 50/100 + 60/200 = 160/200, and +the output sample value is 160. +.PP +For these functions, \fBpamarith\fP makes the output image's +maxval the maximum of the two input maxvals, except with +\fB-compare\fP, where \fBpamarith\fP uses an output maxval of 2. +(Before Netpbm 10.14 (February 2003), there was no exception for +\fB-compare\fP; in 10.14, the exception was just that the maxval +was \fIat least\fP 2, and sometime between 10.18 and 10.26 (January +2005), it changed to being exactly 2). +.PP +If the result of a calculation falls outside the range [0, 1), +\fBpamarith\fP clips it -- i.e. considers it to be zero or 1-. +.PP +In many cases, where both your input maxvals are the same, you can +just think of the operation as taking place between the sample values +directly, with no consideration of the maxval except for the clipping. +E.g. an \fB-add\fP of sample value 5 to sample value 8 yields sample +value 13. +.PP +But with \fB-multiply\fP, this doesn't work. Say your two input +images have maxval 255, which means the output image also has maxval +255. Consider a location in the image where the input sample values +are 5 and 10. You might think the multiplicative product of those +would yield 50 in the output. But \fBpamarith\fP carries out the +arithmetic on the fractions 5/255 and 10/255. It multiplies those +together and then rescales to the output maxval, giving a sample value +in the output PAM of 50/255 rounded to the nearest integer: 0. +.PP +With the bit string operations, the maxval has a whole different +meaning. The operations in question are: \fB-and\fP, \fB-or\fP, +\fB-nand\fP, \fB-nor\fP, \fB-xor\fP, and \fB-shiftleft\fP, +\fB-shiftright\fP. +.PP +With these, each sample value in one or both input images, and in +the output image, represents a bit string, not a number. The maxval +tells how wide the bit string is. The maxval must be a full binary +count (a power of two minus one, such as 0xff) and the number of ones +in it is the width of the bit string. For the dyadic bit string +operations (that's everything but the shift functions), the maxvals of +the input images must be the same and \fBpamarith\fP makes the maxval +of the output image the same. +.PP +For the bit shift operations, the output maxval is the same as the +left input maxval. The right input image (which contains the shift +counts) can have any maxval and the maxval is irrelevant to the +interpretation of the samples. The sample value is the actual shift +count. But it's still required that no sample value exceed the +maxval. + +.UN operations +.SS The Operations +.PP +Most of the operations are obvious from the option name. The following +paragraphs cover those that aren't. +.PP +\fB-subtract\fP subtracts a value in the right input image from a +value in the left input image. +.PP +\fB-difference\fP calculates the absolute value of +the difference. +.PP +\fB-multiply\fP does an ordinary arithmetic multiplication, but +tends to produce nonobvious results because of the way \fBpamarith\fP +interprets sample values. See +.UR #maxval +Maxval +.UE +\&. +.PP +\fB-divide\fP divides a value in the left input image by the value +in the right input image. But like \fB-multiply\fP, it tends to +produce nonobvious results. Note that \fBpamarith\fP clipping +behavior makes this of little use when the left argument (dividend) is +greater than the right argument (divisor) -- the result in that case +is always the maxval. If the divisor is 0, the result is the maxval. +This option was new in Netpbm 10.30 (October 2005). +.PP +\fB-compare\fP produces the value \fB0\fP when the value in the +left input image is less than the value in the right input image, +\fB1\fP when the values are equal, and \fB2\fP when the left is +greater than the right. +.PP +If the maxvals of the input images are not identical, \fBpamarith\fP +may claim two values are not equal when in fact they are, because of +the precision with which it does the arithmetic. However, it will never +say A is greater than B if A is less than B. +.PP +\fB-compare\fP was new in Netpbm 10.13 (December 2002). +.PP +\fB-and\fP, \fB-nand\fP, \fB-or\fP, \fB-nor\fP, and \fB-xor\fP +consider the input and output images to contain bit strings; they +compute bitwise logic operations. Note that if the maxval is 1, you +can also look at these as logic operations on boolean input values. +See section +.UR #maxval +Maxval +.UE +\& for the special meaning of +maxval with respect to bit string operations such as these. +.PP +\fB-shiftleft\fP and \fB-shiftright\fP consider the left input +image and output image to contain bit strings. They compute a bit +shift operation, with bits falling off the left or right end and +zeroes shifting in, as opposed to bits off one end to the other. The +right input image sample value is the number of bit positions to +shift. +.PP +Note that the maxval (see +.UR #maxval +Maxval +.UE +\&) determines +the width of the frame within which you are shifting. + +.UN notes +.SS Notes +.PP +If you want to apply a unary function, e.g. "halve", to a single +image, use \fBpamfunc\fP. + +.UN seealso +.SH SEE ALSO +.BR "\fBpamfunc\fP" (1)\c +\&, +.BR "\fBpamsummcol\fP" (1)\c +\&, +.BR "\fBpamsumm\fP" (1)\c +\&, +.BR "\fBpnminvert\fP" (1)\c +\&, +.BR "\fBppmbrighten\fP" (1)\c +\&, +.BR "\fBppmdim\fP" (1)\c +\&, +.BR "\fBpnmconvol\fP" (1)\c +\&, +.BR "\fBpamdepth\fP" (1)\c +\&, +.BR "\fBpnmpsnr\fP" (1)\c +\&, +.BR "pnm" (5)\c +\&, +.BR "pam" (5)\c +\& + + +.UN history +.SH HISTORY +.PP +\fBpamarith\fP replaced \fBpnmarith\fP in Netpbm 10.3 (June 2002). +.PP +In Netpbm 10.3 through 10.8, though, \fBpamarith\fP was not +backward compatible because it required the input images to be of the +same depth, so you could not multiply a PBM by a PPM as is often done +for masking. (It was not intended at the time that \fBpnmarith\fP +would be removed from Netpbm -- the plan was just to rewrite it to use +\fBpamarith\fP; it was removed by mistake). +.PP +But starting with Netpbm 10.9 (September 2002), \fBpamarith\fP allows +the images to have different depths as long as one of them has depth 1, and +that made it backward compatible with \fBpnmarith\fP. +.PP +The original \fBpnmarith\fP did not have the \fB-mean\fP option. +.PP +The \fB-compare\fP option was added in Netpbm 10.13 (December 2002). +.PP +The bit string operations were added in Netpbm 10.27 (March 2005). +.PP +The \fB-divide\fP option was added in Netpbm 10.30 (October 2005). +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pamarith.html +.PP
\ No newline at end of file |