libpnm(3)libpnm(3)NAMElibpnm - 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 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
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 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.
format The format code of the raw image. This is PAM_FOR
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 func
tion 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 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().
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 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
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_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
upon invocation to tell the function how and what to
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_invertxel() inverts an xel.
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 ALSOpbm(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)
