Manpages - libnetpbm_image.3

libnetpbm_image - overview of netpbm image-processing functions

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 (3) , *PGM*Function*Manual*(3) , *PPM*Function*Manual*(3) , and *PNM*Function*Manual*(3)

need those functions to process PBM, PGM, PPM, and PNM images. The functions in this manual are sufficient for that.

The PPM drawing functions are covered separately in PPM*Drawing*Function*Manual*(1)

For introductory and general information using libnetpbm, see *Libnetpbm*User’s*Guide*(3)

libnetpbm also contains functions that are not specifically oriented toward processing image data. Read about those in the *Libnetpbm*Utility*Manual*(3)

To use these services, #include pam.h.

Here are some important types that you use with libnetpbm:

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.

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.

samplen

Same as sample, 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.

tuplen

The same as tuple, except composed of normalized samples (samplen) instead of regular samples (sample).

    
      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]
          int allocation_depth
          char **comment_p;
      }
      

PNM_MAXMAXVAL 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.

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.

void pnm_gammarown( struct pam * const */pamP/,* tuplen * const */row/);*

void pnm_ungammarown( struct pam * const */pamP/,* tuplen * const */row/);*

void pnm_applyopacityrown( struct pam * const */pamP/,* tuplen * const */tuplenrow/);*

void pnm_unapplyopacityrown( struct pam * const */pamP/,* tuplen * const */tuplenrow/);*

pnm_transformMap * pnm_creategammatransform( const struct pam * const */pamP/);*

void pnm_freegammatransform( const pnm_transformMap * const */transform/,* const struct pam * const */pamP/);*

pnm_transformMap * pnm_createungammatransform( const struct pam * const */pamP/);*

void pnm_freeungammatransform( const pnm_transformMap * const */transform/,* const struct pam * const */pamP/);*

Description

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 because of rounding. Divide them by the maxval to get normalized [0..1] values.

pnm_YCbCr_to_rgbtuple() does the reverse. */pamP/ indicates the maxval for the returned tuple, and the Y,* /Cb/*, and Cr arguments are of the same scale.*

It is possible for /Y/*, Cb, and Cr to describe a* color that cannot be represented in RGB form. In that case, pnm_YCbCr_to_rgbtuple() 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.

pnm_lumin_factor[] 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.

pnm_gammarown() and pnm_ungammarown() apply and unapply gamma correction to a row of an image using the same transformation as pm_gamma709() and pm_ungamma709() . Note that these operate on a row of normalized tuples (tuplen, not tuple).

pnm_applyopacityrown() 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 pnm_applyopacityrown() in preparation for doing such a composition. For example, if the opacity plane says that the left half of the image is 50% opaque and the right half 100% opaque, pnm_applyopacityrown() will reduce the intensity of each sample of each tuple (pixel) in the left half of the image by 50%, and leave the rest alone.

If the image does not have an opacity plane (i.e. its tuple type is not one that libnetpbm recognizes as having an opacity plane), pnm_applyopacityrown() does nothing (which is the same as assuming opacity 100%). The tuple types that libnetpbm recognizes as having opacity are RGB_ALPHA and GRAYSCALE_ALPHA.

pnm_unapplyopacityrown() does the reverse. It assumes the intensities are already reduced according to the opacity plane, and raises back to normal.

pnm_applyopacityrown() 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 pnm_readpamrown() and then gamma-correct it with pnm_ungammarown(), and then do pnm_applyopacityrown(). You then manipulate the row further (perhaps add it with other rows you’ve processed similarly), then do pnm_unapplyopacityrown(), then pnm_gammarown(), then pnm_writepamrown().

pnm_applyopacityrown() and pnm_unapplyopacityrown() were new in Netpbm 10.25 (October 2004).

pnm_normalizetuple() and pnm_unnormalizetuple() convert between a tuple data type and a tuplen 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. pnm_normalizetuple() divides every sample value by the maxval and pnm_unnormalizetuple() multiples every sample by the maxval.

pnm_normalizeRow() and pnm_unnormalizeRow() 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.

If you don’t have any transformation to apply, just specify NULL for the */transform/ argument and the function will* just normalize (i.e. divide or multiply by the maxval).

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.

  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);

To specify a transform, you must create a special pnm_transformMap object and pass it as the */transform/ 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 *pnm_creategammatransform() and pnm_createungammatransform() to create this object and don’t worry about what’s inside it.

pnm_creategammatransform() and pnm_createungammatransform() create objects that you use with pnm_normalizeRow() and pnm_unnormalizeRow() 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.

pnm_freegammatransform() and pnm_freeungammatransform() destroy the objects.