summary refs log tree commit diff
path: root/pamfunc.html
blob: 42e33bbddd15e0f90d34ca2ac46269fc3a5f4d70 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD><TITLE>Pamfunc User Manual</TITLE></HEAD>

<BODY>
<H1>pamfunc</H1>
Updated: July 2007
<BR>
<A HREF="#index">Table Of Contents</A>

<H2>NAME</H2>
pamfunc - Apply a simple monadic arithmetic function to a Netpbm image

<H2 id="synopsis">SYNOPSIS</H2>

<B>pamfunc</B>
{
<b>-multiplier=</b><i>realnum</i> |
<b>-divisor=</b><i>realnum</i> |
<b>-adder=</b><i>integer</i> |
<b>-subtractor=</b><i>integer</i> |
<b>-min=</b><i>wholenum</i> |
<b>-max=</b><i>wholenum</i>
<b>-andmask=</b><i>hexmask</i>
<b>-ormask=</b><i>hexmask</i>
<b>-xormask=</b><i>hexmask</i>
<b>-not</b>
<b>-shiftleft=</b><i>count</i>
<b>-shiftright=</b><i>count</i>
}
[<I>filespec</I>]

<P>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.

<H2 id="description">DESCRIPTION</H2>

<p>This program is part of <a href="index.html">Netpbm</a>.

<P><b>pamfunc</b> reads a Netpbm image as input and produces a Netpbm
image as output, with the same format, maxval, and dimensions as the
input.  <b>pamfunc</b> applies a simple transfer function to each
sample in the input to generate the corresponding sample in the
output.  The options determine what function.

<P><b>pamarith</b> 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.


<H2 id="options">OPTIONS</H2>

<DL COMPACT>
<DT><B>-multiplier=<i>realnum</i></B>

<DD>
     <P>This option makes the transfer function that of multiplying by
     <i>realnum</i>.  <i>realnum</i> must be nonnegative.  If the result
     is greater than the image maxval, it is clipped to the maxval.

     <P>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 <a href="ppmbrighten.html"><b>ppmbrighten</b></a> and
     <a href="ppmflash.html"><b>ppmflash</b></a>

     <P>Also, see <a href="ppmdim.html"><b>ppmdim</b></a>, which does the
     same thing as <b>pamfunc -multiplier</b> on a PPM image with a
     multiplier between 0 and 1,
     except it uses integer arithmetic, so it may be faster.

     <P>And <a href="ppmfade.html"><b>ppmfade</b></a> can generate a whole
     sequence of images of brightness declining to black or increasing to
     white, if that's what you want.
     
<DT><B>-divisor=<i>realnum</i></B>

<DD>
     <P>This option makes the transfer function that of dividing by
     <i>realnum</i>.  <i>realnum</i> must be nonnegative.  If the result
     is greater than the image maxval, it is clipped to the maxval.

     <P>This is the same function as you would get with <b>-multiplier</b>,
     specifying the multiplicative inverse of <i>realnum</i>.
     
<DT><B>-adder=<i>integer</i></B>

<DD>
     <P>This option makes the transfer function that of adding
     <i>wholenum</i>.  If the result is greater than the image maxval,
     it is clipped to the maxval.  If it is less than zero, it is
     clipped to zero.

     <p>Note that in mathematics, this entity is called an &quot;addend,&quot;
     and an &quot;adder&quot; is a snake.  We use &quot;adder&quot; because
     it makes more sense.
     
<DT><B>-subtractor=<i>integer</i></B>

<DD>
     <P>This option makes the transfer function that of subtracting
     <i>wholenum</i>.  If the result is greater than the image maxval,
     it is clipped to the maxval.  If it is less than zero, it is
     clipped to zero.

     <p>Note that in mathematics, this entity is called a
     &quot;subtrahend&quot; rather than a &quot;subtractor.&quot;  We
     use &quot;subtractor&quot; because it makes more sense.

     <P>This is the same function as you would get with <b>-adder</b>,
     specifying the negative of <i>integer</i>.
     
<DT><B>-min=<i>wholenum</i></B>

<DD>
     <P>This option makes the transfer function that of taking the
     maximum of the argument and <i>wholenum</i>.  I.e the minimum
     value in the output will be <i>wholenum</i>.

     If <i>wholenum</i> is greater than the maxval, though, every sample
     in the output will be maxval.

<DT><B>-max=<i>wholenum</i></B>

<DD>
     <P>This option makes the transfer function that of taking the
     minimum of the argument and <i>wholenum</i>.  I.e the maximum
     value in the output will be <i>wholenum</i>.

     If <i>wholenum</i> is greater than the maxval, the function is
     idempotent -- the output is identical to the input.
     
