diff options
Diffstat (limited to 'upstream/debian-unstable/man1/pamfunc.1')
| -rw-r--r-- | upstream/debian-unstable/man1/pamfunc.1 | 359 |
1 files changed, 359 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/pamfunc.1 b/upstream/debian-unstable/man1/pamfunc.1 new file mode 100644 index 00000000..ec39c381 --- /dev/null +++ b/upstream/debian-unstable/man1/pamfunc.1 @@ -0,0 +1,359 @@ +\ +.\" 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 "Pamfunc User Manual" 1 "09 September 2020" "netpbm documentation" + +.SH NAME +pamfunc - Apply a simple monadic arithmetic function to a Netpbm image + +.UN synopsis +.SH SYNOPSIS + +\fBpamfunc\fP +{ +\fB-multiplier=\fP\fIrealnum\fP | +\fB-divisor=\fP\fIrealnum\fP | +\fB-adder=\fP\fIinteger\fP | +\fB-subtractor=\fP\fIinteger\fP | +\fB-min=\fP\fIwholenum\fP | +\fB-max=\fP\fIwholenum\fP +\fB-andmask=\fP\fIhexmask\fP +\fB-ormask=\fP\fIhexmask\fP +\fB-xormask=\fP\fIhexmask\fP +\fB-not\fP +\fB-shiftleft=\fP\fIcount\fP +\fB-shiftright=\fP\fIcount\fP +[\fB-changemaxval\fP] +} +[\fIfilespec\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 +\fBpamfunc\fP reads a Netpbm image as input and produces a Netpbm +image as output, with the same format, and dimensions as the +input. \fBpamfunc\fP applies a simple transfer function to each +sample in the input to generate the corresponding sample in the +output. The options determine what function. +.PP +The samples involved are PAM samples. If the input is PBM, PGM, or PPM, +the output will be that same format, but \fBpamfunc\fP applies the functions +to the PAM equivalent samples, yielding PAM equivalent samples. This can +be nonintuitive in the +.UR #pbmoddness +PBM +.UE +\& case. + +.PP +\fBpamarith\fP is the same thing for binary functions -- it takes +two images as input and applies a specified simple arithmetic function +(e.g. addition) on pairs of samples from the two to produce the single +output image. + + +.UN values +.SS Values +.PP +The functions fall into two categories: arithmetic (such as multiply by 5) +and bit string (such as and with 01001000). For the arithmetic functions, the +function arguments and results are the fraction that a sample is of the +maxval, i.e. normal interpretation of PAM tuples. But for the bit string +functions, the value is the the bit string whose value as a binary cipher is +the sample value, and the maxval indicates the width of the bit string. + +.B Arithmetic functions +.PP +The arithmetic functions are those selected by the options +\fB-multiplier\fP, \fB-divisor\fP, \fB-adder\fP, \fB-subtractor\fP, +\fB-min\fP, and \fB-max\fP. +.PP +As an example, consider an image with maxval 100 and a sample value of 10 +and a function of "multiply by 5." The argument to the function is +10/100 (0.1) and the result is 5 * 0.1 = 0.5. In the simplest case, the +maxval of the output is also 100, so the output sample value is 0.5 * 100 = +50. As you can see, we could just talk about the sample values themselves +instead of these fractions and get the same result (10 * 5 = 50), but we +don't. +.PP +Where it makes a practical difference whether we consider the values to be +the fraction of the maxval or the sample value alone is where \fBpamfunc\fP +uses a different maxval in the output image than it finds in the input +image. See \fB-changemaxval\fP. +.PP +So remember in reading the descriptions below that the values are 0.1 and +0.5 in this example, not 10 and 50. All arguments and results are in the +range [0,1]. + +.B Bit string functions +.PP +The bit string functions are those selected by the options +\fB-andmask\fP, \fB-ormask\fP, \fB-xormask\fP, \fB-not\fP, +\fB-shiftleft\fP, and \fB-shiftright\fP. +.PP +With these functions, the maxval has a very different meaning than in +normal Netpbm images: it tells how wide (how many bits) 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. +.PP +As an example, consider an image with maxval 15 and a sample value of 5 +and a function of "and with 0100". The argument to the function is +0101 and the result is 0100. +.PP +In this example, it doesn't make any practical difference what we consider +the width of the string to be, as long as it is at least 3. If the maxval +were 255, the result would be the same. But with a bit shift operation, +it matters. Consider shifting left by 2 bits. In the example, where +the input value is 0101, the result is 0100. But if the maxval were 255, +the result would be 00010100. +.PP +For a masking function, the mask value you specify must not have +more significant bits than the width indicated by the maxval. +.PP +For a shifting operation, the shift count you specify must not be +greater than the width indicated by the maxval. + +.UN pbmoddness +.B PBM Oddness +.PP +If you're familiar with the PBM format, you may find \fBpamfunc\fP's +operation on PBM images to be nonintuitive. Because in PBM black is +represented as 1 and white as 0 (1.0 and 0.0 normlized), you might be +expecting adding 1 to white to yield black. +.PP +But the PBM format is irrelevant, because \fBpamfunc\fP operates on the +numbers found in the PAM equivalent (see above). In a PAM black and white +image, black is 0 and white is 1 (0.0 and 1.0 normalized). So white plus 1 +(clipped to the maximum of 1.0) is white. + + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBpamfunc\fP recognizes the following +command line options: + + +.TP +\fB-multiplier=\fIrealnum\fP\fP +.sp +This option makes the transfer function that of multiplying by + \fIrealnum\fP. \fIrealnum\fP must be nonnegative. If the result + is greater than one, it is clipped to one. +.sp +Where the input is a PGM or PPM image, this has the effect of + dimming or brightening it. For a different kind of brightening, + see +.BR "\fBpambrighten\fP" (1)\c +\& and +.BR "\fBppmflash\fP" (1)\c +\& +.sp +Also, see +.BR "\fBppmdim\fP" (1)\c +\&, which does the same + thing as \fBpamfunc -multiplier\fP on a PPM image with a multiplier + between zero and one, except it uses integer arithmetic, so it may be + faster. +.sp +And +.BR "\fBppmfade\fP" (1)\c +\& can generate a whole + sequence of images of brightness declining to black or increasing to + white, if that's what you want. + +.TP +\fB-divisor=\fIrealnum\fP\fP +.sp +This option makes the transfer function that of dividing by + \fIrealnum\fP. \fIrealnum\fP must be nonnegative. If the result + is greater than one, it is clipped to one. +.sp +This is the same function as you would get with \fB-multiplier\fP, + specifying the multiplicative inverse of \fIrealnum\fP. + +.TP +\fB-adder=\fIinteger\fP\fP +.sp +This option makes the transfer function that of adding + \fIinteger\fP/\fImaxval\fP. If the result is greater than one, it is + clipped to one. If it is less than zero, it is clipped to zero. +.sp +Note that in mathematics, this entity is called an "addend," + and an "adder" is a snake. We use "adder" because + it makes more sense. + +.TP +\fB-subtractor=\fIinteger\fP\fP +.sp +This option makes the transfer function that of subtracting + \fIinteger\fP/\fImaxval\fP. If the result is greater than one, it is + clipped to one. If it is less than zero, it is clipped to zero. +.sp +Note that in mathematics, this entity is called a + "subtrahend" rather than a "subtractor." We use + "subtractor" because it makes more sense. +.sp +This is the same function as you would get with \fB-adder\fP, + specifying the negative of \fIinteger\fP. + +.TP +\fB-min=\fIwholenum\fP\fP +.sp +This option makes the transfer function that of taking the maximum of + the argument and \fIwholenum\fP/\fImaxval\fP. I.e the minimum value in + the output will be \fIwholenum\fP/\fImaxval\fP. + + If \fIwholenum\fP/\fImaxval\fP is greater than one, though, every value + in the output will be one. + +.TP +\fB-max=\fIwholenum\fP\fP +.sp +This option makes the transfer function that of taking the minimum of + the argument and \fIwholenum\fP/\fImaxval\fP. I.e the maximum value in + the output will be \fIwholenum\fP/\fImaxval\fP. + + If \fIwholenum\fP/\fImaxval\fP is greater than one, the function is + idempotent -- the output is identical to the input. + +.TP +\fB-andmask=\fIhexmask\fP\fP +.sp +This option makes the transfer function that of bitwise anding + with \fIhexmask\fP. +.sp +\fIhexmask\fP is in hexadecimal. Example: \f(CW0f\fP +.sp +This option was new in Netpbm 10.40 (September 2007). + +.TP +\fB-ormask=\fIhexmask\fP\fP +.sp +This option makes the transfer function that of bitwise + inclusive oring with \fIhexmask\fP. +.sp +This is analogous to \fB-andmask\fP. +.sp +This option was new in Netpbm 10.40 (September 2007). + +.TP +\fB-xormask=\fIhexmask\fP\fP +.sp +This option makes the transfer function that of bitwise + exclusive oring with \fIhexmask\fP. +.sp +This is analogous to \fB-andmask\fP. +.sp +This option was new in Netpbm 10.40 (September 2007). + +.TP +\fB-not\fP +.sp +This option makes the transfer function that of bitwise logical + inversion (e.g. sample value 0xAA becomes 0x55). +.sp +\fBpnminvert\fP does the same thing for a bilevel visual image + which has maxval 1 or is of PBM type. +.sp +This option was new in Netpbm 10.40 (September 2007). + +.TP +\fB-shiftleft=\fIcount\fP\fP +.sp +This option makes the transfer function that of bitwise shifting + left by \fIcount\fP bits. +.sp +This option was new in Netpbm 10.40 (September 2007). + +.TP +\fB-shiftright=\fIcount\fP\fP +.sp +This option makes the transfer function that of bitwise shifting + right by \fIcount\fP bits. +.sp +This is analogous to \fB-shiftleft\fP. +.sp +This option was new in Netpbm 10.40 (September 2007). + +.TP +\fB-changemaxval\fP +.sp +This option tells \fBpamfunc\fP to use a different maxval in the output +image than the maxval of the input image, if it helps. By default, the maxval +of the output is unchanged from the input and \fBpamfunc\fP modifies the +sample values as necessary to perform the operation. +.sp +But there is one case where \fBpamfunc\fP can achieve the same result just +by changing the maxval and leaving the sample values unchanged: dividing by a +number 1 or greater, or multiplying by a number 1 or less. For example, to +halve all of the values, \fBpamfunc\fP can just double the maxval. +.sp +With \fB-changemaxval\fP, \fBpamfunc\fP will do just that. +.sp +As the Netpbm formats have a maximum maxval of 65535, for large divisors, +\fBpamfunc\fP may not be able to use this method. +.sp +An advantage of dividing by changing the maxval is that you don't lose +precision. The higher maxval means higher precision. For example, consider +an image with a maxval of 100 and sample value of 10. You divide by 21 and +then multiply by 21 again. If \fBpamfunc\fP does this by changing the sample +values while retaining maxval 100, the division will result in a sample value +of 0 and the multiplication will also result in zero. But if \fBpamfunc\fP +instead keeps the sample value 10 and changes the maxval, the division will +result in a maxval of 2100 and the multiplication will change it back to 100, +and the round trip is idempotent. +.sp +This option was new in Netpbm 10.65 (December 2013). + + + + +.UN seealso +.SH SEE ALSO +.BR "ppmdim" (1)\c +\&, +.BR "pambrighten" (1)\c +\&, +.BR "pamdepth" (1)\c +\&, +.BR "pamarith" (1)\c +\&, +.BR "pamsummcol" (1)\c +\&, +.BR "pamsumm" (1)\c +\&, +.BR "ppmfade" (1)\c +\&, +.BR "pnminvert" (1)\c +\&, +.BR "pam" (1)\c +\&, +.BR "pnm" (1)\c +\&, + +.UN history +.SH HISTORY +.PP +This program was added to Netpbm in Release 10.3 (June 2002). +.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/pamfunc.html +.PP
\ No newline at end of file |