libpnm

The storage size in bytes of this entire structure.

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 R size . size and len can be used to make programs compatible with newer and older versions of the Netpbm libraries.

The file.

The format code of the raw image. This is PAM_FORMAT unless the PAM image is really a view of a PBM, PGM, or PPM image. Then it's R PBM_FORMAT , R RPBM_FORMAT , etc.

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.

The height of the image in rows.

The width of the image in number of columns (tuples per row).

The depth of the image (degree of or number of samples in each tuple).

The maxval of the image. See definitions in pam(5).

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 R maxval . It exists as a separate member for computational speed.

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: R PAM_PBM_TUPLETYPE , R PAM_PGM_TUPLETYPE , R 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 specify 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 function 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 convert the output of your program to plain format.

PNM TYPES AND CONSTANTS

Each R xel contains three R xelval s, each of which should contain only the values between R 0 and R PNM_MAXMAXVAL , inclusive. R 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 R PPM_GETR() , R PPM_GETG() , and R 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 R PPM_ASSIGN . The PNM_EQUAL macro checks two xels for equality. The PNM_FORMAT_TYPE and PAM_FORMAT_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 formats: 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. R 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 R pnm_readpam() . pnm_allocarray() allocates space for an array of xels. pnm_freearray() frees an array space allocated by pnm_allocarray() or R 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 I * pamP structure. It does not require any members of I * pamP to be set at invocation, and sets every member. size is the storage size of the I * pamP structure, normally R 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 R 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 I *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 R 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 I * pamP to have any of its members set and sets them all. size is the storage size in bytes of the I * pamP structure, normally R 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 R pnm_allocpamarray() , R pnm_readpaminit() , and iterations of R pnm_readpamrow() . 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 I * pamP structure must be set upon invocation to tell the function how and what to write. R size , R len , R file , R format , R height , R width , R depth , R maxval , R tuple_type . pnm_writepaminit() sets the plainformat and bytes_per_sample 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 I * 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 I * pamP structure must be set upon invocation to tell the function how and what to write: R size , R len , R file , R format , R height , R width , R depth , R maxval , R 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 R pnm_writepamrow() , with the top row being Element 0 of the array. pnm_writepam() combines the functions of R pnm_writepaminit() , and iterations of R 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 R 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 R 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 R format . pnm_invertxel() inverts an xel. pnm_backgroundxelrow() figures out an appropriate background xel based on the row of xels R xelrow , which is cols xels wide, has maxval R maxval , and represents an image with format R format . This estimate works best when the row is the top or bottom row of the image. pnm_backgroundxel() does the same thing as R pnm_backgroundxelrow() , except based on an entire image instead of just one row. This tends to do a slightly better job than R 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 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.