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 -missingcolor=color [-fit] indexfile
12
13       All options can be abbreviated to their shortest  unique  prefix.   You
14       may  use  two  hyphens instead of one.  You may separate an option name
15       and its value with white space instead of an equals sign.
16
17

DESCRIPTION

19       This program is part of Netpbm(1).
20
21       pamlookup takes a two dimensional array of indices and a  lookup  table
22       as  input.  For each position in the index array, it looks up the index
23       in the lookup table and places the result of the lookup in  the  output
24       image.   The  output  thus  has  the same width and height as the index
25       image, and tuple types determined by the lookup table.
26
27       An index is either a whole number or an ordered pair of whole  numbers.
28       If the index image has a depth of one, each index in it is a whole num‐
29       ber: the value of the one sample.  If  the  index  image  has  a  depth
30       greater  than one, each index in it is an ordered pair of the first and
31       second samples in the relevant tuple.
32
33       The lookup table is a PAM or PNM image.  If the  index  image  contains
34       whole number indices, the lookup image is a single row and the index is
35       a column number.  The lookup result is the value of the tuple or  pixel
36       at  the  indicated  column  in the one row in the lookup table.  If the
37       index image contains ordered pair indices, the  first  element  of  the
38       ordered pair is a row number and the second element of the ordered pair
39       is a column number.  The lookup result is the value  of  the  tuple  or
40       pixel at the indicated row and column in the lookup table.
41
42       For example:  Consider an index image consisting of a 3x2x1 PAM as fol‐
43       lows:
44
45
46       0   1   0
47       2   2   2
48
49       and a lookup table consisting of a 3x1 PPM image as follows:
50
51
52       red   yellow   beige
53
54       The lookup table above says Index 0 corresponds to the color red, Index
55       1  corresponds to yellow, and Index 2 corresponds to beige.  The output
56       of pamlookup is the following PPM image:
57
58
59       red     yellow   red
60       beige   beige    beige
61
62       Now let's look at an example of the more complex case where the indices
63       are ordered pairs of whole numbers instead of whole numbers.  Our index
64       image will be this 3x2x2 PAM image:
65
66
67       (0,0)   (0,1)   (0,0)
68       (1,1)   (1,0)   (0,0)
69
70       Our lookup table for the example will be this two dimensional PPM:
71
72
73       red     yellow
74       green   black
75
76       This lookup table says Index (0,0) corresponds to the color red,  Index
77       (0,1)  corresponds  to  yellow,  Index  (1,0) corresponds to green, and
78       Index (1,1) corresponds to black.  The output of pamlookup is the  fol‐
79       lowing PPM image:
80
81
82       red     yellow   red
83       black   green    red
84
85       If  an  index  specifies a row or column that exceeds the dimensions of
86       the lookup table image, pamlookup uses the value from the top left cor‐
87       ner  of  the  lookup image, or the value you specify with the -missing‐
88       color option.
89
90       The indexfile argument identifies the file containing the index PAM  or
91       PNM  image.   - means Standard Input.  The mandatory -lookupfile option
92       identifies the file containing the lookup table image.  Again, -  means
93       Standard  Input.  It won't work if both the index image file and lookup
94       table file are Standard Input.  The output image goes to Standard  Out‐
95       put.
96
97       You can use ppmmake and pnmcat to create a lookup table file.
98
99       If you want to use two separate 1-plane images as indices (so that your
100       output reflects the combination of both inputs), use pamstack  to  com‐
101       bine  the  two into one two-plane image (and use a 2-dimensional lookup
102       table image).
103
104
105

OPTIONS

