Provided by: netpbm_11.01.00-2build1_amd64 bug

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 array, 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 pamlookup 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 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.  The first sample  of
       each tuple in the index image is the index.  The lookup table maps each whole number index
       to another whole number.  pamlookup looks up each sample  from  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 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.

   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 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   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 corresponds 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 inputs), 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 ⟨index.html#commonoptions⟩ ), 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 mandatory.

       -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 image 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 ⟨libnetpbm_image.html#colorname⟩ .

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

   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

       pamunlookup(1), pnmremap(1), ppmmake(1), pnmcat(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