Man Pages

pamlookup(1) - phpMan pamlookup(1) - phpMan

Command: man perldoc info search(apropos)  


Pamlookup User Manual(0)                              Pamlookup User Manual(0)



NAME
       pamlookup - map an image to a new image by using it as indices into a table


SYNOPSIS
       pamlookup -lookupfile=lookupfile -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
       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.

       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.

       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 num-
       ber.  The lookup result is the value of the tuple or pixel at the indicated row and column in the lookup table.

       For example:  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
       corresponds 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
       green   black

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


       red     yellow   red
       black   green    red

       If an index specifies a row or column that exceeds the dimensions of the lookup table image, pamlookup uses the
       value from the top left corner of the lookup image, or the value you specify with the -missingcolor option.

       The indexfile argument identifies the file containing the index PAM or PNM image.  - means Standard Input.  The
       mandatory  -lookupfile  option  identifies the file containing the lookup table image.  Again, - 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.

       You can use ppmmake and pnmcat to create a lookup table file.

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



OPTIONS
       -lookupfile=lookupfile
              lookupfile  names  the file that contains the PAM or PNM image that is the lookup table.  This option is
              mandatory.


       -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  of -fit, pamlookup uses the value from the top left corner of the
              lookup image whenever an index exceeds the dimensions of the lookup image.

              Specify the color (color) as described for the argument of the ppm_parsecolor() library routine .

              Another way to deal with a too-small lookup image is to use the -fit option.


       -fit   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, pamlookup stretches your lookup image to 255
              columns  before  doing  the  lookups.  pamlookup does the stretching (or shrinking) with the pamscale(1)
              program.

              When you use -fit, pamlookup never fails or warns you due to invalid lookup image  dimensions,  and  the
              -missingcolor option has no effect.




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 lat-
       titude 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.ppm -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 out-
       put.


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



SEE ALSO
       pnmremap(1), ppmmake(1), pnmcat(1), pamstack(1), pnm(1), pam(1)



HISTORY
       pamlookup was new in Netpbm 10.13 (December 2002).



netpbm documentation           10 November 2002       Pamlookup User Manual(0)