<DT><B>-andmask=<i>hexmask</i></B>

<DD>
     <P>This option makes the transfer function that of bitwise anding
     with <i>hexmask</i>.

     <p><i>hexmask</i> is in hexadecimal.  Example: <kbd>0f</kbd>

     <p>See section <a href="#maxval">Maxval</a> for the special
     meaning of maxval with respect to bit string operations such as
     this.

     <p>This option was new in Netpbm 10.40 (September 2007).

<DT><B>-ormask=<i>hexmask</i></B>

<DD>
     <P>This option makes the transfer function that of bitwise
     inclusive oring with <i>hexmask</i>.

     <p>This is analogous to <b>-andmask</b>.

     <p>This option was new in Netpbm 10.40 (September 2007).

<DT><B>-xormask=<i>hexmask</i></B>

<DD>
     <P>This option makes the transfer function that of bitwise
     exclusive oring with <i>hexmask</i>.

     <p>This is analogous to <b>-andmask</b>.

     <p>This option was new in Netpbm 10.40 (September 2007).

<dt><b>-not</b>

<dd>
     <p>This option makes the transfer function that of bitwise logical
     inversion (e.g. sample value 0xAA becomes 0x55).

     <p>See section <a href="#maxval">Maxval</a> for the special
     meaning of maxval with respect to bit string operations such as
     this.

     <p><b>pnminvert</b> does the same thing for a bilevel visual image
     which has maxval 1 or is of PBM type.

     <p>This option was new in Netpbm 10.40 (September 2007).

<DT><B>-shiftleft=<i>count</i></B>

<DD>
     <P>This option makes the transfer function that of bitwise shifting
     left by <i>count</i> bits.

     <p>See section <a href="#maxval">Maxval</a> for the special
     meaning of maxval with respect to bit string operations such as
     this.

     <p>This option was new in Netpbm 10.40 (September 2007).

<DT><B>-shiftright=<i>count</i></B>

<DD>
     <P>This option makes the transfer function that of bitwise shifting
     right by <i>count</i> bits.

     <p>This is analogous to <b>-shiftleft</b>.

     <p>This option was new in Netpbm 10.40 (September 2007).
</DL>


<h2 id="maxval">MAXVAL</h2>

<p>For the arithmetic functions, the maxval has no meaning.  The function
applies to the sample value as an integer.  (Note that this differs from
the usual interpretation of PAM samples as being a fraction of a maxval,
but <em>does</em> produce more intuitive result: 2 times 5 is 10.

<P>But with the bit string operations, the maxval has a special
meaning.  The functions in question are: <B>-andmask</B>, <B>-ormask</B>,
<B>-xormask</B>, <B>-not</B>, <b>-shiftleft</b>, and <b>-shiftright</b>.

<p>With these, each sample value the input image, 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.

<p>For a masking function, the mask value you specify must not have
more significant bits than the width indicated by the maxval.

<p>For a shifting operation, the shift count you specify must not be
greater than the width indicated by the maxval.

<p>The maxval of the output image is the same as that of the input image.


<H2 id="seealso">SEE ALSO</H2>

<B><A HREF="ppmdim.html">ppmdim</A></B>,
<B><A HREF="ppmbrighten.html">ppmbrighten</A></B>,
<B><A HREF="pamdepth.html">pamdepth</A></B>,
<B><A HREF="pamarith.html">pamarith</A></B>,
<b><A HREF="pamsummcol.html">pamsummcol</A></b>,
<b><A HREF="pamsumm.html">pamsumm</A></b>,
<B><A HREF="ppmfade.html">ppmfade</A></B>,
<B><A HREF="pnminvert.html">pnminvert</A></B>,

<B><A HREF="pam.html">pam</A></B>,

<B><A HREF="pnm.html">pnm</A></B>,

<H2 id="history">HISTORY</H2>

<p>This program was added to Netpbm in Release 10.3 (June 2002).

<HR>
<A NAME="index">&nbsp;</A>
<H2>Table Of Contents</H2>
<UL>
<LI><A HREF="#synopsis">SYNOPSIS</A>
<LI><A HREF="#description">DESCRIPTION</A>
<LI><A HREF="#options">OPTIONS</A>
<LI><A HREF="#maxval">MAXVAL</A>
<LI><A HREF="#seealso">SEE ALSO</A>
<LI><A HREF="#history">HISTORY</A>
</UL>
</BODY>
</HTML>