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>

       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++) {
           pnm_readpamrow(&inpam, tuplerow);
           for (column = 0; column < inpam.width; column++) {
               for (sample = 0; sample < inpam.depth; column++) {
                   grand_total += tuplerow[row][column][sample];
               }
           }
           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_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 );

       void pnm_writepaminit( struct pam *pamP);

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

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

       void  pnm_writepnmrow(  FILE  *fp,  xel *xelrow, int cols,
       xelval maxval, 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 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);

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



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 oper­
       ate on all three, both reading and writing, without a  lot
       of concern for which of the three formats you are process­
       ing.

       The pam functions provide all the same functions for oper­
       ating  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  for­
       mat, 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  conve­
       nient  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  pro­
              grams  compatible  with newer and older versions of
              the Netpbm libraries.

       file   The file.

              MAT unless the PAM image is really a view of a PBM,
              PGM, or PPM image.  Then it's PBM_FORMAT, RPBM_FOR­
              MAT, 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 sam­
              ples 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  spec­
       ify  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

       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  con­
       vert the output of your program to plain format.

   PNM TYPES AND CONSTANTS
       Each xel contains three xelvals, each of which should con­
       tain only the values between 0 and  PNM_MAXMAXVAL,  inclu­
       sive.  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_FOR­
       MAT_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 for­
       mats: 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().

       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  posi­
       tioned  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

       height, width, and depth of the image, in that order.

       pnm_readpam() combines the  functions  of  pnm_allocpamar­
       ray(),  pnm_readpaminit(),  and iterations of pnm_readpam­
       row().  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_sam­
       ple 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

       write: size, len, file, format, height, width, depth, max­
       val, 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_backgroundxelrow() figures out  an  appropriate  back­
       ground  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_back­
       groundxelrow(), 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 representa­
       tion (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.


Man(1) output converted with man2html