Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for libppm (redhat section 3)

libppm(3)			     Library Functions Manual				libppm(3)

NAME
       libppm - functions to support portable pixmap (PPM) programs

SYNOPSIS
       #include <ppm.h>

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

       pixel ** ppm_allocarray( int cols, int rows );

       pixel * ppm_allocrow( int cols );

       void ppm_freearray( pixel **pixels, int rows );

       void ppm_freerow( pixel *pixelrow);

       void ppm_readppminit( FILE *fp, int *colsP, int *rowsP, pixval *maxvalP, int *formatP );

       void ppm_readppmrow( FILE *fp, pixel *pixelrow, int cols, pixval maxval, int format );

       pixel ** ppm_readppm( FILE *fp, int *colsP, int *rowsP, pixvalP *maxvalP );

       void ppm_writeppminit( FILE *  fp , int cols, int rows, pixval maxval, int forceplain );

       void  ppm_writeppmrow(  FILE *fp, pixel *pixelrow, int cols, pixval maxval, int forceplain
       );

       void ppm_writeppm( FILE *fp, pixel ** pixels, int cols, int rows, pixval maxval, int  for-
       ceplain );

       void ppm_writeppm( FILE *fp, pixel **pixels, int cols, int rows, pixval maxval, int force-
       plain );

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

       void ppm_check( FILE * file, const enum pm_check_type check_type, const int format,  const
       int cols, const int rows, const int maxval,
       enum pm_check_code * const retval);

       typedef ... pixel; typedef ... pixval;

       #define PPM_MAXMAXVAL ...

       #define PPM_OVERALLMAXVAL ...

       #define PPM_FORMAT ...

       #define RPPM_FORMAT ...

       #define PPM_TYPE PPM_FORMAT

       #define PPM_FORMAT_TYPE(format) ...

       extern pixval ppm_pbmmaxval;

       pixval PPM_GETR( pixel p) pixval PPM_GETG( pixel p) pixval PPM_GETB( pixel p)

       void PPM_ASSIGN( pixel p, pixval red, pixval grn, pixval blu)

       int PPM_EQUAL( pixel p, pixel q)

       void PPM_DEPTH( pixel newp, pixel p, pixval oldmaxval, pixval newmaxval)

       float PPM_LUMIN( pixel p)

       float PPM_CHROM_R( pixel p)

       float PPM_CHROM_B( pixel p)

       pixel ppm_parsecolor( char *colorname, pixval maxval)

       char * ppm_colorname( pixel *colorP, pixval maxval, int hexok)

