Provided by: libnetpbm9-dev_10.0-12_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)