pamlookup



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 num-
       ber: 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 number.  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 fol-
       lows:


       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  fol-
       lowing 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 cor-
       ner  of  the  lookup image, or the value you specify with the -missing-
       color 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  Out-
       put.

       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  com-
       bine  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 there-
              fore 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  neces-
              sary  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 lattitude and longitude.  The sam-
       ple 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 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 con-
       tain 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)

Man(1) output converted with man2html