1Pamlookup User Manual(0) Pamlookup User Manual(0)
2
6 pamlookup - map an image to a new image by using it as indices into a
7 table
8
11 pamlookup -lookupfile=lookupfile [-byplane] -missingcolor=color [-fit]
12 indexfile
13 All options can be abbreviated to their shortest unique prefix. You
15 may use two hyphens instead of one. You may separate an option name
16 and its value with white space instead of an equals sign.
17
20 This program is part of Netpbm(1).
21 pamlookup takes a two dimensional array of indices and a lookup table
23 as input. For each position in the index array, it looks up the index
24 in the lookup table and places the result of the lookup in the output
25 image.
26 There are two ways of indexing the lookup table: whole tuple and by
28 plane. The -byplane option controls which pamlookup does.
29 In the simplest form of whole tuple indexing, each index in the index
31 array is a single whole number and the lookup table associates a whole
32 tuple with each possible whole number index. So for example, the index
33 array might have at Row 2, Column 9 the value 23. The lookup table
34 might associate the tuple (1,2,3) with the value 23. In that case, the
35 output image contains the tuple (1,2,3) at Row 2, Column 9.
36 In a more complex form of whole tuple indexing, each index in the index
38 array is an ordered pair of whole numbers and the lookup table asso‐
39 ciates a whole tuple with each possible ordered pair index. Modifying
40 the example above, the index value could be (23, 5) instead of 23.
41 With whole tuple indexing, the output thus has the same width and
43 height as the index image, and tuple depth and type and maxval deter‐
44 mined by the lookup table.
45 With whole tuple indexing, if the index image has depth 1, its sample
47 values are single whole number indices. If the index image has depth
48 greater than 1, its tuples are ordered pair indices composed of the
49 first and second sample in the tuple.
50 In by plane indexing, the index image contains whole number indices.
52 The first sample of each tuple in the index image is the index. The
53 lookup table maps each whole number index to another whole number.
54 pamlookup looks up each sample from the index image in the lookup table
55 and uses the resulting whole number as the sample value for the same
56 row, column, and plane in the output.
57 With by plane indexing, the output thus has the same dimensions as the
59 index image an the same maxval as the lookup image.
60 The Lookup Table Image
64 The lookup table is a PAM or PNM image. If the index image contains
65 whole number indices, the lookup image is a single row and the index is
66 a column number. The lookup result is the value of the tuple or pixel
67 at the indicated column in the one row in the lookup table. If the
68 index image contains ordered pair indices, the first element of the
69 ordered pair is a row number and the second element of the ordered pair
70 is a column number. The lookup result is the value of the tuple or
71 pixel at the indicated row and column in the lookup table.
72 The width of the lookup image should normally be the maxval of the
74 index image plus one, so that each possible index sample value corre‐
75 sponds to one entry in the lookup table. There are two ways pamlookup
76 deals with a lookup image that does not have such a width:
77 · Scale the lookup image to the required width. pamlookup always
81 does this with by plane indexing, and with whole tuple indexing,
82 does it when you specify -fit.
83 · Use a default value for indices that exceed the width of the
86 lookup image and ignore lookup image columns beyond the maxval
87 of the index image. pamlookup does this with whole tuple index‐
88 ing when you don't specify -fit.
89 You specify the default value with a -missingcolor option; it
91 defaults to the value from the top left corner of the lookup
92 image.
93 With ordered pair indexes (which implies whole tuple indexing), the
96 same rule applies to the height of the index image as to the width.
97 The mandatory -lookupfile option identifies the file containing the
99 lookup table image. - means Standard Input. It won't work if both the
100 index image file and lookup table file are Standard Input.
101 You can use ppmmake and pnmcat to create a lookup table file.
103 Example - Whole Tuple Indexing
107 Here is an example of pamlookup's function with whole tuple indexing
108 (-byplane not specified).
109 Consider an index image consisting of a 3x2x1 PAM as follows:
111 0 1 0
114 2 2 2
115 and a lookup table consisting of a 3x1 PPM image as follows:
117 red yellow beige
120 The lookup table above says Index 0 corresponds to the color red, Index
122 1 corresponds to yellow, and Index 2 corresponds to beige. The output
123 of pamlookup is the following PPM image:
124 red yellow red
127 beige beige beige
128 Now let's look at an example of the more complex case where the indices
130 are ordered pairs of whole numbers instead of whole numbers. Our index
131 image will be this 3x2x2 PAM image:
132 (0,0) (0,1) (0,0)
135 (1,1) (1,0) (0,0)
136 Our lookup table for the example will be this two dimensional PPM:
138 red yellow
141 green black
142 This lookup table says Index (0,0) corresponds to the color red, Index
144 (0,1) corresponds to yellow, Index (1,0) corresponds to green, and
145 Index (1,1) corresponds to black. The output of pamlookup is the fol‐
146 lowing PPM image:
147 red yellow red
150 black green red
151 Example - By Plane Indexing
155 Here is an example of pamlookup's function with by plane tuple indexing
156 (-byplane specified).
157 Consider an index image consisting of a 3x2x3 PAM as follows:
159 (0,0,0) (1,0,0) (2,0,0)
162 (2,2,0) (2,0,2) (2,0,0)
163 and a lookup table consisting of a 3x1x1 PAM image with maxval 7 as
165 follows:
166 3 4 7
169 The lookup table above says Index 0 corresponds to the sample value 3,
171 Index 1 corresponds to 4, and Index 2 corresponds to 7. The output of
172 pamlookup is the following 3x2x3 PAM image:
173 (3,3,3) (4,3,3) (7,3,3)
176 (7,7,3) (7,3,7) (7,3,3)
177 Miscellaneous
181 The indexfile argument identifies the file containing the index PAM or
182 PNM image. - means Standard Input. It won't work if both the index
183 image file and lookup table file are Standard Input.
184 The output image goes to Standard Output.
186 If you want to use two separate 1-plane images as indices (so that your
188 output reflects the combination of both inputs), use pamstack to com‐
189 bine the two into one two-plane image (and use a 2-dimensional lookup
190 table image).
191
195 -lookupfile=lookupfile
196 lookupfile names the file that contains the PAM or PNM image
197 that is the lookup table. This option is mandatory.
198 -byplane
201 This options selects by plane indexing. The default is whole
202 tuple indexing.
203 This option was new in Netpbm 10.72 (September 2015). Before
205 that, there is no by plane indexing.
206 -missingcolor=color
209 This option is meaningful only if the lookup image (and there‐
210 fore the output) is a PNM image. color specifies the color that
211 is to go in the output wherever the index from the input is not
212 present in the lookup table (not present means the index exceeds
213 the dimensions of the lookup image -- e.g. index is 100 but the
214 lookup image is a 50 x 1 PPM).
215 If you don't specify this option or -fit, pamlookup uses the
217 value from the top left corner of the lookup image whenever an
218 index exceeds the dimensions of the lookup image.
219 Specify the color (color) as described for the argument of the
221 pnm_parsecolor() library routine
222 ⟨libnetpbm_image.html#colorname⟩ .
223 Another way to deal with a too-small lookup image is to use the
225 -fit option.
226 This option has no effect if you also specify -fit or -byplane.
228 -fit This option says to shrink or expand the lookup image as neces‐
231 sary to fit the indices present in the index image, per the
232 index image's maxval. For example, if your index image has a
233 single plane and a maxval of 255 and your lookup image is 1 row
234 of 10 columns, pamlookup stretches your lookup image to 255 col‐
235 umns before doing the lookups. pamlookup does the stretching
236 (or shrinking) with the pamscale(1) program.
237 When you use -fit, pamlookup never fails or warns you because of
239 invalid lookup image dimensions, and the -missingcolor option
240 has no effect.
241 -fit has no effect when you specify -byplane. pamlookup always
243 has the behavior requested by -fit when it does by plane index‐
244 ing.
245
250 Example: rainfall map
251 Say you have a set of rainfall data in a single plane PAM image. The
252 rows and columns of the PAM indicate latitude and longitude. The sam‐
253 ple values are the annual rainfall in (whole) centimeters. The highest
254 rainfall value in the image is 199 centimeters. The image is in the
255 file rainfall.pam.
256 You want to produce a PPM rainfall map with green for the wettest
258 places, red for the driest, and other colors in between.
259 First, compose a lookup table image, probably with a graphical editor
261 and the image blown way up so you can work with individual pixels. The
262 image must have a single row and 200 columns. Make the leftmost pixel
263 red and the rightmost pixel green and choose appropriate colors in
264 between. Call it colorkey.ppm.
265 pamlookup rainfall.pam -lookupfile=colorkey.ppm >rainfallmap.ppm
267 Now lets say you're too lazy to type in 200 color values and nobody
269 really cares about the places that have more than 99 centimeters of
270 annual rainfall. In that case, just make colorkey.ppm 100 columns wide
271 and do this:
272 pamlookup rainfall.ppm -lookupfile=colorkey.ppm -missingcolor=black \
274 >rainfallmap.ppm
275 Now if there are areas that get more than 100 centimeters of rainfall,
277 they will just show up black in the output.
278 Example: graphical diff
281 Say you want to compare two PBM (black and white) images visually.
282 Each consists of black foreground pixels on a white background. You
283 want to create an image that contains background where both images con‐
284 tain background and foreground where both images contain foreground.
285 But where Image 1 has a foreground pixel and Image 2 does not, you want
286 red in the output; where Image 2 has a foreground pixel and Image 1
287 does not, you want green.
288 First, we create a single image that contains the information from both
290 input PBMs:
291 pamstack image1.pbm image2.pbm >bothimages.pam
293 Note that this image has 1 of 4 possible tuple values at each location:
295 (0,0), (0,1), (1,0), or (1,1).
296 Now, we create a lookup table that we can index with those 4 values:
298 ppmmake white 1 1 >white.ppm
300 ppmmake black 1 1 >black.ppm
301 ppmmake red 1 1 >red.ppm
302 ppmmake green 1 1 >green.ppm
303 pnmcat -leftright black.ppm red.ppm >blackred.ppm
304 pnmcat -leftright green.ppm white.ppm >greenwhite.ppm
305 pnmcat -topbottom blackred.ppm greenwhite.ppm >lookup.ppm
306 Finally, we look up the indices from our index in our lookup table and
308 produce the output:
309 pamlookup bothimages.ppm -lookupfile=lookup.ppm >imagediff.ppm
311
315 pamunlookup(1), pnmremap(1), ppmmake(1), pnmcat(1), pamstack(1),
316 pnm(1), pam(1)
317
321 pamlookup was new in Netpbm 10.13 (December 2002).
322
324 This manual page was generated by the Netpbm tool 'makeman' from HTML
325 source. The master documentation is at
326 http://netpbm.sourceforge.net/doc/pamlookup.html
328netpbm documentation 25 July 2015 Pamlookup User Manual(0)