Provided by: libnetpbm9-dev_10.0-12.2_i386 bug

NAME

       libpnm - functions to support pnm and pam programs

EXAMPLE

       /* Example program fragment to read a PAM or PNM image
          from stdin, add up the values of every sample in it
          (I don't know why), and write the image unchanged to
          stdout.  */

       #include <pam.h>

       struct pam inpam, outpam; unsigned int row;

       pnm_init(&argc, argv);

       pnm_readpaminit(stdin, &inpam, sizeof(inpam));

       outpam = inpam; outpam.file = stdout;

       pnm_writepaminit(&outpam);

       tuplerow = pnm_allocpamrow(&inpam);

       for (row = 0; row < inpam.height; row++) {
           unsigned int col;
           pnm_readpamrow(&inpam, tuplerow);
           for (column = 0; column < inpam.width; column++) {
               unsigned int plane;
               for (plane = 0; plane < inpam.depth; column++) {
                   grand_total += tuplerow[row][column][plane];
               }
           }
           pnm_writepamrow(&outpam, tuplerow); }

       pnm_freepamrow(tuplerow);

SYNOPSIS

       #include <pnm.h>

       void pnm_init( int *argcP, char *argv[] );

       tuple ** pnm_allocpamarray( struct pam *pamP);

       xel ** pnm_allocarray( int cols, int rows);

       tuple * pnm_allocpamrow( struct pam *pamP);

       xel * pnm_allocrow( int cols);

       void pnm_freepamarray( tuple **tuplearray, struct pam *pamP);

       void pnm_freearray( xel **xels, int rows);

       void pnm_freepamrow( tuple *tuplerow);

       void pnm_freerow( xel *xelrow);

       tuple * allocpamtuple( struct pam *pamP);

       void pnm_freepamtuple( tuple tuple );

       void pnm_readpaminit( FILE *file, struct pam *pamP, int size);

       void   pnm_readpnminit(  FILE  *fp,  int  *colsP,  int  *rowsP,  xelval
       *maxvalP, int *formatP );

       void pnm_readpamrow( struct pam *pamP, tuple *tuplerow);

       void pnm_readpnmrow( FILE *fp, xel *xelrow, int cols,
       xelval maxval, int format );

       tuple ** pnm_readpam( FILE *file, struct pam *pamP,
       int size);

       xel ** pnm_readpnm( FILE *fp, int *colsP, int *rowsP,
       xelval *maxvalP, int* formatP );"

       void pnm_writepaminit( struct pam *pamP);

       void pnm_writepnminit( FILE *  fp , int cols, int rows, xelval  maxval,
       int format, int forceplain);

       void pnm_writepamrow( struct pam *pamP, const tuple *tuplerow);

       void  pnm_writepnmrow(  FILE *fp, xel *xelrow, int cols, xelval maxval,
       int format, int forceplain );

       void pnm_writepam( struct pam *pamP, const tuple * const *tuplearray);

       void pnm_writepnm( FILE *fp, xel ** xels, int cols,  int  rows,  xelval
       maxval, int format, int forceplain );

       void   pnm_checkpam(   struct   pam  *pamP,  const  enum  pm_check_type
       check_type, enum pm_check_code *retvalP);

       void pnm_nextimage( FILE *file, int * const eofP);

       void pnm_check( FILE * file, const enum pm_check_type check_type, const
       int  format,  const int cols, const int rows, const xelval maxval, enum
       pm_check_code *retvalP);

       void pnm_promoteformatrow( xel *xelrow, int cols,  xelval  maxval,  int
       format, xelval newmaxval, int newformat);

       void  pnm_promoteformatrow(  xel  **xels,  int cols, xelval maxval, int
       format, xelval newmaxval, int newformat);

       xel pnm_whitexel( xelval maxval, int format);

       xel pnm_blackxel( xelval maxval, int format);

       void pnm_invertxel( xel *x, xelval maxval, int format);

       xel pnm_backgroundxelrow( xel *xelrow, int  cols,  xelval  maxval,  int
       format);

       xel  pnm_backgroundxel(  xel **xels, int cols, int rows, xelval maxval,
       int format);

       void pnm_YCbCrtuple( tupletuple, double *YP, double *CrP, double *CbP);

       struct pam {
       int size
       int len
       FILE * file
       int format
       int plainformat
       int height
       int width
       int depth
       sample maxval
       int bytes_per_sample
       char tuple_type[256]; }

       typedef ... sample;

       typedef ... tuple;

       typedef ... xelval;

       typedef ... xel;

       extern xelval pnm_pbmmaxval;

       #define PNM_MAXMAXVAL ...

       #define PNM_OVERALLMAXVAL ...

       #define PNM_FORMAT ...

       #define PNM_ASSIGN1(x,v) ...

       #define PNM_GET1(x) ...

       #define PNM_EQUAL(x,y) ...

       #define PAM_FORMAT_TYPE(format) ...

       #define PNM_FORMAT_TYPE(format) ...

