| 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 "Pamfunc User Manual" 1 "09 September 2020" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
pamfunc - Apply a simple monadic arithmetic function to a Netpbm image |
| 10 |
|
| 11 |
.UN synopsis |
| 12 |
.SH SYNOPSIS |
| 13 |
|
| 14 |
\fBpamfunc\fP |
| 15 |
{ |
| 16 |
\fB-multiplier=\fP\fIrealnum\fP | |
| 17 |
\fB-divisor=\fP\fIrealnum\fP | |
| 18 |
\fB-adder=\fP\fIinteger\fP | |
| 19 |
\fB-subtractor=\fP\fIinteger\fP | |
| 20 |
\fB-min=\fP\fIwholenum\fP | |
| 21 |
\fB-max=\fP\fIwholenum\fP |
| 22 |
\fB-andmask=\fP\fIhexmask\fP |
| 23 |
\fB-ormask=\fP\fIhexmask\fP |
| 24 |
\fB-xormask=\fP\fIhexmask\fP |
| 25 |
\fB-not\fP |
| 26 |
\fB-shiftleft=\fP\fIcount\fP |
| 27 |
\fB-shiftright=\fP\fIcount\fP |
| 28 |
[\fB-changemaxval\fP] |
| 29 |
} |
| 30 |
[\fIfilespec\fP] |
| 31 |
.PP |
| 32 |
All options can be abbreviated to their shortest unique prefix. |
| 33 |
You may use two hyphens instead of one. You may separate an option |
| 34 |
name and its value with white space instead of an equals sign. |
| 35 |
|
| 36 |
.UN description |
| 37 |
.SH DESCRIPTION |
| 38 |
.PP |
| 39 |
This program is part of |
| 40 |
.BR "Netpbm" (1)\c |
| 41 |
\&. |
| 42 |
.PP |
| 43 |
\fBpamfunc\fP reads a Netpbm image as input and produces a Netpbm |
| 44 |
image as output, with the same format, and dimensions as the |
| 45 |
input. \fBpamfunc\fP applies a simple transfer function to each |
| 46 |
sample in the input to generate the corresponding sample in the |
| 47 |
output. The options determine what function. |
| 48 |
.PP |
| 49 |
The samples involved are PAM samples. If the input is PBM, PGM, or PPM, |
| 50 |
the output will be that same format, but \fBpamfunc\fP applies the functions |
| 51 |
to the PAM equivalent samples, yielding PAM equivalent samples. This can |
| 52 |
be nonintuitive in the |
| 53 |
.UR #pbmoddness |
| 54 |
PBM |
| 55 |
.UE |
| 56 |
\& case. |
| 57 |
|
| 58 |
.PP |
| 59 |
\fBpamarith\fP is the same thing for binary functions -- it takes |
| 60 |
two images as input and applies a specified simple arithmetic function |
| 61 |
(e.g. addition) on pairs of samples from the two to produce the single |
| 62 |
output image. |
| 63 |
|
| 64 |
|
| 65 |
.UN values |
| 66 |
.SS Values |
| 67 |
.PP |
| 68 |
The functions fall into two categories: arithmetic (such as multiply by 5) |
| 69 |
and bit string (such as and with 01001000). For the arithmetic functions, the |
| 70 |
function arguments and results are the fraction that a sample is of the |
| 71 |
maxval, i.e. normal interpretation of PAM tuples. But for the bit string |
| 72 |
functions, the value is the the bit string whose value as a binary cipher is |
| 73 |
the sample value, and the maxval indicates the width of the bit string. |
| 74 |
|
| 75 |
.B Arithmetic functions |
| 76 |
.PP |
| 77 |
The arithmetic functions are those selected by the options |
| 78 |
\fB-multiplier\fP, \fB-divisor\fP, \fB-adder\fP, \fB-subtractor\fP, |
| 79 |
\fB-min\fP, and \fB-max\fP. |
| 80 |
.PP |
| 81 |
As an example, consider an image with maxval 100 and a sample value of 10 |
| 82 |
and a function of "multiply by 5." The argument to the function is |
| 83 |
10/100 (0.1) and the result is 5 * 0.1 = 0.5. In the simplest case, the |
| 84 |
maxval of the output is also 100, so the output sample value is 0.5 * 100 = |
| 85 |
50. As you can see, we could just talk about the sample values themselves |
| 86 |
instead of these fractions and get the same result (10 * 5 = 50), but we |
| 87 |
don't. |
| 88 |
.PP |
| 89 |
Where it makes a practical difference whether we consider the values to be |
| 90 |
the fraction of the maxval or the sample value alone is where \fBpamfunc\fP |
| 91 |
uses a different maxval in the output image than it finds in the input |
| 92 |
image. See \fB-changemaxval\fP. |
| 93 |
.PP |
| 94 |
So remember in reading the descriptions below that the values are 0.1 and |
| 95 |
0.5 in this example, not 10 and 50. All arguments and results are in the |
| 96 |
range [0,1]. |
| 97 |
|
| 98 |
.B Bit string functions |
| 99 |
.PP |
| 100 |
The bit string functions are those selected by the options |
| 101 |
\fB-andmask\fP, \fB-ormask\fP, \fB-xormask\fP, \fB-not\fP, |
| 102 |
\fB-shiftleft\fP, and \fB-shiftright\fP. |
| 103 |
.PP |
| 104 |
With these functions, the maxval has a very different meaning than in |
| 105 |
normal Netpbm images: it tells how wide (how many bits) the bit string is. |
| 106 |
The maxval must be a full binary count (a power of two minus one, such as |
| 107 |
0xff) and the number of ones in it is the width of the bit string. |
| 108 |
.PP |
| 109 |
As an example, consider an image with maxval 15 and a sample value of 5 |
| 110 |
and a function of "and with 0100". The argument to the function is |
| 111 |
0101 and the result is 0100. |
| 112 |
.PP |
| 113 |
In this example, it doesn't make any practical difference what we consider |
| 114 |
the width of the string to be, as long as it is at least 3. If the maxval |
| 115 |
were 255, the result would be the same. But with a bit shift operation, |
| 116 |
it matters. Consider shifting left by 2 bits. In the example, where |
| 117 |
the input value is 0101, the result is 0100. But if the maxval were 255, |
| 118 |
the result would be 00010100. |
| 119 |
.PP |
| 120 |
For a masking function, the mask value you specify must not have |
| 121 |
more significant bits than the width indicated by the maxval. |
| 122 |
.PP |
| 123 |
For a shifting operation, the shift count you specify must not be |
| 124 |
greater than the width indicated by the maxval. |
| 125 |
|
| 126 |
.UN pbmoddness |
| 127 |
.B PBM Oddness |
| 128 |
.PP |
| 129 |
If you're familiar with the PBM format, you may find \fBpamfunc\fP's |
| 130 |
operation on PBM images to be nonintuitive. Because in PBM black is |
| 131 |
represented as 1 and white as 0 (1.0 and 0.0 normlized), you might be |
| 132 |
expecting adding 1 to white to yield black. |
| 133 |
.PP |
| 134 |
But the PBM format is irrelevant, because \fBpamfunc\fP operates on the |
| 135 |
numbers found in the PAM equivalent (see above). In a PAM black and white |
| 136 |
image, black is 0 and white is 1 (0.0 and 1.0 normalized). So white plus 1 |
| 137 |
(clipped to the maximum of 1.0) is white. |
| 138 |
|
| 139 |
|
| 140 |
.UN options |
| 141 |
.SH OPTIONS |
| 142 |
.PP |
| 143 |
In addition to the options common to all programs based on libnetpbm |
| 144 |
(most notably \fB-quiet\fP, see |
| 145 |
.UR index.html#commonoptions |
| 146 |
Common Options |
| 147 |
.UE |
| 148 |
\&), \fBpamfunc\fP recognizes the following |
| 149 |
command line options: |
| 150 |
|
| 151 |
|
| 152 |
.TP |
| 153 |
\fB-multiplier=\fIrealnum\fP\fP |
| 154 |
.sp |
| 155 |
This option makes the transfer function that of multiplying by |
| 156 |
\fIrealnum\fP. \fIrealnum\fP must be nonnegative. If the result |
| 157 |
is greater than one, it is clipped to one. |
| 158 |
.sp |
| 159 |
Where the input is a PGM or PPM image, this has the effect of |
| 160 |
dimming or brightening it. For a different kind of brightening, |
| 161 |
see |
| 162 |
.BR "\fBpambrighten\fP" (1)\c |
| 163 |
\& and |
| 164 |
.BR "\fBppmflash\fP" (1)\c |
| 165 |
\& |
| 166 |
.sp |
| 167 |
Also, see |
| 168 |
.BR "\fBppmdim\fP" (1)\c |
| 169 |
\&, which does the same |
| 170 |
thing as \fBpamfunc -multiplier\fP on a PPM image with a multiplier |
| 171 |
between zero and one, except it uses integer arithmetic, so it may be |
| 172 |
faster. |
| 173 |
.sp |
| 174 |
And |
| 175 |
.BR "\fBppmfade\fP" (1)\c |
| 176 |
\& can generate a whole |
| 177 |
sequence of images of brightness declining to black or increasing to |
| 178 |
white, if that's what you want. |
| 179 |
|
| 180 |
.TP |
| 181 |
\fB-divisor=\fIrealnum\fP\fP |
| 182 |
.sp |
| 183 |
This option makes the transfer function that of dividing by |
| 184 |
\fIrealnum\fP. \fIrealnum\fP must be nonnegative. If the result |
| 185 |
is greater than one, it is clipped to one. |
| 186 |
.sp |
| 187 |
This is the same function as you would get with \fB-multiplier\fP, |
| 188 |
specifying the multiplicative inverse of \fIrealnum\fP. |
| 189 |
|
| 190 |
.TP |
| 191 |
\fB-adder=\fIinteger\fP\fP |
| 192 |
.sp |
| 193 |
This option makes the transfer function that of adding |
| 194 |
\fIinteger\fP/\fImaxval\fP. If the result is greater than one, it is |
| 195 |
clipped to one. If it is less than zero, it is clipped to zero. |
| 196 |
.sp |
| 197 |
Note that in mathematics, this entity is called an "addend," |
| 198 |
and an "adder" is a snake. We use "adder" because |
| 199 |
it makes more sense. |
| 200 |
|
| 201 |
.TP |
| 202 |
\fB-subtractor=\fIinteger\fP\fP |
| 203 |
.sp |
| 204 |
This option makes the transfer function that of subtracting |
| 205 |
\fIinteger\fP/\fImaxval\fP. If the result is greater than one, it is |
| 206 |
clipped to one. If it is less than zero, it is clipped to zero. |
| 207 |
.sp |
| 208 |
Note that in mathematics, this entity is called a |
| 209 |
"subtrahend" rather than a "subtractor." We use |
| 210 |
"subtractor" because it makes more sense. |
| 211 |
.sp |
| 212 |
This is the same function as you would get with \fB-adder\fP, |
| 213 |
specifying the negative of \fIinteger\fP. |
| 214 |
|
| 215 |
.TP |
| 216 |
\fB-min=\fIwholenum\fP\fP |
| 217 |
.sp |
| 218 |
This option makes the transfer function that of taking the maximum of |
| 219 |
the argument and \fIwholenum\fP/\fImaxval\fP. I.e the minimum value in |
| 220 |
the output will be \fIwholenum\fP/\fImaxval\fP. |
| 221 |
|
| 222 |
If \fIwholenum\fP/\fImaxval\fP is greater than one, though, every value |
| 223 |
in the output will be one. |
| 224 |
|
| 225 |
.TP |
| 226 |
\fB-max=\fIwholenum\fP\fP |
| 227 |
.sp |
| 228 |
This option makes the transfer function that of taking the minimum of |
| 229 |
the argument and \fIwholenum\fP/\fImaxval\fP. I.e the maximum value in |
| 230 |
the output will be \fIwholenum\fP/\fImaxval\fP. |
| 231 |
|
| 232 |
If \fIwholenum\fP/\fImaxval\fP is greater than one, the function is |
| 233 |
idempotent -- the output is identical to the input. |
| 234 |
|
| 235 |
.TP |
| 236 |
\fB-andmask=\fIhexmask\fP\fP |
| 237 |
.sp |
| 238 |
This option makes the transfer function that of bitwise anding |
| 239 |
with \fIhexmask\fP. |
| 240 |
.sp |
| 241 |
\fIhexmask\fP is in hexadecimal. Example: \f(CW0f\fP |
| 242 |
.sp |
| 243 |
This option was new in Netpbm 10.40 (September 2007). |
| 244 |
|
| 245 |
.TP |
| 246 |
\fB-ormask=\fIhexmask\fP\fP |
| 247 |
.sp |
| 248 |
This option makes the transfer function that of bitwise |
| 249 |
inclusive oring with \fIhexmask\fP. |
| 250 |
.sp |
| 251 |
This is analogous to \fB-andmask\fP. |
| 252 |
.sp |
| 253 |
This option was new in Netpbm 10.40 (September 2007). |
| 254 |
|
| 255 |
.TP |
| 256 |
\fB-xormask=\fIhexmask\fP\fP |
| 257 |
.sp |
| 258 |
This option makes the transfer function that of bitwise |
| 259 |
exclusive oring with \fIhexmask\fP. |
| 260 |
.sp |
| 261 |
This is analogous to \fB-andmask\fP. |
| 262 |
.sp |
| 263 |
This option was new in Netpbm 10.40 (September 2007). |
| 264 |
|
| 265 |
.TP |
| 266 |
\fB-not\fP |
| 267 |
.sp |
| 268 |
This option makes the transfer function that of bitwise logical |
| 269 |
inversion (e.g. sample value 0xAA becomes 0x55). |
| 270 |
.sp |
| 271 |
\fBpnminvert\fP does the same thing for a bilevel visual image |
| 272 |
which has maxval 1 or is of PBM type. |
| 273 |
.sp |
| 274 |
This option was new in Netpbm 10.40 (September 2007). |
| 275 |
|
| 276 |
.TP |
| 277 |
\fB-shiftleft=\fIcount\fP\fP |
| 278 |
.sp |
| 279 |
This option makes the transfer function that of bitwise shifting |
| 280 |
left by \fIcount\fP bits. |
| 281 |
.sp |
| 282 |
This option was new in Netpbm 10.40 (September 2007). |
| 283 |
|
| 284 |
.TP |
| 285 |
\fB-shiftright=\fIcount\fP\fP |
| 286 |
.sp |
| 287 |
This option makes the transfer function that of bitwise shifting |
| 288 |
right by \fIcount\fP bits. |
| 289 |
.sp |
| 290 |
This is analogous to \fB-shiftleft\fP. |
| 291 |
.sp |
| 292 |
This option was new in Netpbm 10.40 (September 2007). |
| 293 |
|
| 294 |
.TP |
| 295 |
\fB-changemaxval\fP |
| 296 |
.sp |
| 297 |
This option tells \fBpamfunc\fP to use a different maxval in the output |
| 298 |
image than the maxval of the input image, if it helps. By default, the maxval |
| 299 |
of the output is unchanged from the input and \fBpamfunc\fP modifies the |
| 300 |
sample values as necessary to perform the operation. |
| 301 |
.sp |
| 302 |
But there is one case where \fBpamfunc\fP can achieve the same result just |
| 303 |
by changing the maxval and leaving the sample values unchanged: dividing by a |
| 304 |
number 1 or greater, or multiplying by a number 1 or less. For example, to |
| 305 |
halve all of the values, \fBpamfunc\fP can just double the maxval. |
| 306 |
.sp |
| 307 |
With \fB-changemaxval\fP, \fBpamfunc\fP will do just that. |
| 308 |
.sp |
| 309 |
As the Netpbm formats have a maximum maxval of 65535, for large divisors, |
| 310 |
\fBpamfunc\fP may not be able to use this method. |
| 311 |
.sp |
| 312 |
An advantage of dividing by changing the maxval is that you don't lose |
| 313 |
precision. The higher maxval means higher precision. For example, consider |
| 314 |
an image with a maxval of 100 and sample value of 10. You divide by 21 and |
| 315 |
then multiply by 21 again. If \fBpamfunc\fP does this by changing the sample |
| 316 |
values while retaining maxval 100, the division will result in a sample value |
| 317 |
of 0 and the multiplication will also result in zero. But if \fBpamfunc\fP |
| 318 |
instead keeps the sample value 10 and changes the maxval, the division will |
| 319 |
result in a maxval of 2100 and the multiplication will change it back to 100, |
| 320 |
and the round trip is idempotent. |
| 321 |
.sp |
| 322 |
This option was new in Netpbm 10.65 (December 2013). |
| 323 |
|
| 324 |
|
| 325 |
|
| 326 |
|
| 327 |
.UN seealso |
| 328 |
.SH SEE ALSO |
| 329 |
.BR "ppmdim" (1)\c |
| 330 |
\&, |
| 331 |
.BR "pambrighten" (1)\c |
| 332 |
\&, |
| 333 |
.BR "pamdepth" (1)\c |
| 334 |
\&, |
| 335 |
.BR "pamarith" (1)\c |
| 336 |
\&, |
| 337 |
.BR "pamsummcol" (1)\c |
| 338 |
\&, |
| 339 |
.BR "pamsumm" (1)\c |
| 340 |
\&, |
| 341 |
.BR "ppmfade" (1)\c |
| 342 |
\&, |
| 343 |
.BR "pnminvert" (1)\c |
| 344 |
\&, |
| 345 |
.BR "pam" (1)\c |
| 346 |
\&, |
| 347 |
.BR "pnm" (1)\c |
| 348 |
\&, |
| 349 |
|
| 350 |
.UN history |
| 351 |
.SH HISTORY |
| 352 |
.PP |
| 353 |
This program was added to Netpbm in Release 10.3 (June 2002). |
| 354 |
.SH DOCUMENT SOURCE |
| 355 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 356 |
source. The master documentation is at |
| 357 |
.IP |
| 358 |
.B http://netpbm.sourceforge.net/doc/pamfunc.html |
| 359 |
.PP |