pamlookup - Man Page

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.

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 beyond 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 image 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 pnmcat to create a lookup table file.

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:

and a lookup table consisting of a 3x1 PPM image as follows:

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 pamlookup is the following PPM image:

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:

Our lookup table for the example will be this two dimensional PPM:

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:

and a lookup table consisting of a 3x1x1 PAM image with maxval 7 as follows:

The lookup table above says Index 0 corresponds to the sample value 3, Index 1 corresponds to 4, and Index 2 corresponds to 7.  The output of pamlookup is the following 3x2x3 PAM image:

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 inputs), use pamstack to combine the two into one two-plane image (and use a 2-dimensional lookup table image).

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 between.

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.

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
    pnmcat -leftright black.ppm red.ppm   >blackred.ppm
    pnmcat -leftright green.ppm white.ppm >greenwhite.ppm
    pnmcat -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