This reference manual covers functions in the libnetpbm library for processing images, using the Netpbm image formats and the libnetpbm in-memory image formats.
For historical reasons as well as to avoid clutter, it does not cover the largely obsolete PBM, PGM, PPM, and PNM classes of libnetpbm functions. For those, see PBM Function Manual, PGM Function Manual,PPM Function Manual, and PNM Function Manual. Note that you do not need those functions to process PBM, PGM, PPM, and PNM images. The functions in this manual are sufficient for that.
For introductory and general information using libnetpbm, see Libnetpbm User's Guide.
libnetpbm also contains functions that are not specifically oriented toward processing image data. Read about those in the Libnetpbm Utility Manual.
To use these services, #include pam.h.
Here are some important types that you use with libnetpbm:
The main argument to most of the PAM functions is the address of a pam structure, which is defined as follows:
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];
}
See The Libnetbm User's Guide for information on the pam structure.
PNM_OVERALLMAXVAL is the maximum maxval that Netpbm images can have today (65535).
PBM_FORMAT, RPBM_FORMAT, PGM_FORMAT, RPGM_FORMAT, PPM_FORMAT, RPPM_FORMAT, and PAM_FORMAT are the format codes of the various Netpbm formats. RPBM_FORMAT is the raw PBM format and PBM_FORMAT is the plain PBM format, and so on. See the format member of the pam structure.
PAM_FORMAT_TYPE(format) gives the type of a format, given the format code. The types of formats are PBM, PGM, PPM, and PAM and macros for the type codes are, respectively, PBM_TYPE, PGM_TYPE, PPM_TYPE, and PAM_TYPE. Note that there are more format codes then there are format types because there are different format codes for the plain and raw subformats of each format.
These interfaces are declared in pam.h.
tuple ** pnm_allocpamarray( struct pam *pamP);
tuple * pnm_allocpamrow( struct pam *pamP);
void pnm_freepamarray( tuple **tuplearray, struct pam *pamP);
void pnm_freepamrow( tuple *tuplerow);
tuple * allocpamtuple( struct pam *pamP);
void pnm_freepamtuple( tuple tuple );
tuplen * pnm_allocpamrown( struct pam *pamP);
void pnm_freepamrown( tuple *tuplenrow);
pnm_allocpamarray() allocates space for an array of tuples. pnm_freepamarray() frees an array space allocated by pnm_allocpamarray() or pnm_readpam().
pnm_allocpamrow() allocates space for a row of a PAM image, in basic form. pnm_freepamrow() frees it.
pnm_allocpamrown() is the same as pnm_allocpamrow() except that it allocates space for a PAM row in the normalized form. pnm_freepamrown() is similarly like pnm_freepamrow.
void pnm_readpaminit( FILE *file, struct pam *pamP, int size);
void pnm_readpamrow( struct pam *pamP, tuple *tuplerow);
tuple ** pnm_readpam(
FILE *file,
struct pam *pamP,
int size);
void pnm_readpamrown( struct pam *pamP, tuplen *tuplenrow);
pnm_readpaminit() reads the header of a Netpbm image.
See above for a general description of the pamP argument.
pnm_readpaminit() returns the information from the header in the *pamP structure. It does not require any members of *pamP through tuple_type to be set at invocation, and sets all of those members. It expects all members after tuple_type to be meaningful.
size is the size of the *pamP structure as understood by the program processing the image. pnm_readpaminit() does not attempt to use or set any members of the structure beyond that. The point of this argument is that the definition of the structure may change over time, with additional fields being added to the end. This argument allows pnm_readpaminit to distinguish between a new program that wants to exploit the additional features and an old program that cannot (or a new program that just doesn't want to deal with the added complexity). At a minimum, this size must contain the members up through tuple_type. You should use the PAM_STRUCT_SIZE macro to compute this argument. E.g. PAM_STRUCT_SIZE(tuple_type).
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_readpamrow() reads a row of the raster from a Netpbm 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_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_readpamrown() is like pnm_readpamrow() except that it returns the row contents in normalized form (composed of normalized tuples (tuplen) instead of basic form (tuple).
pnm_readpaminit() and pnm_readpam abort the program with a message to Standard Error if the PAM or PNM image header is not syntactically valid, including if it contains a number too large to be processed using the system's normal data structures (to wit, a number that won't fit in a C 'int').
void pnm_writepaminit( struct pam *pamP);
void pnm_writepamrow( struct pam *pamP, const tuple *tuplerow);
void pnm_writepam( struct pam *pamP, const tuple * const *tuplearray);
void pnm_writepamrown( struct pam *pamP, const tuplen *tuplerown);
pnm_writepaminit() writes the header of a PAM or PNM image and computes some of the fields of the pam structure.
See above for a description of the pamP argument.
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_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_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(). Its raster input may be more storage than you can afford.
pnm_writepamrown() is like pnm_writepamrow() except that it takes the row contents in normalized form (composed of normalized tuples (tuplen) instead of basic form (tuple).
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_YCbCrtuple( tupletuple, double *YP, double *CrP, double *CbP);
pnm_checkpam() 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.
pnm_nextimage()positions a Netpbm image input file to the next image in it (so that a subsequent pnm_readpaminit() reads its header).
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.