107       -lookupfile=lookupfile
108              lookupfile names the file that contains the  PAM  or  PNM  image
109              that is the lookup table.  This option is mandatory.
110
111
112       -missingcolor=color
113              This  option  is meaningful only if the lookup image (and there‐
114              fore the output) is a PNM image.  color specifies the color that
115              is  to go in the output wherever the index from the input is not
116              present in the lookup table (not present means the index exceeds
117              the  dimensions of the lookup image -- e.g. index is 100 but the
118              lookup image is a 50 x 1 PPM).
119
120              If you don't specify this option of  -fit,  pamlookup  uses  the
121              value  from  the top left corner of the lookup image whenever an
122              index exceeds the dimensions of the lookup image.
123
124              Specify the color (color) as described for the argument  of  the
125              ppm_parsecolor() library routine ⟨libppm.html#colorname⟩ .
126
127              Another  way to deal with a too-small lookup image is to use the
128              -fit option.
129
130
131       -fit   This option says to shrink or expand the lookup image as  neces‐
132              sary  to  fit  the  indices  present in the index image, per the
133              index image's maxval.  For example, if your index  image  has  a
134              single  plane and a maxval of 255 and your lookup image is 1 row
135              of 10 columns, pamlookup stretches your lookup image to 255 col‐
136              umns  before  doing  the lookups.  pamlookup does the stretching
137              (or shrinking) with the pamscale(1) program.
138
139              When you use -fit, pamlookup never fails or  warns  you  due  to
140              invalid  lookup  image  dimensions, and the -missingcolor option
141              has no effect.
142
143
144
145

EXAMPLES

147   Example: rainfall map
148       Say you have a set of rainfall data in a single plane PAM  image.   The
149       rows and columns of the PAM indicate lattitude and longitude.  The sam‐
150       ple values are the annual rainfall in (whole) centimeters.  The highest
151       rainfall  value  in  the image is 199 centimeters.  The image is in the
152       file rainfall.pam.
153
154       You want to produce a PPM rainfall  map  with  green  for  the  wettest
155       places, red for the driest, and other colors in between.
156
157       First,  compose  a lookup table image, probably with a graphical editor
158       and the image blown way up so you can work with individual pixels.  The
159       image  must have a single row and 200 columns.  Make the leftmost pixel
160       red and the rightmost pixel green  and  choose  appropriate  colors  in
161       between.  Call it colorkey.ppm.
162
163           pamlookup rainfall.ppm -lookupfile=colorkey.ppm >rainfallmap.ppm
164
165       Now  lets  say  you're  too lazy to type in 200 color values and nobody
166       really cares about the places that have more  than  99  centimeters  of
167       annual rainfall.  In that case, just make colorkey.ppm 100 columns wide
168       and do this:
169
170           pamlookup rainfall.ppm -lookupfile=colorkey.ppm -missingcolor=black        >rainfallmap.ppm
171
172       Now if there are areas that get more than 100 centimeters of  rainfall,
173       they will just show up black in the output.
174
175
176   Example: graphical diff
177       Say  you  want  to  compare  two PBM (black and white) images visually.
178       Each consists of black foreground pixels on a  white  background.   You
179       want to create an image that contains background where both images con‐
180       tain background and foreground where both  images  contain  foreground.
181       But where Image 1 has a foreground pixel and Image 2 does not, you want
182       red in the output; where Image 2 has a foreground  pixel  and  Image  1
183       does not, you want green.
184
185       First, we create a single image that contains the information from both
186       input PBMs:
187
188           pamstack image1.pbm image2.pbm >bothimages.pam
189
190       Note that this image has 1 of 4 possible tuple values at each location:
191       (0,0), (0,1), (1,0), or (1,1).
192
193       Now, we create a lookup table that we can index with those 4 values:
194
195           ppmmake white 1 1 >white.ppm
196           ppmmake black 1 1 >black.ppm
197           ppmmake red   1 1 >red.ppm
198           ppmmake green 1 1 >green.ppm
199           pnmcat -leftright black.ppm red.ppm   >blackred.ppm
200           pnmcat -leftright green.ppm white.ppm >greenwhite.ppm
201           pnmcat -topbottom blackred.ppm greenwhite.ppm >lookup.ppm
202
203       Finally,  we look up the indices from our index in our lookup table and
204       produce the output:
205
206           pamlookup bothimages.ppm -lookupfile=lookup.ppm >imagediff.ppm
207
208
209

SEE ALSO

211       pnmremap(1), ppmmake(1), pnmcat(1), pamstack(1), pnm(1), pam(1)
212
213
214

HISTORY

216       pamlookup was new in Netpbm 10.13 (December 2002).
217
218
219
220netpbm documentation           10 November 2002       Pamlookup User Manual(0)
Impressum