libppm - functions to support portable pixmap (PPM) pro
grams
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 forceplain );
void ppm_writeppm( FILE *fp, pixel **pixels, int cols, int
rows, pixval maxval, int forceplain );
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 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
The PPM_LUMIN, PPM_CHROM_R, and PPM_CHROM_B, macros deter
mine the luminance, red chrominance, and blue chrominance,
respectively, of the pixel p. The scale of all these val
ues is the same as the scale of the input samples (i.e. 0
to maxval for luminance, -maxval/2 to maxval/2 for chromi
nance).
Note that the macros do it by floating point multiplica
tion. If you are computing these values over an entire
image, it may be significantly faster to do it with multi
plication tables instead. Compute all the possible prod
ucts 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 invoca
tion, before they process their arguments.
MEMORY MANAGEMENT
ppm_allocarray() allocates an array of pixels.
ppm_allocrow() allocates a row of the given number of pix
els.
ppm_freearray() frees the array allocated with ppm_allo
carray() containing the given number 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
equivalent PPM file. The format value returned by
ppm_readppminit() is, however, not translated. It repre
sents the actual format of the PBM or PGM file.
ppm_readppminit() reads the header of a PPM file, return
ing 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
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_writepp
minit() 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 hexadecimal triple:
#rgb, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb. 3) A triplet
of decimal floating point numbers separated by commas:
r.r,g.g,b.b.
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,
file. If the color does not appear in a X11-style color
file and hexok is true, ppm_colorname() returns a hexadec
imal 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 chartreuse pixel. Netpbm's
color indexing data types and functions give you that.
colorhash_table is a C data type that associates an inte
ger with each of an arbitrary number 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 subscript 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).
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 mes
sage.
void ppm_freecolorhash()
This destroys a ppm_freecolorhash and frees all the stor
age associated with it.
int ppm_addtocolorhash( colorhash_table cht, const pixel *
const colorP, const int value)
This adds the specified color to the specified col
orhash_table and associates the specified value with it.
You must ensure that the color you are adding isn't
already present in the colorhash_table.
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 col
orhash_table. It returns the integer value associated
with that color.
If the specified color is not in the hash table, the func
tion returns -1. (So if you assign the value -1 to a
color, the return value is ambiguous).
colorhist_vector ppm_colorhashtocolorhist( const col
orhash_table cht, const int ncolors )
This converts a colorhash_table to a colorhist_vector.
The return value is a new colorhist_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_colorhashtocolorhist does not create
a colorhist_vector and returns NULL.
colorhash_table ppm_colorhisttocolorhash( const col
orhist_vector chv, const int ncolors )
This poorly named function does not convert from a col
orhist_vector to a colorhash_table.
It does create a colorhist_vector based on a col
orhash_table input, but the integer value for a given
for that same color in the input. ppm_colorhisttocol
orhash() 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_colorhist
tocolorhash() 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_col
orhisttocolorhash() exit the program with an error mes
sage.
ncolors is the number of colors in chv.
The return value is a new colorhash_table which you must
eventually free with ppm_freecolorhash().
COLOR HISTOGRAMS
The Netpbm libraries give you functions to examine a
Netpbm image and determine what colors are in it and how
many pixels of each color are in it. This information is
known as a color histogram. Netpbm uses its col
orhash_table data type to represent a color histogram.
colorhash_table ppm_computecolorhash( pixel ** const pix
els, 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 num
ber of colors in the image.
pixels, cols, and rows describe the input image.
maxcolors is the maximum number of colors you want pro
cessed. 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 memory. 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
(It's poorly named because not all colorhash_tables are
color histograms, but that's all it generates).
colorhist_vector ppm_computecolorhist( pixel ** const pix
els, const int cols, const int rows, const int maxcolors,
int * const 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_computecolorhist() returns a
null pointer as its return value and nothing meaningful as
*colorsP. If not, the function returns the new col
orhist_vector as its return value and the actual number of
colors in the image as *colorsP.
SEE ALSO
pbm(5), pgm(5), libpbm(3)
AUTHOR
Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.
Man(1) output converted with
man2html