.TL
Pamlookup User Manual
.SH 1
pamlookup
.LP
Updated: 10 November 2002
.br
Table Of Contents
.SH 2
NAME
.LP
pamlookup - map an image to a new image by using it as indices into a table
.SH 2
SYNOPSIS
.LP
\fBpamlookup\fR
\fB-lookupfile=\fR\fIlookupfile\fR
\fB-missingcolor=\fR\fIcolor\fR
[\fB-fit\fR]
\fIindexfile\fR
.LP
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.
.SH 2
DESCRIPTION
.LP
.LP
This program is part of Netpbm.
.LP
\fBpamlookup\fR takes a two dimensional array of indices and a lookup
table as input.  For each position in the index array, it looks up the index
in the lookup table and places the result of the lookup in the output image.
The output thus has the same width and height as the index image, and tuple
types determined by the lookup table.
.LP
An index is either a whole number or an ordered pair of whole
numbers.  If the index image has a depth of one, each index in it is a
whole number: the value of the one sample.  If the index image has a
depth greater than one, each index in it is an ordered pair of the first
and second samples in the relevant tuple.
.LP
The lookup table is a PAM or PNM image.  If the index image
contains whole number indices, the lookup image is a single row and
the index is a column number.  The lookup result is the value of the
tuple or pixel at the indicated column 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.
.LP
For example:  Consider an index image consisting of a 3x2x1 PAM
as follows:
.TS
center ;
<?makeman l l l. ?>
<tr>
 <td>
0</td>
 <td>
1</td>
 <td>
0</td>
 </tr>

<tr>
 <td>
2</td>
 <td>
2</td>
 <td>
2</td>
 </tr>

.TE
and a lookup table consisting of a 3x1 PPM image as follows:
.TS
center ;
<?makeman l l l. ?>
<tr>
 <td>
red</td>
 <td>
yellow</td>
 <td>
beige</td>
 </tr>

.TE
The lookup table above says Index 0 corresponds to the color red,
Index 1 corresponds to yellow, and Index 2 corresponds to beige.  The output
of \fBpamlookup\fR is the following PPM image:
.TS
center ;
<?makeman l l l. ?>
<tr>
 <td>
red</td>
 <td>
yellow</td>
 <td>
red</td>
 </tr>

<tr>
 <td>
beige</td>
 <td>
beige</td>
 <td>
beige</td>
 </tr>

.TE
.LP
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:
.TS
center ;
<?makeman l l l. ?>
<tr>
 <td>
(0,0)</td>
 <td>
(0,1)</td>
 <td>
(0,0)</td>
 </tr>

<tr>
 <td>
(1,1)</td>
 <td>
(1,0)</td>
 <td>
(0,0)</td>
 </tr>

.TE
Our lookup table for the example will be this two dimensional PPM:
.TS
center ;
<?makeman l l l. ?>
<tr>
 <td>
red</td>
   <td>
yellow</td>
 </tr>

<tr>
 <td>
green</td>
 <td>
black</td>
 </tr>

.TE
This lookup table says Index (0,0) corresponds to the color red,
Index (0,1) corresponds to yellow, Index (1,0) corresponds to green,
and Index (1,1) corresponds to black.  The output of \fBpamlookup\fR
is the following PPM image:
.TS
center ;
<?makeman l l l. ?>
<tr>
 <td>
red</td>
   <td>
yellow</td>
 <td>
red</td>
 </tr>

<tr>
 <td>
black</td>
 <td>
green</td>
  <td>
red</td>
 </tr>

