1Pamlookup User Manual(0)                              Pamlookup User Manual(0)
2
3
4

NAME

6       pamlookup  -  map an image to a new image by using it as indices into a
7       table
8
9

SYNOPSIS

11       pamlookup -lookupfile=lookupfile [-byplane] -missingcolor=color  [-fit]
12       indexfile
13
14       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
18

DESCRIPTION

20       This program is part of Netpbm(1).
21
22       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
27       There are two ways of indexing the lookup table:  whole  tuple  and  by
28       plane.  The -byplane option controls which pamlookup does.
29
30       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
37       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
42       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
46       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
51       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
58       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
61
62
63   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
73       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
78
79
80       ·      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
84
85       ·      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
90              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
94
95       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
98       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
102       You can use ppmmake and pnmcat to create a lookup table file.
103
104
105
106   Example - Whole Tuple Indexing
107       Here is an example of pamlookup's function with  whole  tuple  indexing
108       (-byplane not specified).
109
110       Consider an index image consisting of a 3x2x1 PAM as follows:
111
112
113       0   1   0
114       2   2   2
115
116       and a lookup table consisting of a 3x1 PPM image as follows:
117
118
119       red   yellow   beige
120
121       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
125
126       red     yellow   red
127       beige   beige    beige
128
129       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
133
134       (0,0)   (0,1)   (0,0)
135       (1,1)   (1,0)   (0,0)
136
137       Our lookup table for the example will be this two dimensional PPM:
138
139
140       red     yellow
141       green   black
142
143       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
148
149       red     yellow   red
150       black   green    red
151
152
153
154   Example - By Plane Indexing
155       Here is an example of pamlookup's function with by plane tuple indexing
156       (-byplane specified).
157
158       Consider an index image consisting of a 3x2x3 PAM as follows:
159
160
161       (0,0,0)   (1,0,0)   (2,0,0)
162       (2,2,0)   (2,0,2)   (2,0,0)
163
164       and  a  lookup  table  consisting of a 3x1x1 PAM image with maxval 7 as
165       follows:
166
167
168       3   4   7
169
170       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
174
175       (3,3,3)   (4,3,3)   (7,3,3)
176       (7,7,3)   (7,3,7)   (7,3,3)
177
178
179
180   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
185       The output image goes to Standard Output.
186
187       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
192
193

OPTIONS

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
199
200       -byplane
201              This options selects by plane indexing.  The  default  is  whole
202              tuple indexing.
203
204              This  option  was  new in Netpbm 10.72 (September 2015).  Before
205              that, there is no by plane indexing.
206
207
208       -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
216              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
220              Specify  the  color (color) as described for the argument of the
221              pnm_parsecolor()                 library                 routine
222              ⟨libnetpbm_image.html#colorname⟩ .
223
224              Another  way to deal with a too-small lookup image is to use the
225              -fit option.
226
227              This option has no effect if you also specify -fit or -byplane.
228
229
230       -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
238              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
242              -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
246
247
248

EXAMPLES

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
257       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
260       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
266           pamlookup rainfall.pam -lookupfile=colorkey.ppm >rainfallmap.ppm
267
268       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
273           pamlookup rainfall.ppm -lookupfile=colorkey.ppm -missingcolor=black \
274              >rainfallmap.ppm
275
276       Now if there are areas that get more than 100 centimeters of  rainfall,
277       they will just show up black in the output.
278
279
280   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
289       First, we create a single image that contains the information from both
290       input PBMs:
291
292           pamstack image1.pbm image2.pbm >bothimages.pam
293
294       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
297       Now, we create a lookup table that we can index with those 4 values:
298
299           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
307       Finally,  we look up the indices from our index in our lookup table and
308       produce the output:
309
310           pamlookup bothimages.ppm -lookupfile=lookup.ppm >imagediff.ppm
311
312
313

SEE ALSO

315       pamunlookup(1),  pnmremap(1),   ppmmake(1),   pnmcat(1),   pamstack(1),
316       pnm(1), pam(1)
317
318
319

HISTORY

321       pamlookup was new in Netpbm 10.13 (December 2002).
322

DOCUMENT SOURCE

324       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
325       source.  The master documentation is at
326
327              http://netpbm.sourceforge.net/doc/pamlookup.html
328
329netpbm documentation             25 July 2015         Pamlookup User Manual(0)
Impressum