Debian Codegraph @

upstream/debian-unstable/man1/pamlookup.1

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