.TE
.LP
If an index specifies a row or column that exceeds the dimensions of
the lookup table image, \fBpamlookup\fR uses the value from the top left
corner of the lookup image, or the value you specify with the
\fB-missingcolor\fR option.
.LP
The \fIindexfile\fR argument identifies the file containing the index
PAM or PNM image.  \fB-\fR means Standard Input.  The mandatory
\fB-lookupfile\fR option identifies the file containing the lookup table
image.  Again, \fB-\fR 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.
.LP
You can use \fBppmmake\fR and \fBpnmcat\fR to create a lookup table file.
.LP
If you want to use two separate 1-plane images as indices (so that your
output reflects the combination of both inputs), use \fBpamstack\fR to combine
the two into one two-plane image (and use a 2-dimensional lookup table image).
.SH 2
OPTIONS
.LP
.RS
.IP "\fB-lookupfile=\fR\fIlookupfile\fR"
\fIlookupfile\fR names the file that contains the PAM or PNM
image that is the lookup table.  This option is mandatory.
.IP "\fB-missingcolor=\fR\fIcolor\fR"
This option is meaningful only if the lookup image (and therefore the 
output) is a PNM image.  \fIcolor\fR 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).
.LP
If you don't specify this option of \fB-fit\fR, \fBpamlookup\fR
uses the value from the top left corner of the lookup image whenever
an index exceeds the dimensions of the lookup image.
.LP
Specify the color (\fIcolor\fR) as described for the argument of the \fBppm_parsecolor()\fR
library routine.
.LP
Another way to deal with a too-small lookup image is to use the 
\fB-fit\fR option.
.IP "\fB-fit\fR"
This option says to shrink or expand the lookup image as necessary
to fit the indices present in the index image, 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,
\fBpamlookup\fR stretches your lookup image to 255 columns before
doing the lookups.  \fBpamlookup\fR does the stretching (or
shrinking) with the \fBpamscale\fR
program.
.LP
When you use \fB-fit\fR, \fBpamlookup\fR never fails or warns you
due to invalid lookup image dimensions, and the \fB-missingcolor\fR
option has no effect.
.RE
.SH 2
EXAMPLES
.LP
.SH 3
Example: rainfall map
.LP
.LP
Say you have a set of rainfall data in a single plane PAM image.
The rows and columns of the PAM indicate lattitude 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.
.LP
You want to produce a PPM rainfall map with green for the wettest places,
red for the driest, and other colors in between.
.LP
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.
.DS L
\f(CW    pamlookup rainfall.ppm -lookupfile=colorkey.ppm >rainfallmap.ppm
\fR.DE
.LP
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:
.DS L
\f(CW    pamlookup rainfall.ppm -lookupfile=colorkey.ppm -missingcolor=black \
       >rainfallmap.ppm
\fR.DE
Now if there are areas that get more than 100 centimeters of rainfall, they
will just show up black in the output.
.SH 3
Example: graphical diff
.LP
.LP
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.
.LP
First, we create a single image that contains the information from both
input PBMs:
.DS L
\f(CW    pamstack image1.pbm image2.pbm >bothimages.pam
\fR.DE
Note that this image has 1 of 4 possible tuple values at each location:
(0,0), (0,1), (1,0), or (1,1).
.LP
Now, we create a lookup table that we can index with those 4 values:
.DS L
\f(CW    ppmmake white 1 1 >white.ppm
    ppmmake black 1 1 >black.ppm
    ppmmake red   1 1 >red.ppm
    ppmmake green 1 1 >green.ppm
    pnmcat -leftright black.ppm red.ppm   >blackred.ppm
    pnmcat -leftright green.ppm white.ppm >greenwhite.ppm
    pnmcat -topbottom blackred.ppm greenwhite.ppm >lookup.ppm
\fR.DE
.LP
Finally, we look up the indices from our index in our lookup table and
produce the output:
.DS L
\f(CW    pamlookup bothimages.ppm -lookupfile=lookup.ppm >imagediff.ppm
\fR.DE
.SH 2
SEE ALSO
.LP
pnmremap,
ppmmake,
pnmcat,
pamstack,
pnm,
pam
.SH 2
HISTORY
.LP
.LP
\fBpamlookup\fR was new in Netpbm 10.13 (December 2002).
.br
\l'5i'
.SH 2
Table Of Contents
.LP
.IP \(bu
NAME
.IP \(bu
SYNOPSIS
.IP \(bu
DESCRIPTION
.IP \(bu
OPTIONS
.IP \(bu
EXAMPLES
.IP \(bu
HISTORY
.IP \(bu
SEE ALSO
.LP