DESCRIPTION
   TYPES AND CONSTANTS
       Each  pixel contains three pixvals, each of which should contain only the values between 0
       and PPM_MAXMAXVAL.  ppm_pbmmaxval is the maxval used when a PPM program reads a PBM  file.
       Normally it is 1; however, for some programs, a larger value gives better results.

   MANIPULATING PIXELS
       The  macros  PPM_GETR,  PPM_GETG,  and  PPM_GETB  retrieve the red, green, or blue sample,
       respectively, from the given pixel.

       The PPM_ASSIGN macro assigns the given values to the red, green, and blue samples  of  the
       given pixel.

       The PPM_EQUAL macro tests two pixels for equality.

       The  PPM_DEPTH  macro  scales  the colors of pixel p according the old and new maxvals and
       assigns the new values to newp.	It is intended to make writing ppmtowhatever easier.

       The PPM_LUMIN, PPM_CHROM_R, and PPM_CHROM_B, macros determine the luminance,  red  chromi-
       nance,  and blue chrominance, respectively, of the pixel p.  The scale of all these values
       is the same as the scale of the input samples (i.e. 0 to maxval for  luminance,	-maxval/2
       to maxval/2 for chrominance).

       Note  that  the macros do it by floating point multiplication.  If you are computing these
       values over an entire image, it may be significantly faster to do it  with  multiplication
       tables  instead.   Compute  all	the possible products once up front, then for each pixel,
       just look up the products in the tables.

   INITIALIZATION
       All PPM programs must call ppm_init() just after invocation,  before  they  process  their
       arguments.

   MEMORY MANAGEMENT
       ppm_allocarray() allocates an array of pixels.

       ppm_allocrow() allocates a row of the given number of pixels.

       ppm_freearray()	frees the array allocated with ppm_allocarray() containing the given num-
       ber of rows.

       ppm_freerow() frees a row of pixelss allocated with ppm_allocrow().

   READING FILES
       If a function in this section is called on a PBM or PGM format file, it translates the PBM
       or  PGM	file into a PPM file on the fly and functions as if it were called on the equiva-
       lent PPM file.  The format value returned by ppm_readppminit()  is,  however,  not  trans-
       lated.  It represents the actual format of the PBM or PGM file.

       ppm_readppminit()  reads  the header of a PPM file, returning all the information from the
       header and leaving the file positioned just after the header.

       ppm_readppmrow() reads a row of pixels into the pixelrow array.	format, cols, and  maxval
       are the values returned by ppm_readppminit().

       ppm_readppm()  reads an entire PPM image into memory, returning the allocated array as its
       return value and returning the information from the header  as  rows,  cols,  and  maxval.
       This function combines ppm_readppminit(), ppm_allocarray(), and ppm_readppmrow().

   WRITING FILES
       ppm_writeppminit()  writes  the	header for a PPM file and leaves it positioned just after
       the header.

       forceplain is a logical value that tells ppm_writeppminit() to write a header for a  plain
       PPM format file, as opposed to a raw PPM format file.

       ppm_writeppmrow()  writes  the  row pixelrow to a PPM file.  For meaningful results, cols,
       maxval, and forceplain must be the same as was used with ppm_writeppminit().

       ppm_writeppm() write the header and all data for a  PPM	image.	 This  function  combines
       ppm_writeppminit() and ppm_writeppmrow().

   MISCELLANEOUS
       ppm_nextimage()	positions  a PPM input file to the next image in it (so that a subsequent
       ppm_readppminit() reads its header).

       ppm_nextimage() is analogous to pbm_nextimage(), but works on PPM, PGM, and PBM files.

       ppm_check() checks for the common file integrity error where the file is the wrong size to
       contain all the image data.

       ppm_check() is analogous to pbm_check(), but works on PPM, PGM, and PBM files.

   COLOR NAMES
       ppm_parsecolor() Interprets a color specification and returns a pixel of the color that it
       indicates.  The color specification is ASCII text, in one of three formats:  1) a name, as
       defined in the system's X11-style color names file (e.g.  rgb.txt).  2) an X11-style hexa-
       decimal triple: #rgb, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb.   3)  A  triplet  of  decimal
       floating  point	numbers  from  0.0  to 1.0, representing red, green, and blue intensities
       respectively, separated by commas.  E.g. "1.0, 0.5, .25".

       If the color specification does not conform to any of these formats,  including	the  case
       that  it is a name, but is not in the rgb.txt database, ppm_parsecolor() exits the program
       via pm_error().

       ppm_colorname() Returns a string that describes the color  of  the  given  pixel.   If  an
       X11-style  color  names	file  (e.g.   rgb.txt)	is available and the color appears in it,
       ppm_colorname() returns the name of the color from the file.  If the color does not appear
       in  a  X11-style color file and hexok is true, ppm_colorname() returns a hexadecimal color
       specification triple (#rrggbb).	If a X11-style color file is available but the color does
       not  appear  in	it  and  hexok	is false, ppm_colorname() returns the name of the closest
       matching color in the color file.  Finally, if their is no X11-style color file	available
       and hexok is false, ppm_colorname() fails and exits the program with an error message.

       The string returned is in static libppm library storage which is overwritten by every call
       to ppm_colorname().

   COLOR INDEXING
       Sometimes in processing images, you want to associate a value  with  a  particular  color.
       Most  often,  that's because you're generating a color mapped graphics format.  In a color
       mapped graphics format, the raster contains small numbers, and the file contains  a  color
       map  that  tells what color each of those small numbers refers to.  If your image has only
       256 colors, but each color takes 24 bits to describe, this can make your output file  much
       smaller than a straightforward RGB raster would.

       So,  continuing	the  above example, say you have a pixel value for chartreuse and in your
       output file you are going to represent chartreuse by the  number  12.   You  need  a  data
       structure  that	allows your program quickly to find out that 12 is the number for a char-
       treuse pixel.  Netpbm's color indexing data types and functions give you that.

       colorhash_table is a C data type that associates an integer with each of an arbitrary num-
       ber of colors.  It is a hash table, so it uses far less space than an array indexed by the
       color's RGB values would.

       The problem with a colorhash_table is that you can only look things up in it.   You  can't
       find out what colors are in it.	So Netpbm has another data type for representing the same
       information, the poorly but historically named colorhist_vector.   A  colorhist_vector  is
       just  an array.	Each entry represents a color and contains the color's value (as a pixel)
       and the integer value associated with it.  The entries are filled in  starting  with  sub-
       script 0 and going consecutively up for the number of colors in the histogram.

       (The  reason the name is poor is because a color histogram is only one of many things that
       could be represented by it).

       colorhash_table ppm_alloccolorhash()

       This creates a colorhash_table using dynamically allocated storage.  There are  no  colors
       in it.  If there is not enough storage, it exits the program with an error message.

       void ppm_freecolorhash()

       This destroys a ppm_freecolorhash and frees all the storage associated with it.

       int ppm_addtocolorhash( colorhash_table cht, const pixel * const colorP, const int value)

       This  adds  the specified color to the specified colorhash_table and associates the speci-
       fied value with it.

       You must ensure that the color you are adding isn't already present in  the  colorhash_ta-
       ble.

       There is no way to update an entry or delete an entry from a colorhash_table.

       int ppm_lookupcolor( const colorhash_table cht, const pixel * const colorP )

       This  looks up the specified color in the specified colorhash_table.  It returns the inte-
       ger value associated with that color.

       If the specified color is not in the hash table, the function  returns  -1.   (So  if  you
       assign the value -1 to a color, the return value is ambiguous).

       colorhist_vector ppm_colorhashtocolorhist( const colorhash_table cht, const int ncolors )

       This  converts  a  colorhash_table  to a colorhist_vector.  The return value is a new col-
       orhist_vector which you must eventually free with ppm_freecolorhist().

       ncolors is the number of colors in cht.	If it has more colors than that, ppm_colorhashto-
       colorhist does not create a colorhist_vector and returns NULL.

       colorhash_table ppm_colorhisttocolorhash( const colorhist_vector chv, const int ncolors )

       This poorly named function does not convert from a colorhist_vector to a colorhash_table.

       It  does create a colorhist_vector based on a colorhash_table input, but the integer value
       for a given color in the output is not the same as the integer value for that  same  color
       in the input.  ppm_colorhisttocolorhash() ignores the integer values in the input.  In the
       output, the integer value for a color is the index in the input colorhist_vector for  that
       color.

       You  can easily create a color map for an image by running ppm_computecolorhist() over the
       image, then ppm_colorhisttocolorhash() over the result.	Now you can use ppm_lookupcolor()
       to find a unique color index for any pixel in the input.

       If  the same color appears twice in the input, ppm_colorhisttocolorhash() exit the program
       with an error message.

       ncolors is the number of colors in chv.

       The return value is a new colorhash_table which you must eventually free with ppm_freecol-
       orhash().

   COLOR HISTOGRAMS
       The  Netpbm libraries give you functions to examine a Netpbm image and determine what col-
       ors are in it and how many pixels of each color are in it.  This information is known as a
       color  histogram.   Netpbm  uses  its  colorhash_table data type to represent a color his-
       togram.

       colorhash_table ppm_computecolorhash( pixel ** const pixels, const  int	cols,  const  int
       rows, const int maxcolors, int* const colorsP )

       This  poorly  but  historically named function generates a colorhash_table whose value for
       each color is the number of pixels in a specified image that have  that	color.	 (I.e.	a
       color histogram).  As a bonus, it returns the number of colors in the image.

       pixels, cols, and rows describe the input image.

       maxcolors  is  the  maximum number of colors you want processed.  If there are more colors
       that that in the input image, ppm_computecolorhash() returns NULL as its return value  and
       stops processing as soon as it discovers this.  This makes it run faster and use less mem-
       ory.  One use for maxcolors is when you just want to find out whether or not the image has
       more  than  N  colors and don't want to wait to generate a huge color table if so.  If you
       don't want any limit on the number of colors, specify maxcolors=1.

       ppm_computecolorhash() returns the actual number of colors in the image as  *colorsP,  but
       only if it is less than or equal to maxcolors.

       (It's  poorly  named because not all colorhash_tables are color histograms, but that's all
       it generates).

       colorhash_table ppm_computecolorhash2( FILE * const ifp, const int cols, const  int  rows,
       const pixval maxval, const int format, const int maxcolors, int* const colorsP )

       This  is  the same as ppm_computecolorhash() except that instead of feeding it an array of
       pixels in storage, you give it an open file stream and it reads the image from  the  file.
       The  file  must	be  positioned after the header, at the raster.  Upon return, the file is
       still open, but its position is undefined.

       maxval and format are the values for the image (i.e. information from the file's header).

       colorhist_vector ppm_computecolorhist( pixel ** pixels, int cols, int rows, int maxcolors,
       int * colorsP )

       This is like ppm_computecolorhash() except that it creates a colorhist_vector instead of a
       colorhash_table.

       You must supply as an argument (maxcolors) the maximum number of colors you expect to find
       in  the	input image.  The function allocates storage for that many regardless of how many
       actually exist.	If there are more colors than  you  say  in  the  image,  ppm_computecol-
       orhist()  returns  a  null pointer as its return value and nothing meaningful as *colorsP.
       If not, the function returns the new colorhist_vector as its return value and  the  actual
       number of colors in the image as *colorsP.

       colorhist_vector ppm_computecolorhist2( FILE * ifp,
       int cols, int rows, int maxcolors, pixval maxval, int format,
       int * colorsP )

       This  is  the same as ppm_computecolorhist() except that instead of feeding it an array of
       pixels in storage, you give it an open file stream and it reads the image from  the  file.
       The  file  must	be  positioned after the header, at the raster.  Upon return, the file is
       still open, but its position is undefined.

SEE ALSO
       pbm(5), pgm(5), libpbm(3)

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

											libppm(3)


All times are GMT -4. The time now is 02:08 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password