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
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.3//EN">
<html><head><title>Pamlookup User Manual</title></head>
<body>
<h1>pamlookup</h1>
Updated: 25 July 2015
<br>
<a href="#index">Table Of Contents</a>
<h2>NAME</h2>
pamlookup - map an image to a new image by using it as indices into a table
<h2 id="synopsis">SYNOPSIS</h2>
<b>pamlookup</b>
<b>-lookupfile=</b><i>lookupfile</i>
[<b>-byplane</b>]
<b>-missingcolor=</b><i>color</i>
[<b>-fit</b>]
<i>indexfile</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>pamlookup</b> takes a two dimensional array of indices and a lookup
table as input. For each position in the index array, it looks up the index
in the lookup table and places the result of the lookup in the output image.
There are two ways of indexing the lookup table: <i>whole tuple</i> and
<i>by plane</i>. The <b>-byplane</b> option controls which <b>pamlookup</b>
does.
<p>In the simplest form of whole tuple indexing, each index in the index array
is a single whole number and the lookup table associates a whole tuple with
each possible whole number index. So for example, the index array might have
at Row 2, Column 9 the value 23. The lookup table might associate the tuple
(1,2,3) with the value 23. In that case, the output image contains the tuple
(1,2,3) at Row 2, Column 9.
<p>In a more complex form of whole tuple indexing, each index in the index
array is an ordered pair of whole numbers and the lookup table associates a
whole tuple with each possible ordered pair index. Modifying the example
above, the index value could be (23, 5) instead of 23.
<p>With whole tuple indexing, the output thus has the same width and height as
the index image, and tuple depth and type and maxval are determined by the
lookup table.
<p>With whole tuple indexing, if the index image has depth 1, its sample
values are single whole number indices. If the index image has depth greater
than 1, its tuples are ordered pair indices composed of the first and second
sample in the tuple.
<p>In by-plane indexing, the index image contains whole number indices. Each
sample in the index image is an index. The lookup table maps each whole
number index to another whole number. <b>pamlookup</b> looks up the sample at
each row, column, and plane in the index image in the lookup table and uses
the resulting whole number as the sample value for the same row, column, and
plane in the output.
<p>With by-plane indexing, the output thus has the same dimensions as the
index image an the same maxval as the lookup image.
<h3 id="lookupimage">The Lookup Table Image</h3>
<p>The lookup table is a PAM or PNM image. If the index image
contains whole number indices, the lookup image is a single row and
the index is a column number. The lookup result is the value of the
tuple or pixel at the indicated column in the one row in the lookup
table. If the index image contains ordered pair indices, the first
element of the ordered pair is a row number and the second element of
the ordered pair is a column number. The lookup result is the value
of the tuple or pixel at the indicated row and column in the lookup
table.
<p>The width of the lookup image should normally be the maxval of the index
image plus one, so that each possible index sample value corresponds to one
entry in the lookup table. There are two ways <b>pamlookup</b> deals
with a lookup image that does not have such a width:
<ul>
<li>Scale the lookup image to the required width. <b>pamlookup</b> always
does this with by plane indexing, and with whole tuple indexing, does it when
you specify <b>-fit</b>.
<li>Use a default value for indices that exceed the width of the lookup image
and ignore lookup image columns beyond the maxval of the index
image. <b>pamlookup</b> does this with whole tuple indexing when you don't
specify <b>-fit</b>.
<p>
You specify the default value with a <b>-missingcolor</b> option; it defaults
to the value from the top left corner of the lookup image.
</ul>
<p>With ordered pair indexes (which implies whole tuple indexing), the same
rule applies to the height of the index image as to the width.
<p>The mandatory <b>-lookupfile</b> option identifies the file containing the
lookup table image. <b>-</b> means Standard Input. It won't work if both the
index image file and lookup table file are Standard Input.
<p>You can use <b>ppmmake</b> and <b>pamcat</b> to create a lookup table file.
<h3 id="wholetuple">Example - Whole Tuple Indexing</h3>
<p>Here is an example of <b>pamlookup</b>'s function with whole
tuple indexing (<b>-byplane</b> not specified).
<p>Consider an index image consisting of a 3x2x1 PAM as follows:
<table>
<?makeman l l l. ?>
<tr> <td>0</td> <td>1</td> <td>0</td> </tr>
<tr> <td>2</td> <td>2</td> <td>2</td> </tr>
</table>
and a lookup table consisting of a 3x1 PPM image as follows:
<table>
<?makeman l l l. ?>
<tr> <td>red</td> <td>yellow</td> <td>beige</td> </tr>
</table>
The lookup table above says Index 0 corresponds to the color red,
Index 1 corresponds to yellow, and Index 2 corresponds to beige. The output
of <b>pamlookup</b> is the following PPM image:
<table>
<?makeman l l l. ?>
<tr> <td>red</td> <td>yellow</td> <td>red</td> </tr>
<tr> <td>beige</td> <td>beige</td> <td>beige</td> </tr>
</table>
<p>Now let's look at an example of the more complex case where the
indices are ordered pairs of whole numbers instead of whole numbers.
Our index image will be this 3x2x2 PAM image:
<table>
<?makeman l l l. ?>
<tr> <td>(0,0)</td> <td>(0,1)</td> <td>(0,0)</td> </tr>
<tr> <td>(1,1)</td> <td>(1,0)</td> <td>(0,0)</td> </tr>
</table>
Our lookup table for the example will be this two dimensional PPM:
<table>
<?makeman l l l. ?>
<tr> <td>red</td> <td>yellow</td> <td>red</td> </tr>
<tr> <td>black</td> <td>green</td> <td>red</td> </tr>
</table>
<h3 id="byplane">Example - By Plane Indexing</h3>
<p>Here is an example of <b>pamlookup</b>'s function with by plane
tuple indexing (<b>-byplane</b> specified).
<p>Consider an index image consisting of a 3x2x3 PAM as follows:
<table>
<?makeman l l l. ?>
<tr> <td>(0,0,0)</td> <td>(1,0,0)</td> <td>(2,0,0)</td> </tr>
<tr> <td>(2,2,0)</td> <td>(2,0,2)</td> <td>(2,0,0)</td> </tr>
</table>
and a lookup table consisting of a 3x1x1 PAM image with maxval 7 as follows:
<table>
<?makeman l l l. ?>
<tr> <td>3</td> <td>4</td> <td>7</td> </tr>
</table>
The lookup table above says Index 0 corresponds to the sample value 3, Index 1
corresponds to 4, and Index 2 corresponds to 7. The output of
<b>pamlookup</b> is the following 3x2x3 PAM image:
<table>
<?makeman l l l. ?>
<tr> <td>(3,3,3)</td> <td>(4,3,3)</td> <td>(7,3,3)</td> </tr>
<tr> <td>(7,7,3)</td> <td>(7,3,7)</td> <td>(7,3,3)</td> </tr>
</table>
<h3 id="misc">Miscellaneous</h3>
<p>The <i>indexfile</i> argument identifies the file containing the index PAM
or PNM image. <b>-</b> means Standard Input.
It won't work if both the
index image file and lookup table file are Standard Input.
The output image goes to Standard Output.
<p>If you want to use two separate 1-plane images as indices (so that your
output reflects the combination of both inputs), use <b>pamstack</b> to combine
the two into one two-plane image (and use a 2-dimensional lookup table image).
<h2 id="options">OPTIONS</h2>
<p>In addition to the options common to all programs based on libnetpbm
(most notably <b>-quiet</b>, see <a href="index.html#commonoptions">
Common Options</a>), <b>pamlookup</b> recognizes the following
command line options:
<dl compact>
<dt><b>-lookupfile=</b><i>lookupfile</i>
<dd><i>lookupfile</i> names the file that contains the PAM or PNM
image that is the lookup table. This option is mandatory.
<dt><b>-byplane</b>
<dd>This options selects by plane indexing. The default is whole tuple
indexing.
<p>This option was new in Netpbm 10.72 (September 2015). Before that, there
is no by plane indexing.
<dt><b>-missingcolor=</b><i>color</i>
<dd>This option is meaningful only if the lookup image (and therefore the
output) is a PNM image. <i>color</i> specifies the color that
is to go in the output wherever the index from the input is not present
in the lookup table (not present means the index exceeds the dimensions
of the lookup image -- e.g. index is 100 but the lookup image is a 50 x 1
PPM).
<p>If you don't specify this option or <b>-fit</b>, <b>pamlookup</b>
uses the value from the top left corner of the lookup image whenever
an index exceeds the dimensions of the lookup image.
<p>Specify the color (<i>color</i>) as described for the <a
href="libnetpbm_image.html#colorname">argument of the <b>pnm_parsecolor()</b>
library routine</a>.
<p>Another way to deal with a too-small lookup image is to use the
<b>-fit</b> option.
<p>This option has no effect if you also specify <b>-fit</b> or
<b>-byplane</b>.
<dt><b>-fit</b>
<dd>This option says to shrink or expand the lookup image as necessary
to fit the indices present in the index image, per the index image's
maxval. For example, if your index image has a single plane and a
maxval of 255 and your lookup image is 1 row of 10 columns,
<b>pamlookup</b> stretches your lookup image to 255 columns before
doing the lookups. <b>pamlookup</b> does the stretching (or
shrinking) with the <a href="pamscale.html"><b>pamscale</b></a>
program.
<p>When you use <b>-fit</b>, <b>pamlookup</b> never fails or warns you
because of invalid lookup image dimensions, and the <b>-missingcolor</b>
option has no effect.
<p><b>-fit</b> has no effect when you specify <b>-byplane</b>.
<b>pamlookup</b> always has the behavior requested by <b>-fit</b> when it does
by plane indexing.
</dl>
<h2 id="examples">EXAMPLES</h2>
<h3>Example: rainfall map</h3>
<p>Say you have a set of rainfall data in a single plane PAM image.
The rows and columns of the PAM indicate latitude and longitude. The
sample values are the annual rainfall in (whole) centimeters. The highest
rainfall value in the image is 199 centimeters. The image is in the file
rainfall.pam.
<p>You want to produce a PPM rainfall map with green for the wettest places,
red for the driest, and other colors in between.
<p>First, compose a lookup table image, probably with a graphical editor
and the image blown way up so you can work with individual pixels. The
image must have a single row and 200 columns. Make the leftmost pixel
red and the rightmost pixel green and choose appropriate colors in between.
Call it colorkey.ppm.
<pre>
<kbd>
pamlookup rainfall.pam -lookupfile=colorkey.ppm >rainfallmap.ppm
</kbd>
</pre>
<p>Now lets say you're too lazy to type in 200 color values and nobody really
cares about the places that have more than 99 centimeters of annual
rainfall. In that case, just make colorkey.ppm 100 columns wide and do
this:
<pre>
<kbd>
pamlookup rainfall.ppm -lookupfile=colorkey.ppm -missingcolor=black \
>rainfallmap.ppm
</kbd>
</pre>
Now if there are areas that get more than 100 centimeters of rainfall, they
will just show up black in the output.
<h3>Example: graphical diff</h3>
<p>
Say you want to compare two PBM (black and white) images visually. Each
consists of black foreground pixels on a white background. You want to
create an image that contains background where both images contain background
and foreground where both images contain foreground. But where Image 1
has a foreground pixel and Image 2 does not, you want red in the output;
where Image 2 has a foreground pixel and Image 1 does not, you want green.
<p>First, we create a single image that contains the information from both
input PBMs:
<pre>
<kbd>
pamstack image1.pbm image2.pbm >bothimages.pam
</kbd>
</pre>
Note that this image has 1 of 4 possible tuple values at each location:
(0,0), (0,1), (1,0), or (1,1).
<p>
Now, we create a lookup table that we can index with those 4 values:
<pre>
<kbd>
ppmmake white 1 1 >white.ppm
ppmmake black 1 1 >black.ppm
ppmmake red 1 1 >red.ppm
ppmmake green 1 1 >green.ppm
pamcat -leftright black.ppm red.ppm >blackred.ppm
pamcat -leftright green.ppm white.ppm >greenwhite.ppm
pamcat -topbottom blackred.ppm greenwhite.ppm >lookup.ppm
</kbd>
</pre>
<p>Finally, we look up the indices from our index in our lookup table and
produce the output:
<pre>
<kbd>
pamlookup bothimages.ppm -lookupfile=lookup.ppm >imagediff.ppm
</kbd>
</pre>
<h2 id="seealso">SEE ALSO</h2>
<a href="pamunlookup.html">pamunlookup</a>,
<a href="pnmremap.html">pnmremap</a>,
<a href="ppmmake.html">ppmmake</a>,
<a href="pamcat.html">pamcat</a>,
<a href="pamstack.html">pamstack</a>,
<a href="pnm.html">pnm</a>,
<a href="pam.html">pam</a>
<h2 id="history">HISTORY</h2>
<p><b>pamlookup</b> was new in Netpbm 10.13 (December 2002).
<hr>
<h2 id="index">Table Of Contents</h2>
<ul compact>
<li><a href="#synopsis">SYNOPSIS</a>
<li><a href="#description">DESCRIPTION</a>
<ul>
<li><a href="#lookupimage">The Lookup Table Image</a>
<li><a href="#wholetuple">Example - Whole Tuple Indexing</a>
<li><a href="#byplane">Example - By Plane Indexing</a>
<li><a href="#misc">Miscellaneous</a>
</ul>
<li><a href="#options">OPTIONS</a>
<li><a href="#examples">EXAMPLES</a>
<li><a href="#seealso">SEE ALSO</a>
<li><a href="#history">HISTORY</a>
</ul>
</body>
</html>
|