DESCRIPTION

   PAM VERSUS PNM FUNCTIONS
       The PNM library contains two classes of functions:  The  pam  functions
       and  the  pnm functions.  The pam functions are enhancements of the pnm
       functions and you should use them unless you need to be compatible with
       older  PNM libraries that don't have them (those released before August
       2000).

       The pnm functions operate on PBM, PGM, and PPM images and files.   They
       are similar to the functions in the PBM, PGM, and PPM libraries, except
       the pnm functions let you  operate  on  all  three,  both  reading  and
       writing,  without  a  lot of concern for which of the three formats you
       are processing.

       The pam functions provide all the same functions for operating on  PBM,
       PGM,  and  PPM  libraries, but also operate on the newer PAM images and
       files.  The pam functions are easier to use than the pnm functions  due
       to improved parameter lists.

       There  is  no separate PAM library specific to the PAM format, as there
       is for PBM, PGM, and PPM.

   THE pam STRUCTURE
       The pam functions take most of their arguments in the form of a  single
       pam structure.  This is not an opaque object, but just a convenient way
       to organize the information upon which most the functions  depend.   So
       you are free to access or set the elements of the structure however you
       want.  But you will find in most cases it is most  convenient  to  call
       pnm_readpaminit()  or  pnm_writepaminit()  to set the fields in the pam
       structure before calling any other pam functions, and then just to pass
       the structure unchanged in all future calls to pam functions.

       The fields are:

       size   The storage size in bytes of this entire structure.

       len    The length, in bytes, of the information in this structure.  The
              information starts in the first byte and  is  contiguous.   This
              cannot  be  greater than size.  size and len can be used to make
              programs compatible with newer and older versions of the  Netpbm
              libraries.

       file   The file.

       format The format code of the raw image.  This is PAM_FORMAT unless the
              PAM image is really a view of a PBM, PGM, or  PPM  image.   Then
              it's PBM_FORMAT, RPBM_FORMAT, etc.

       plainformat
              This  is a boolean value and means:  The format above is a plain
              (text) format as opposed to a  raw  (binary)  format.   This  is
              entirely  redundant  with  the  format  member  and  exists as a
              separate member only for computational speed.

       height The height of the image in rows.

       width  The width of the image in number of columns (tuples per row).

       depth  The depth of the image (degree of or number of samples  in  each
              tuple).

       maxval The maxval of the image.  See definitions in pam(5).

       bytes_per_sample
              The  number  of bytes used to represent each sample in the image
              file.  See the format definition in pam(5).   This  is  entirely
              redundant  with  maxval.   It  exists  as  a separate member for
              computational speed.

       tuple_type
              The tuple type of the image.  See definitions in pam(5).  Netpbm
              does  not define any values for this except the following, which
              are used for a PAM image which is really a view of a  PBM,  PGM,
              or     PPM    image:    PAM_PBM_TUPLETYPE,    PAM_PGM_TUPLETYPE,
              PAM_PPM_TUPLETYPE.

   PLAIN VERSUS RAW FORMAT
       The PNM formats each come in two  varieties:  the  older  plain  (text)
       format  and  the newer raw (binary) format.  There are different format
       codes for the plain and raw formats, but which of the two  formats  the
       pnm  and pam functions write is independent of the format code you pass
       to them.

       The pam functions always write raw formats.  If you specify the  format
       code for a plain format, a pam function assumes instead the raw version
       of that format.

       The pnm functions choose between plain and raw based on the  forceplain
       parameter  that  every  write-type  pnm  function has.  If this boolean
       value is true, the function writes the  plain  version  of  the  format
       specified  by the format code.  If it is false, the function writes the
       raw version of the format specified by the format code.

       We are trying to stamp out the older plain formats, so it  would  be  a
       wise  choice not to write a program that sets forceplain true under any
       circumstance.   A  user  who  needs  a  plain  format   can   use   the
       pnmtoplainpnm  program  to  convert the output of your program to plain
       format.

   PNM TYPES AND CONSTANTS
       Each xel contains three xelvals, each of which should contain only  the
       values  between  0  and PNM_MAXMAXVAL, inclusive.  pnm_pbmmaxval is the
       maxval used when a PNM program reads a PBM file.   Normally  it  is  1;
       however, for some programs, a larger value gives better results.

   PNM XEL MANIPULATIONS
       The  PNM_GET1  macro extracts a single value from an xel, when you know
       it's from a  PBM  or  PGM  file.   When  it's  from  a  PPM  file,  use
       PPM_GETR(), PPM_GETG(), and PPM_GETB().

       The  PNM_ASSIGN1  macro assigns a single value to an xel, when you know
       it's from a  PBM  or  PGM  file.   When  it's  from  a  PPM  file,  use
       PPM_ASSIGN.   The  PNM_EQUAL  macro  checks two xels for equality.  The
       PNM_FORMAT_TYPE and PAM_FORMAT_TYPE macros compute a format  type  code
       from  a format code.  The format types are PBM, PGM, PPM, and PAM.  But
       note that PBM, PGM, and PPM each are two different formats: a plain one
       and  a  raw  one.   So  there are four format types, but seven formats.
       PNM_FORMAT_TYPE does not work on the PAM format code.

   INITIALIZATION
       All PNM and PAM programs  must  call  pnm_init()  just  after  startup,
       before they process their arguments.

       pnm_init(),  among  other things, processes Netpbm universal parameters
       and removes them from the parameter list.

   MEMORY MANAGEMENT
       pnm_allocpamarray()  allocates  space   for   an   array   of   tuples.
       pnm_freepamarray()     frees    an    array    space    allocated    by
       pnm_allocpamarray() or pnm_readpam().

       pnm_allocarray() allocates space for an array of xels.  pnm_freearray()
       frees an array space allocated by pnm_allocarray() or pnm_readpnm().

       pnm_allocpamrow()   allocates   space   for  a  row  of  a  PAM  image.
       pnm_freepamrow() frees it.

       pnm_allocrow() allocates space for a row of a PNM image.  pnm_freerow()
       frees it.

   READING PNM FILES
       pnm_readpaminit()  reads  the header of a PAM or PNM image.  It returns
       the information from the header in the *pamP structure.   It  does  not
       require  any  members  of *pamP to be set at invocation, and sets every
       member.  size is the storage size  of  the  *pamP  structure,  normally
       sizeof(struct pam).

       The  function expects to find the image file positioned to the start of
       the header and leaves it positioned to the start of the raster.

       pnm_readpnminit() is similar to pnm_readpaminit(), but reads  only  PNM
       images and has a different parameter list.

       pnm_readpamrow()  reads  a  row  of  the raster from a PAM or PNM image
       file.  It expects all of the members of the *pamP structure to  be  set
       upon  invocation  and  does not modify any of them.  It expects to find
       the file positioned to the start of the row in question in  the  raster
       and  leaves  it  positioned  just  after it.  It returns the row as the
       array of tuples tuplerow, which must already have its  column  pointers
       set up so that it forms a C 2-dimensional array.  The leftmost tuple is
       Element 0 of this array.

       pnm_readpnmrow() is similar to pnm_readpamrow() but only works  on  PNM
       images  and  has  a  different parameter list and returns the row as an
       array of xels instead of tuples.

       pnm_readpam() reads an entire image from a PAM or PNM  image  file  and
       allocates  the space in which to return the raster.  It expects to find
       the file positioned to the first  byte  of  the  image  and  leaves  it
       positioned just after the image.

       The  function does not require *pamP to have any of its members set and
       sets them all.  size  is  the  storage  size  in  bytes  of  the  *pamP
       structure, normally sizeof(struct pam).

       The  return  value is a newly allocated array of the rows of the image,
       with the top row being Element 0 of the array.  Each row is represented
       as pnm_readpamrow() would return.

       The  return  value  is  also  effectively  a  3-dimensional  C array of
       samples, with the dimensions corresponding to the  height,  width,  and
       depth of the image, in that order.

       pnm_readpam()    combines   the   functions   of   pnm_allocpamarray(),
       pnm_readpaminit(), and iterations of pnm_readpamrow().  It may  require
       more dynamic storage than you can afford.

       pnm_readpnm() is similar to pnm_readpam() except that it reads only PNM
       images and uses a different parameter list and returns an array of rows
       such   that   pnm_readpnmrow()  would  return  rather  than  such  that
       pnm_readpamrow() would return.

   WRITING FILES
       pnm_writepnminit() writes the header of a PAM or PNM image and computes
       some of the fields of the pam structure.

       The  following  members  of  the  *pamP  structure  must  be  set  upon
       invocation to tell the function how and  what  to  write.   size,  len,
       file, format, height, width, depth, maxval, tuple_type.

       pnm_writepaminit()  sets  the  plainformat and bytes_per_sample members
       based on the information supplied.

       pnm_writepnminit() is similar to pnm_writepaminit() except that it  can
       write only a PNM header and has a different parameter list.

       See the description of forceplain above.

       pnm_writepamrow()  writes  a  row of the raster into a PAM or PNM image
       file.  It expects to find the file  positioned  where  the  row  should
       start  and  leaves  it  positioned  just  after  the row.  The function
       requires all the elements of  *pamP  to  be  set  upon  invocation  and
       doesn't modify them.

       tuplerow  is  an  array  of  tuples representing the row.  The leftmost
       tuple is Element 0 of this array.

       pnm_writepnmrow() is similar to pnm_writepamrow() except that it  works
       only  on  PNM  images  and  has a different parameter list and takes an
       array of xels instead of an array of tuples.  See  the  description  of
       forceplain above.

       pnm_writepam()  writes an entire PAM or PNM image to a PAM or PNM image
       file.  It expects to find the file positioned to where the image should
       start and leaves it positioned just after the image.

       The  following  members  of  the  *pamP  structure  must  be  set  upon
       invocation to tell the function how and what to write: size, len, file,
       format, height, width, depth, maxval, tuple_type.

       pnm_writepam()  sets the plainformat and bytes_per_sample members based
       on the information supplied.

       tuplearray  is  an  array  of  rows  such  that  you  would   pass   to
       pnm_writepamrow(), with the top row being Element 0 of the array.

       pnm_writepam()   combines  the  functions  of  pnm_writepaminit(),  and
       iterations of pnm_writepamrow().  It's raster input may be more storage
       than you can afford.

       pnm_writepnm()  is  similar to pnm_writepam() except that it works only
       on PNM image, has a different parameter list, and  takes  an  array  of
       rows  of  xels  instead  of  an  array  of  rows  of  tuples.   See the
       description of forceplain above.

   MISCELLANEOUS
       pnm_nextimage() positions a PNM input file to the next image in it  (so
       that a subsequent pnm_readpnminit() reads its header).

       pnm_nextimage() is identical to pbm_nextimage().

       pam_check()  checks  for the common file integrity error where the file
       is the wrong size to contain the raster, according to  the  information
       in the header.  This works on PAM and PNM images.

       pnm_check()  is  similar  to  pam_check()  except  it works only on PNM
       images.

       pnm_check() is identical to ppm_check().

   PNM FORMAT PROMOTION
       pnm_promoteformatrow() promotes a row  of  xels  from  one  maxval  and
       format  to a new set.  Use this when you are combining multiple anymaps
       of different types - just take the  maximum  of  the  maxvals  and  the
       maximum of the formats, and promote them all to that.

       pnm_promoteformat() promotes an entire anymap.

   PNM XEL MANIPULATION
       pnm_whitexel()   and  pnm_blackxel()  return  a  white  or  black  xel,
       respectively, for the given maxval and format.

       pnm_invertxel() inverts an xel.

       pnm_backgroundxelrow() figures out an appropriate background xel  based
       on  the row of xels xelrow, which is cols xels wide, has maxval maxval,
       and represents an image with format format.

       This estimate works best when the row is the top or bottom row  of  the
       image.

       pnm_backgroundxel()  does  the  same  thing  as pnm_backgroundxelrow(),
       except based on an entire image instead of just one row.  This tends to
       do a slightly better job than pnmbackgroundxelrow().

       pnm_YCbCrtuple()     Returns    the    Y/Cb/Cr    luminance/chrominance
       representation of the color represented by the  input  tuple,  assuming
       that  the tuple is an RGB color representation (which is the case if it
       was read from a PPM image).  The output components  are  based  on  the
       same  scale  (maxval)  as  the  input  tuple,  but  are  floating point
       nonetheless to avoid losing information due to rounding.   Divide  them
       by the maxval to get normalized [0..1] values.

SEE ALSO

       pbm(5), pgm(5), ppm(5), pam(5), libpbm(3), libpgm(3), libppm(3)

AUTHOR

       Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.

                                                                     libpnm(3)