Debian Codegraph @

userguide/pamlookup.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.3//EN">
2 <html><head><title>Pamlookup User Manual</title></head>
3 <body>
4 <h1>pamlookup</h1>
5 Updated: 25 July 2015
6 <br>
7 <a href="#index">Table Of Contents</a>
8
9 <h2>NAME</h2>
10 pamlookup - map an image to a new image by using it as indices into a table
11
12 <h2 id="synopsis">SYNOPSIS</h2>
13
14 <b>pamlookup</b>
15 <b>-lookupfile=</b><i>lookupfile</i>
16 [<b>-byplane</b>]
17 <b>-missingcolor=</b><i>color</i>
18 [<b>-fit</b>]
19 <i>indexfile</i>
20
21
22 <p>All options can be abbreviated to their shortest unique prefix.
23 You may use two hyphens instead of one. You may separate an option
24 name and its value with white space instead of an equals sign.
25
26 <h2 id="description">DESCRIPTION</h2>
27
28 <p>This program is part of <a href="index.html">Netpbm</a>.
29
30 <p><b>pamlookup</b> takes a two dimensional array of indices and a lookup
31 table as input. For each position in the index array, it looks up the index
32 in the lookup table and places the result of the lookup in the output image.
33
34 There are two ways of indexing the lookup table: <i>whole tuple</i> and
35 <i>by plane</i>. The <b>-byplane</b> option controls which <b>pamlookup</b>
36 does.
37
38 <p>In the simplest form of whole tuple indexing, each index in the index array
39 is a single whole number and the lookup table associates a whole tuple with
40 each possible whole number index. So for example, the index array might have
41 at Row 2, Column 9 the value 23. The lookup table might associate the tuple
42 (1,2,3) with the value 23. In that case, the output image contains the tuple
43 (1,2,3) at Row 2, Column 9.
44
45 <p>In a more complex form of whole tuple indexing, each index in the index
46 array is an ordered pair of whole numbers and the lookup table associates a
47 whole tuple with each possible ordered pair index. Modifying the example
48 above, the index value could be (23, 5) instead of 23.
49
50 <p>With whole tuple indexing, the output thus has the same width and height as
51 the index image, and tuple depth and type and maxval are determined by the
52 lookup table.
53
54 <p>With whole tuple indexing, if the index image has depth 1, its sample
55 values are single whole number indices. If the index image has depth greater
56 than 1, its tuples are ordered pair indices composed of the first and second
57 sample in the tuple.
58
59 <p>In by-plane indexing, the index image contains whole number indices. Each
60 sample in the index image is an index. The lookup table maps each whole
61 number index to another whole number. <b>pamlookup</b> looks up the sample at
62 each row, column, and plane in the index image in the lookup table and uses
63 the resulting whole number as the sample value for the same row, column, and
64 plane in the output.
65
66 <p>With by-plane indexing, the output thus has the same dimensions as the
67 index image an the same maxval as the lookup image.
68
69
70 <h3 id="lookupimage">The Lookup Table Image</h3>
71
72 <p>The lookup table is a PAM or PNM image. If the index image
73 contains whole number indices, the lookup image is a single row and
74 the index is a column number. The lookup result is the value of the
75 tuple or pixel at the indicated column in the one row in the lookup
76 table. If the index image contains ordered pair indices, the first
77 element of the ordered pair is a row number and the second element of
78 the ordered pair is a column number. The lookup result is the value
79 of the tuple or pixel at the indicated row and column in the lookup
80 table.
81
82 <p>The width of the lookup image should normally be the maxval of the index
83 image plus one, so that each possible index sample value corresponds to one
84 entry in the lookup table. There are two ways <b>pamlookup</b> deals
85 with a lookup image that does not have such a width:
86
87 <ul>
88 <li>Scale the lookup image to the required width. <b>pamlookup</b> always
89 does this with by plane indexing, and with whole tuple indexing, does it when
90 you specify <b>-fit</b>.
91
92 <li>Use a default value for indices that exceed the width of the lookup image
93 and ignore lookup image columns beyond the maxval of the index
94 image. <b>pamlookup</b> does this with whole tuple indexing when you don't
95 specify <b>-fit</b>.
96 <p>
97 You specify the default value with a <b>-missingcolor</b> option; it defaults
98 to the value from the top left corner of the lookup image.
99 </ul>
100
101 <p>With ordered pair indexes (which implies whole tuple indexing), the same
102 rule applies to the height of the index image as to the width.
103
104 <p>The mandatory <b>-lookupfile</b> option identifies the file containing the
105 lookup table image. <b>-</b> means Standard Input. It won't work if both the
106 index image file and lookup table file are Standard Input.
107
108 <p>You can use <b>ppmmake</b> and <b>pamcat</b> to create a lookup table file.
109
110
111 <h3 id="wholetuple">Example - Whole Tuple Indexing</h3>
112
113 <p>Here is an example of <b>pamlookup</b>'s function with whole
114 tuple indexing (<b>-byplane</b> not specified).
115
116 <p>Consider an index image consisting of a 3x2x1 PAM as follows:
117
118 <table>
119 <?makeman l l l. ?>
120 <tr> <td>0</td> <td>1</td> <td>0</td> </tr>
121 <tr> <td>2</td> <td>2</td> <td>2</td> </tr>
122 </table>
123
124 and a lookup table consisting of a 3x1 PPM image as follows:
125
126 <table>
127 <?makeman l l l. ?>
128 <tr> <td>red</td> <td>yellow</td> <td>beige</td> </tr>
129 </table>
130
131 The lookup table above says Index 0 corresponds to the color red,
132 Index 1 corresponds to yellow, and Index 2 corresponds to beige. The output
133 of <b>pamlookup</b> is the following PPM image:
134
135 <table>
136 <?makeman l l l. ?>
137 <tr> <td>red</td> <td>yellow</td> <td>red</td> </tr>
138 <tr> <td>beige</td> <td>beige</td> <td>beige</td> </tr>
139 </table>
140
141 <p>Now let's look at an example of the more complex case where the
142 indices are ordered pairs of whole numbers instead of whole numbers.
143 Our index image will be this 3x2x2 PAM image:
144
145 <table>
146 <?makeman l l l. ?>
147 <tr> <td>(0,0)</td> <td>(0,1)</td> <td>(0,0)</td> </tr>
148 <tr> <td>(1,1)</td> <td>(1,0)</td> <td>(0,0)</td> </tr>
149 </table>
150
151 Our lookup table for the example will be this two dimensional PPM:
152
153 <table>
154 <?makeman l l l. ?>
155 <tr> <td>red</td> <td>yellow</td> <td>red</td> </tr>
156 <tr> <td>black</td> <td>green</td> <td>red</td> </tr>
157 </table>
158
159
160 <h3 id="byplane">Example - By Plane Indexing</h3>
161
162 <p>Here is an example of <b>pamlookup</b>'s function with by plane
163 tuple indexing (<b>-byplane</b> specified).
164
165 <p>Consider an index image consisting of a 3x2x3 PAM as follows:
166
167 <table>
168 <?makeman l l l. ?>
169 <tr> <td>(0,0,0)</td> <td>(1,0,0)</td> <td>(2,0,0)</td> </tr>
170 <tr> <td>(2,2,0)</td> <td>(2,0,2)</td> <td>(2,0,0)</td> </tr>
171 </table>
172
173 and a lookup table consisting of a 3x1x1 PAM image with maxval 7 as follows:
174
175 <table>
176 <?makeman l l l. ?>
177 <tr> <td>3</td> <td>4</td> <td>7</td> </tr>
178 </table>
179
180 The lookup table above says Index 0 corresponds to the sample value 3, Index 1
181 corresponds to 4, and Index 2 corresponds to 7. The output of
182 <b>pamlookup</b> is the following 3x2x3 PAM image:
183
184 <table>
185 <?makeman l l l. ?>
186 <tr> <td>(3,3,3)</td> <td>(4,3,3)</td> <td>(7,3,3)</td> </tr>
187 <tr> <td>(7,7,3)</td> <td>(7,3,7)</td> <td>(7,3,3)</td> </tr>
188 </table>
189
190
191 <h3 id="misc">Miscellaneous</h3>
192
193 <p>The <i>indexfile</i> argument identifies the file containing the index PAM
194 or PNM image. <b>-</b> means Standard Input.
195 It won't work if both the
196 index image file and lookup table file are Standard Input.
197
198 The output image goes to Standard Output.
199
200 <p>If you want to use two separate 1-plane images as indices (so that your
201 output reflects the combination of both inputs), use <b>pamstack</b> to combine
202 the two into one two-plane image (and use a 2-dimensional lookup table image).
203
204
205 <h2 id="options">OPTIONS</h2>
206
207 <p>In addition to the options common to all programs based on libnetpbm
208 (most notably <b>-quiet</b>, see <a href="index.html#commonoptions">
209 Common Options</a>), <b>pamlookup</b> recognizes the following
210 command line options:
211
212 <dl compact>
213 <dt><b>-lookupfile=</b><i>lookupfile</i>
214
215 <dd><i>lookupfile</i> names the file that contains the PAM or PNM
216 image that is the lookup table. This option is mandatory.
217
218 <dt><b>-byplane</b>
219
220 <dd>This options selects by plane indexing. The default is whole tuple
221 indexing.
222
223 <p>This option was new in Netpbm 10.72 (September 2015). Before that, there
224 is no by plane indexing.
225
226 <dt><b>-missingcolor=</b><i>color</i>
227
228 <dd>This option is meaningful only if the lookup image (and therefore the
229 output) is a PNM image. <i>color</i> specifies the color that
230 is to go in the output wherever the index from the input is not present
231 in the lookup table (not present means the index exceeds the dimensions
232 of the lookup image -- e.g. index is 100 but the lookup image is a 50 x 1
233 PPM).
234
235 <p>If you don't specify this option or <b>-fit</b>, <b>pamlookup</b>
236 uses the value from the top left corner of the lookup image whenever
237 an index exceeds the dimensions of the lookup image.
238
239 <p>Specify the color (<i>color</i>) as described for the <a
240 href="libnetpbm_image.html#colorname">argument of the <b>pnm_parsecolor()</b>
241 library routine</a>.
242
243 <p>Another way to deal with a too-small lookup image is to use the
244 <b>-fit</b> option.
245
246 <p>This option has no effect if you also specify <b>-fit</b> or
247 <b>-byplane</b>.
248
249 <dt><b>-fit</b>
250
251 <dd>This option says to shrink or expand the lookup image as necessary
252 to fit the indices present in the index image, per the index image's
253 maxval. For example, if your index image has a single plane and a
254 maxval of 255 and your lookup image is 1 row of 10 columns,
255 <b>pamlookup</b> stretches your lookup image to 255 columns before
256 doing the lookups. <b>pamlookup</b> does the stretching (or
257 shrinking) with the <a href="pamscale.html"><b>pamscale</b></a>
258 program.
259
260 <p>When you use <b>-fit</b>, <b>pamlookup</b> never fails or warns you
261 because of invalid lookup image dimensions, and the <b>-missingcolor</b>
262 option has no effect.
263
264 <p><b>-fit</b> has no effect when you specify <b>-byplane</b>.
265 <b>pamlookup</b> always has the behavior requested by <b>-fit</b> when it does
266 by plane indexing.
267
268 </dl>
269
270 <h2 id="examples">EXAMPLES</h2>
271
272 <h3>Example: rainfall map</h3>
273
274 <p>Say you have a set of rainfall data in a single plane PAM image.
275 The rows and columns of the PAM indicate latitude and longitude. The
276 sample values are the annual rainfall in (whole) centimeters. The highest
277 rainfall value in the image is 199 centimeters. The image is in the file
278 rainfall.pam.
279
280 <p>You want to produce a PPM rainfall map with green for the wettest places,
281 red for the driest, and other colors in between.
282
283 <p>First, compose a lookup table image, probably with a graphical editor
284 and the image blown way up so you can work with individual pixels. The
285 image must have a single row and 200 columns. Make the leftmost pixel
286 red and the rightmost pixel green and choose appropriate colors in between.
287 Call it colorkey.ppm.
288
289 <pre>
290 <kbd>
291 pamlookup rainfall.pam -lookupfile=colorkey.ppm &gt;rainfallmap.ppm
292 </kbd>
293 </pre>
294
295 <p>Now lets say you're too lazy to type in 200 color values and nobody really
296 cares about the places that have more than 99 centimeters of annual
297 rainfall. In that case, just make colorkey.ppm 100 columns wide and do
298 this:
299
300 <pre>
301 <kbd>
302 pamlookup rainfall.ppm -lookupfile=colorkey.ppm -missingcolor=black \
303 &gt;rainfallmap.ppm
304 </kbd>
305 </pre>
306
307 Now if there are areas that get more than 100 centimeters of rainfall, they
308 will just show up black in the output.
309
310 <h3>Example: graphical diff</h3>
311 <p>
312 Say you want to compare two PBM (black and white) images visually. Each
313 consists of black foreground pixels on a white background. You want to
314 create an image that contains background where both images contain background
315 and foreground where both images contain foreground. But where Image 1
316 has a foreground pixel and Image 2 does not, you want red in the output;
317 where Image 2 has a foreground pixel and Image 1 does not, you want green.
318
319 <p>First, we create a single image that contains the information from both
320 input PBMs:
321
322 <pre>
323 <kbd>
324 pamstack image1.pbm image2.pbm &gt;bothimages.pam
325 </kbd>
326 </pre>
327
328 Note that this image has 1 of 4 possible tuple values at each location:
329 (0,0), (0,1), (1,0), or (1,1).
330
331 <p>
332 Now, we create a lookup table that we can index with those 4 values:
333
334 <pre>
335 <kbd>
336 ppmmake white 1 1 &gt;white.ppm
337 ppmmake black 1 1 &gt;black.ppm
338 ppmmake red 1 1 &gt;red.ppm
339 ppmmake green 1 1 &gt;green.ppm
340 pamcat -leftright black.ppm red.ppm &gt;blackred.ppm
341 pamcat -leftright green.ppm white.ppm &gt;greenwhite.ppm
342 pamcat -topbottom blackred.ppm greenwhite.ppm &gt;lookup.ppm
343 </kbd>
344 </pre>
345
346 <p>Finally, we look up the indices from our index in our lookup table and
347 produce the output:
348
349 <pre>
350 <kbd>
351 pamlookup bothimages.ppm -lookupfile=lookup.ppm &gt;imagediff.ppm
352 </kbd>
353 </pre>
354
355
356 <h2 id="seealso">SEE ALSO</h2>
357
358 <a href="pamunlookup.html">pamunlookup</a>,
359 <a href="pnmremap.html">pnmremap</a>,
360 <a href="ppmmake.html">ppmmake</a>,
361 <a href="pamcat.html">pamcat</a>,
362 <a href="pamstack.html">pamstack</a>,
363 <a href="pnm.html">pnm</a>,
364 <a href="pam.html">pam</a>
365
366
367 <h2 id="history">HISTORY</h2>
368
369 <p><b>pamlookup</b> was new in Netpbm 10.13 (December 2002).
370
371 <hr>
372 <h2 id="index">Table Of Contents</h2>
373 <ul compact>
374 <li><a href="#synopsis">SYNOPSIS</a>
375 <li><a href="#description">DESCRIPTION</a>
376 <ul>
377 <li><a href="#lookupimage">The Lookup Table Image</a>
378 <li><a href="#wholetuple">Example - Whole Tuple Indexing</a>
379 <li><a href="#byplane">Example - By Plane Indexing</a>
380 <li><a href="#misc">Miscellaneous</a>
381 </ul>
382 <li><a href="#options">OPTIONS</a>
383 <li><a href="#examples">EXAMPLES</a>
384 <li><a href="#seealso">SEE ALSO</a>
385 <li><a href="#history">HISTORY</a>
386 </ul>
387 </body>
388 </html>