.TL Libnetpbm Image Processing Manual .SH 1 Libnetpbm Image Processing Manual .LP Updated: December 2003 .br .LP Table Of Contents .LP This reference manual covers functions in the \fBlibnetpbm\fR library for processing images, using the Netpbm image formats and the \fBlibnetpbm\fR in-memory image formats. .LP For historical reasons as well as to avoid clutter, it does not cover the largely obsolete PBM, PGM, PPM, and PNM classes of \fBlibnetpbm\fR 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. .LP The PPM Drawing function are covered separately in PPM Drawing Function Manual. .LP For introductory and general information using \fBlibnetpbm\fR, see Libnetpbm User's Guide. .LP \fBlibnetpbm\fR also contains functions that are not specifically oriented toward processing image data. Read about those in the Libnetpbm Utility Manual. .LP To use these services, #include \fBpam.h\fR. .SH 2 Types .LP .LP Here are some important types that you use with \fBlibnetpbm\fR: .RS .IP "sample" A sample of a Netpbm image. See the format specifications -- as an example, the red intensity of a particular pixel of a PPM image is a sample. This is an integer type. .IP "tuple" A tuple from a PAM image or the PAM equivalent of a PNM image. See the PAM format specification -- as an example, a pixel of a PPM image would be a tuple. A tuple is an array of samples. .IP "samplen" Same as \fBsample\fR, except in normalized form. This is a floating point type with a value in the range 0..1. 0 corresponds to a PAM/PNM sample value of 0. 1 corresponds to a PAM/PNM sample value equal to the image's maxval. .IP "tuplen" The same as \fBtuple\fR, except composed of normalized samples (\fBsamplen\fR) intead of regular samples (\fBsample\fR). .RE .LP The main argument to most of the PAM functions is the address of a \fBpam\fR structure, which is defined as follows: .LP \fBstruct pam {\fR .br \fBint \fR\fIsize\fR .br \fBint \fR\fIlen\fR .br \fBFILE *\fR\fIfile \fR .br \fBint \fR\fIformat\fR .br \fBint \fR\fIplainformat\fR .br \fBint \fR\fIheight\fR .br \fBint \fR\fIwidth\fR .br \fBint \fR\fIdepth\fR .br \fBsample \fR\fImaxval\fR .br \fBint \fR\fIbytes_per_sample\fR .br \fBchar \fR\fItuple_type\fR\fB[256];\fR \fB}\fR .LP See The Libnetbm User's Guide for information on the \fBpam\fR structure. .SH 2 Macros .LP \fBPNM_MAXMAXVAL\fR is the maximum maxval that Netpbm images could historically have: 255. Many programs aren't capable of handling Netpbm images with a maxval larger than this. It's named this way for backward compatibility -- it had this name back when it was the maximum maxval. .LP \fBPNM_OVERALLMAXVAL\fR is the maximum maxval that Netpbm images can have today (65535). .LP \fBPBM_FORMAT\fR, \fBRPBM_FORMAT\fR, \fBPGM_FORMAT\fR, \fBRPGM_FORMAT\fR, \fBPPM_FORMAT\fR, \fBRPPM_FORMAT\fR, and \fBPAM_FORMAT\fR are the format codes of the various Netpbm formats. \fBRPBM_FORMAT\fR is the raw PBM format and \fBPBM_FORMAT\fR is the plain PBM format, and so on. See the \fIformat\fR member of the \fBpam\fR structure. .LP \fBPAM_FORMAT_TYPE(\fR\fIformat\fR\fB)\fR 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. .SH 2 Functions .LP .LP These interfaces are declared in \fBpam.h\fR. .SH 3 Memory Management .LP .SH 4 Synopsis .LP .LP \fBtuple ** pnm_allocpamarray(\fR \fBstruct pam *\fR\fIpamP\fR\fB);\fR .LP \fBtuple * pnm_allocpamrow(\fR \fBstruct pam *\fR\fIpamP\fR\fB);\fR .LP \fBvoid pnm_freepamarray(\fR \fBtuple **\fR\fItuplearray\fR\fB,\fR \fBstruct pam *\fR\fIpamP\fR\fB);\fR .LP \fBvoid pnm_freepamrow(\fR \fBtuple *\fR\fItuplerow\fR\fB);\fR .LP \fBtuple * allocpamtuple(\fR \fBstruct pam *\fR\fIpamP\fR\fB);\fR .LP \fBvoid pnm_freepamtuple(\fR \fBtuple \fR\fItuple\fR \fB);\fR .LP \fBtuplen * pnm_allocpamrown(\fR \fBstruct pam *\fR\fIpamP\fR\fB);\fR .LP \fBvoid pnm_freepamrown(\fR \fBtuple *\fR\fItuplenrow\fR\fB);\fR .SH 4 Description .LP .LP \fBpnm_allocpamarray()\fR allocates space for an array of tuples. \fBpnm_freepamarray()\fR frees an array space allocated by \fBpnm_allocpamarray()\fR or \fBpnm_readpam()\fR. .LP \fBpnm_allocpamrow() \fR allocates space for a row of a PAM image, in basic form. \fBpnm_freepamrow()\fR frees it. .LP \fBpnm_allocpamrown()\fR is the same as \fBpnm_allocpamrow()\fR except that it allocates space for a PAM row in the normalized form. \fBpnm_freepamrown()\fR is similarly like \fBpnm_freepamrow\fR. .SH 3 Reading Netpbm Files .LP .SH 4 Synopsis .LP .LP \fBvoid pnm_readpaminit(\fR \fBFILE *\fR\fIfile\fR\fB,\fR \fBstruct pam *\fR\fIpamP\fR\fB,\fR \fBint \fR\fIsize\fR\fB);\fR .LP \fBvoid pnm_readpamrow(\fR \fBstruct pam *\fR\fIpamP\fR\fB,\fR \fBtuple *\fR\fItuplerow\fR\fB);\fR .LP \fBtuple ** pnm_readpam(\fR \fBFILE *\fR\fIfile\fR\fB,\fR \fBstruct pam *\fR\fIpamP\fR\fB,\fR .br \fBint \fR\fIsize\fR\fB);\fR .LP \fBvoid pnm_readpamrown(\fR \fBstruct pam *\fR\fIpamP\fR\fB,\fR \fBtuplen *\fR\fItuplenrow\fR\fB);\fR .SH 4 Description .LP .LP \fBpnm_readpaminit()\fR reads the header of a Netpbm image. .LP See above for a general description of the \fIpamP\fR argument. .LP \fBpnm_readpaminit()\fR returns the information from the header in the \fB*\fR\fIpamP\fR structure. It does not require any members of \fB*\fR\fIpamP\fR through \fBtuple_type\fR to be set at invocation, and sets all of those members. It expects all members after \fBtuple_type\fR to be meaningful. .LP \fIsize\fR is the size of the \fB*\fR\fIpamP\fR structure as understood by the program processing the image. \fBpnm_readpaminit()\fR 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 \fBpnm_readpaminit\fR 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 \fBtuple_type\fR. You should use the \fBPAM_STRUCT_SIZE\fR macro to compute this argument. E.g. \fBPAM_STRUCT_SIZE(tuple_type)\fR. .LP 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. .LP \fBpnm_readpamrow()\fR reads a row of the raster from a Netpbm image file. It expects all of the members of the \fB*pamP\fR 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 \fItuplerow\fR, 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. .LP \fBpnm_readpam()\fR 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. .LP The function does not require \fB*\fR\fIpamP\fR to have any of its members set and sets them all. \fIsize\fR is the storage size in bytes of the \fB*\fR\fIpamP\fR structure, normally \fBsizeof(struct pam)\fR. .LP 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 \fBpnm_readpamrow()\fR would return. .LP 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. .LP \fBpnm_readpam()\fR combines the functions of \fBpnm_allocpamarray()\fR, \fBpnm_readpaminit()\fR, and iterations of \fBpnm_readpamrow()\fR. It may require more dynamic storage than you can afford. .LP \fBpnm_readpamrown()\fR is like \fBpnm_readpamrow()\fR except that it returns the row contents in normalized form (composed of normalized tuples (\fBtuplen\fR) instead of basic form (\fBtuple\fR). .LP \fBpnm_readpaminit()\fR and \fBpnm_readpam\fR 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'). .SH 3 Writing Netpbm Files .LP .SH 4 Synopsis .LP .LP \fBvoid pnm_writepaminit(\fR \fBstruct pam *\fR\fIpamP\fR\fB);\fR .LP \fBvoid pnm_writepamrow(\fR \fBstruct pam *\fR\fIpamP\fR\fB,\fR \fBconst tuple *\fR\fItuplerow\fR\fB);\fR .LP \fBvoid pnm_writepam(\fR \fBstruct pam *\fR\fIpamP\fR\fB,\fR \fBconst tuple * const *\fR\fItuplearray\fR\fB);\fR .LP \fBvoid pnm_writepamrown(\fR \fBstruct pam *\fR\fIpamP\fR\fB,\fR \fBconst tuplen *\fR\fItuplerown\fR\fB);\fR .LP \fBvoid pnm_formatpamrow(\fR \fBstruct pam *\fR\fIpamP\fR\fB,\fR \fBconst tuple *\fR\fItuplerow\fR \fBunsigned char * const \fIoutbuf\fB,\fR \fBunsigned int * const \fIrowSizeP\fB\fR \fB);\fR .SH 4 Description .LP .LP \fBpnm_writepaminit()\fR writes the header of a PAM or PNM image and computes some of the fields of the pam structure. .LP See above for a description of the \fIpamP\fR argument. .LP The following members of the \fB*\fR\fIpamP\fR structure must be set upon invocation to tell the function how and what to write. \fBsize\fR, \fBlen\fR, \fBfile\fR, \fBformat\fR, \fBheight\fR, \fBwidth\fR, \fBdepth\fR, \fBmaxval\fR, \fBtuple_type\fR. .LP \fBpnm_writepaminit()\fR sets the \fBplainformat\fR and \fBbytes_per_sample\fR members based on the information supplied. .LP \fBpnm_writepamrow()\fR 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 \fB*\fR\fIpamP\fR to be set upon invocation and doesn't modify them. .LP \fItuplerow\fR is an array of tuples representing the row. The leftmost tuple is Element 0 of this array. .LP \fBpnm_writepam()\fR 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. .LP The following members of the \fB*\fR\fIpamP\fR structure must be set upon invocation to tell the function how and what to write: \fBsize\fR, \fBlen\fR, \fBfile\fR, \fBformat\fR, \fBheight\fR, \fBwidth\fR, \fBdepth\fR, \fBmaxval\fR, \fBtuple_type\fR. .LP \fBpnm_writepam()\fR sets the \fBplainformat\fR and \fBbytes_per_sample\fR members based on the information supplied. .LP \fItuplearray\fR is an array of rows such that you would pass to \fBpnm_writepamrow()\fR, with the top row being Element 0 of the array. .LP \fBpnm_writepam()\fR combines the functions of \fBpnm_writepaminit()\fR, and iterations of \fBpnm_writepamrow()\fR. Its raster input may be more storage than you can afford. .LP \fBpnm_writepamrown()\fR is like \fBpnm_writepamrow()\fR except that it takes the row contents in normalized form (composed of normalized tuples (\fBtuplen\fR) instead of basic form (\fBtuple\fR). .LP \fBpnm_formatpamrow()\fR is like \fBpnm_writepamrow()\fR, except that instead of writing a row to a file, it places the same bytes that would go in the file in a buffer you supply. There isn't an equivalent function to construct an image header; i.e. there is no analog to \fBpnm_writepaminit()\fR. But the header format, particularly for PAM, is so simple that you can easily build it yourself with standard C library string functions. .LP \fBpnm_formatpamrow()\fR was new in Netpbm 10.25 (October 2004). .SH 3 Transforming Pixels .LP .SH 4 Synopsis .LP .LP \fBvoid pnm_YCbCrtuple(\fR .br \fBtuple\fR\fItuple\fR\fB,\fR \fBdouble *\fR\fIYP\fR\fB,\fR \fBdouble *\fR\fICrP\fR\fB,\fR \fBdouble *\fR\fICbP\fR\fB);\fR .LP \fBvoid pnm_YCbCr_to_rgbtuple( .br const struct pam * const \fIpamP\fB, .br tuple const \fItuple\fB, .br double const \fIY\fB, double const \fICb\fB, double const \fICr\fB, .br int * const \fIoverflowP\fB ); \fR.LP \fBextern double pnm_lumin_factor[3];\fR .LP \fBvoid pnm_normalizetuple( .br struct pam * const \fIpamP\fB, tuple const \fItuple\fB, tuplen const \fItuplen\fB); \fR.LP \fBvoid pnm_unnormalizetuple( .br struct pam * const \fIpamP\fB, tuplen const \fItuplen\fB, tuple const \fItuple\fB); \fR.LP \fBvoid pnm_normalizeRow( .br struct pam * const \fIpamP\fB, const tuple * const \fItuplerow\fB, pnm_transformMap * const \fItransform\fB, tuplen * const \fItuplenrow\fB); \fR.LP \fBvoid pnm_unnormalizeRow( .br struct pam * const \fIpamP\fB, const tuplen * const \fItuplenrow\fB, pnm_transformMap * const \fItransform\fB, tuple * const \fItuplerow\fB); \fR.LP \fBvoid pnm_gammarown( .br struct pam * const \fIpamP\fB, tuplen * const \fIrow\fB ); \fR.LP \fBvoid pnm_ungammarown( .br struct pam * const \fIpamP\fB, tuplen * const \fIrow\fB ); \fR.LP \fBvoid pnm_applyopacityrown( .br struct pam * const \fIpamP\fB, tuplen * const \fItuplenrow\fB ); \fR.LP \fBvoid pnm_unapplyopacityrown( .br struct pam * const \fIpamP\fB, tuplen * const \fItuplenrow\fB ); \fR.LP \fBpnm_transformMap * pnm_creategammatransform( .br const struct pam * const \fIpamP\fB ); \fR.LP \fBvoid pnm_freegammatransform( .br const pnm_transformMap * const \fItransform\fB, const struct pam * const \fIpamP\fB ); \fR.LP \fBpnm_transformMap * pnm_createungammatransform( .br const struct pam * const \fIpamP\fB ); \fR.LP \fBvoid pnm_freeungammatransform( .br const pnm_transformMap * const \fItransform\fB, const struct pam * const \fIpamP\fB ); \fR.SH 4 Description .LP .LP \fBpnm_YCbCrtuple()\fR 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. .LP \fBpnm_YCbCr_to_rgbtuple()\fR does the reverse. \fIpamP\fR indicates the maxval for the returned \fItuple\fR, and the \fIY\fR, \fICb\fR, and \fICr\fR arguments are of the same scale. .LP It is possible for \fIY\fR, \fICb\fR, and \fICr\fR to describe a color that cannot be represented in RGB form. In that case, \fBpnm_YCbCr_to_rgbtuple()\fR chooses a color as close as possible (by clipping each component to 0 and the maxval) and sets *overflowP true. It otherwise sets *overflowP false. \fBpnm_lumin_factor[]\fR is the factors (weights) one uses to compute the intensity of a color (according to some standard -- I don't know which). pnm_lumin_factor[0] is for the red component, [1] is for the green, and [2] is for the blue. They add up to 1. .LP \fBpnm_gammarown()\fR and \fBpnm_ungammarown()\fR apply and unapply gamma correction to a row of an image using the same transformation as \fBpm_gamma()\fR and \fBpm_ungamma()\fR. Note that these operate on a row of normalized tuples (\fBtuplen\fR, not \fBtuple\fR). .LP \fBpnm_applyopacity()\fR reduces the intensity of samples in accordance with the opacity plane of an image. The opacity plane, if it exists, tells how much of the light from that pixel should show when the image is composed with another image. You use \fBpnm_applyopacity()\fR in preparation for doing such a composition. For example, if the opacity plane says that the top half of the image is 50% opaque and the bottom half 100% opaque, \fBpnm_applyopacity()\fR will reduce the intensity of each sample of each tuple (pixel) in the upper half of the image by 50%, and leave the rest alone. .LP If the image does not have an opacity plane (i.e. its tuple type is not one that \fBlibnetpbm\fR recognizes as having an opacity plane), \fBpnm_applyopacity()\fR does nothing (which is the same as assuming opacity 100%). The tuple types that \fBlibnetpbm\fR recognizes as having opacity are \fBRGB_ALPHA\fR and \fBGRAYSCALE_ALPHA\fR. .LP \fBpnm_unapplyopacity()\fR does the reverse. It assumes the intensities are already reduced according to the opacity plane, and raises back to normal. .LP \fBpnm_applyopacity()\fR works on (takes as input and produces as output) normalized, intensity-proportional tuples. That means you will typically read the row from the image file with \fBpnm_readpamrown()\fR and then gamma-correct it with \fBpnm_ungammarown()\fR, and then do \fBpnm_applyopacity()\fR. You then manipulate the row further (perhaps add it with other rows you've processed similarly), then do \fBpnm_unapplyopacity()\fR, then \fBpnm_gammarown()\fR, then \fBpnm_writegammarown()\fR. .LP \fBpnm_normalizeTuple()\fR and \fBpnm_unnormalizeTuple()\fR convert between a \fBtuple\fR data type and a \fBtuplen\fR data type. The former represents a sample value using the same unsigned integer that is in the PAM image, while the latter represents a sample value as a number scaled by the maxval to the range 0..1. I.e. \fBpnm_normalizeTuple()\fR divides every sample value by the maxval and \fBpnm_unnormalizeTuple()\fR multiples every sample by the maxval. .LP \fBpnm_normalizeRow()\fR and \fBpnm_unnormalizeRow()\fR do the same thing on an entire tuple row, but also have an extra feature: You can specify a transform function to be applied in addition. Typically, this is a gamma transform function. You can of course more easily apply your transform function separately from normalizing, but doing it all at once is usually way faster. Why? Because you can use a lookup table that is indexed by an integer on one side and produces a floating point number on the other. To do it separately, you'd either have to do floating point arithmetic on the normalized value or do the transform on the integer values and lose a lot of precision. .LP If you don't have any transformation to apply, just specify \fBNULL\fR for the \fItransform\fR argument and the function will just normalize (i.e. divide or multiply by the maxval). .LP Here's an example of doing a transformation. The example composes two images together, something that has to be done with intensity-linear sample values. .DS L pnm_transformMap * const transform1 = pnm_createungammatransform(&inpam1); pnm_transformMap * const transform2 = pnm_createungammatransform(&inpam2); pnm_transformMap * const transformOut = pnm_creategammatransform(&outpam); pnm_readpamrow(&inpam1, inrow1); pnm_readpamrow(&inpam2, inrow2); pnm_normalizeRow(&inpam1, inrow1, transform1, normInrow1); pnm_normalizeRow(&inpam2, inrow2, transform2, normInrow2); for (col = 0; col < outpam.width; ++col) normOutrow[col] = (normInrow1[col] + normInrow2[col])/2; pnm_unnormalizeRow(&outpam, normOutrow, transformOut, outrow); pnm_writepamrow(&outpam, outrow); .DE .LP To specify a transform, you must create a special \fBpnm_transformMap\fR object and pass it as the \fItransform\fR argument. Typically, your transform is a gamma transformation because you want to work in intensity-proportional sample values and the PAM image format uses gamma-adjusted ones. In that case, just use \fBpnm_creategammtransform()\fR and \fBpnm_createungammatransform()\fR to create this object and don't worry about what's inside it. .LP \fBpnm_creategammatransform()\fR and \fBpnm_createungammatransform()\fR create objects that you use with \fBpnm_normalizeRow()\fR and \fBpnm_unnormalizeRow()\fR as described above. The created object describes a transform that applies or reverses the ITU-R Recommendation BT.709 gamma adjustment that is used in PAM visual images and normalizes or unnormalizes the sample values. \fBpnm_freegammatransform()\fR and \fBpnm_freeungammatransform()\fR destroy the objects. .SH 3 Miscellaneous .LP .SH 4 Synopsis .LP .LP \fBvoid pnm_checkpam(\fR \fBstruct pam *\fR\fIpamP\fR\fB,\fR \fBconst enum pm_check_type \fR\fIcheck_type\fR\fB,\fR \fBenum pm_check_code *\fR\fIretvalP\fR\fB);\fR .LP \fBvoid pnm_nextimage(\fR \fBFILE *\fR\fIfile\fR\fB,\fR \fBint * const \fR\fIeofP\fR\fB);\fR .SH 4 Description .LP .LP \fBpnm_checkpam()\fR 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. .LP \fBpnm_nextimage()\fRpositions a Netpbm image input file to the next image in it (so that a subsequent \fBpnm_readpaminit()\fR reads its header). .br \l'5i' .SH 2 Table Of Contents .LP .IP \(bu Types .IP \(bu Macros .IP \(bu Functions .IP \(bu Memory Management .IP \(bu Reading Netpbm Files .IP \(bu Writing Netpbm Files .IP \(bu Transforming Pixels .IP \(bu Miscellaneous .LP .LP