man > pamlookup(1)

Pamlookup User Manual(1)               General Commands Manual              Pamlookup User Manual(1)

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 in‐
       stead 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 po‐
       sition 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 op‐
       tion 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  or‐
       dered  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 are 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 in‐
       dices composed of the first and second sample in the tuple.

       In  by-plane indexing, the index image contains whole number indices.  Each sample in the in‐
       dex image is an index.  The lookup table maps each whole number index to another  whole  num‐
       ber.   pamlookup looks up the sample at each row, column, and plane in the index image in the
       lookup table and uses the resulting whole number as the sample value for the same  row,  col‐
       umn, 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 pamcat to create a lookup table file.



   Example - Whole Tuple Indexing
       Here  is  an  example  of pamlookup's function with whole tuple indexing (-byplane not speci‐
       fied).

       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 yel‐
       low, 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  Stan‐
       dard 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 ]8;;index.html#commonoptions\ Common Options]8;;\ ), 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 im‐
              age.

              Specify the color (color) as described  for  the  ]8;;libnetpbm_image.html#colorname\argument of the pnm_parsecolor() li‐
              brary routine]8;;\ .

              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  re‐
              quested 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 col‐
       orkey.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 back‐
       ground where both images contain background and foreground where both  images  contain  fore‐
       ground.   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
           pamcat -leftright black.ppm red.ppm   >blackred.ppm
           pamcat -leftright green.ppm white.ppm >greenwhite.ppm
           pamcat -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), pamcat(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

netpbm documentation                        25 July 2015                    Pamlookup User Manual(1)