Manual: pamlookup
Pamlookup User Manual(1) General Commands Manual Pamlookup User Manual(1)
NAME
pamlookup - map an image to a new image by using it as indices into a table
SYNOPSIS
pamlookup -lookupfile=lookupfile [-byplane] -missingcolor=color [-fit] indexfile
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.
DESCRIPTION
This program is part of Netpbm(1).
pamlookup takes a two dimensional array of indices and a lookup table as input. For each position in the index ar‐
ray, 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: whole tuple and by plane. The -byplane option controls which pam‐
lookup does.
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.
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.
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.
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.
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. pamlookup 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.
With by-plane indexing, the output thus has the same dimensions as the index image an the same maxval as the lookup
image.
The Lookup Table Image
The lookup table is a PAM or PNM image. If the index image contains whole number indices, the lookup image is a sin‐
gle row and the index is a column number. The lookup result is the value of the tuple or pixel at the indicated col‐
umn 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.
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 pamlookup deals with a lookup image
that does not have such a width:
• Scale the lookup image to the required width. pamlookup always does this with by plane indexing, and with
whole tuple indexing, does it when you specify -fit.
• Use a default value for indices that exceed the width of the lookup image and ignore lookup image columns be‐
yond the maxval of the index image. pamlookup does this with whole tuple indexing when you don't specify
-fit.
You specify the default value with a -missingcolor option; it defaults to the value from the top left corner
of the lookup image.
With ordered pair indexes (which implies whole tuple indexing), the same rule applies to the height of the index im‐
age as to the width.
The mandatory -lookupfile option identifies the file containing the lookup table image. - means Standard Input. It
won't work if both the index image file and lookup table file are Standard Input.
You can use ppmmake and pamcat to create a lookup table file.
Example - Whole Tuple Indexing
Here is an example of pamlookup's function with whole tuple indexing (-byplane not specified).
Consider an index image consisting of a 3x2x1 PAM as follows:
0 1 0
2 2 2
and a lookup table consisting of a 3x1 PPM image as follows:
red yellow beige
The lookup table above says Index 0 corresponds to the color red, Index 1 corresponds to yellow, and Index 2 corre‐
sponds to beige. The output of pamlookup is the following PPM image:
red yellow red
beige beige beige
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:
(0,0) (0,1) (0,0)
(1,1) (1,0) (0,0)
Our lookup table for the example will be this two dimensional PPM:
red yellow red
black green red
Example - By Plane Indexing
Here is an example of pamlookup's function with by plane tuple indexing (-byplane specified).
Consider an index image consisting of a 3x2x3 PAM as follows:
(0,0,0) (1,0,0) (2,0,0)
(2,2,0) (2,0,2) (2,0,0)
and a lookup table consisting of a 3x1x1 PAM image with maxval 7 as follows:
3 4 7
The lookup table above says Index 0 corresponds to the sample value 3, Index 1 corresponds to 4, and Index 2 corre‐
sponds to 7. The output of pamlookup is the following 3x2x3 PAM image:
(3,3,3) (4,3,3) (7,3,3)
(7,7,3) (7,3,7) (7,3,3)
Miscellaneous
The indexfile argument identifies the file containing the index PAM or PNM image. - 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.
If you want to use two separate 1-plane images as indices (so that your output reflects the combination of both in‐
puts), use pamstack to combine the two into one two-plane image (and use a 2-dimensional lookup table image).
OPTIONS
In addition to the options common to all programs based on libnetpbm (most notably -quiet, see Common Options ),
pamlookup recognizes the following command line options:
-lookupfile=lookupfile
lookupfile names the file that contains the PAM or PNM image that is the lookup table. This option is manda‐
tory.
-byplane
This options selects by plane indexing. The default is whole tuple indexing.
This option was new in Netpbm 10.72 (September 2015). Before that, there is no by plane indexing.
-missingcolor=color
This option is meaningful only if the lookup image (and therefore the output) is a PNM image. color 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).
If you don't specify this option or -fit, pamlookup uses the value from the top left corner of the lookup im‐
age whenever an index exceeds the dimensions of the lookup image.
Specify the color (color) as described for the argument of the pnm_parsecolor() library routine .
Another way to deal with a too-small lookup image is to use the -fit option.
This option has no effect if you also specify -fit or -byplane.
-fit This option says to shrink or expand the lookup image as necessary to fit the indices present in the index im‐
age, 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, pamlookup stretches your lookup image to 255 columns before do‐
ing the lookups. pamlookup does the stretching (or shrinking) with the pamscale(1) program.
When you use -fit, pamlookup never fails or warns you because of invalid lookup image dimensions, and the
-missingcolor option has no effect.
-fit has no effect when you specify -byplane. pamlookup always has the behavior requested by -fit when it
does by plane indexing.
EXAMPLES
Example: rainfall map
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.
You want to produce a PPM rainfall map with green for the wettest places, red for the driest, and other colors in be‐
tween.
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.
pamlookup rainfall.pam -lookupfile=colorkey.ppm >rainfallmap.ppm
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:
pamlookup rainfall.ppm -lookupfile=colorkey.ppm -missingcolor=black \
>rainfallmap.ppm
Now if there are areas that get more than 100 centimeters of rainfall, they will just show up black in the output.
Example: graphical diff
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.
First, we create a single image that contains the information from both input PBMs:
pamstack image1.pbm image2.pbm >bothimages.pam
Note that this image has 1 of 4 possible tuple values at each location: (0,0), (0,1), (1,0), or (1,1).
Now, we create a lookup table that we can index with those 4 values:
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
Finally, we look up the indices from our index in our lookup table and produce the output:
pamlookup bothimages.ppm -lookupfile=lookup.ppm >imagediff.ppm
SEE ALSO
pamunlookup(1), pnmremap(1), ppmmake(1), pamcat(1), pamstack(1), pnm(1), pam(1)
HISTORY
pamlookup was new in Netpbm 10.13 (December 2002).
DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML source. The master documentation is at
http://netpbm.sourceforge.net/doc/pamlookup.html
netpbm documentation 25 July 2015 Pamlookup User Manual(1)