diff options
| author | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2006-12-25 03:06:05 +0000 |
|---|---|---|
| committer | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2006-12-25 03:06:05 +0000 |
| commit | 1017cbebe5d5edd859e0fddad0a8600f509f4821 (patch) | |
| tree | 78bdf336648566f7a7d55f42837357dea3dd674c /pam.html | |
| parent | 16f2ac126651015a376eba864a3a35f738b0b25a (diff) | |
| download | netpbm-mirror-1017cbebe5d5edd859e0fddad0a8600f509f4821.tar.gz netpbm-mirror-1017cbebe5d5edd859e0fddad0a8600f509f4821.tar.xz netpbm-mirror-1017cbebe5d5edd859e0fddad0a8600f509f4821.zip | |
Place user guide into Subversion repository
git-svn-id: http://svn.code.sf.net/p/netpbm/code/userguide@181 9d0c8265-081b-0410-96cb-a4ca84ce46f8
Diffstat (limited to 'pam.html')
| -rw-r--r-- | pam.html | 317 |
1 files changed, 317 insertions, 0 deletions
diff --git a/pam.html b/pam.html new file mode 100644 index 00000000..27a48d26 --- /dev/null +++ b/pam.html @@ -0,0 +1,317 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> +<HEAD> +<TITLE>PAM format specification</TITLE> +<META NAME="manual_section" CONTENT="5"> +</HEAD> +<BODY> +<A HREF="#index">Table Of Contents</A> + +<H1>pam</H1> +Updated: 09 October 2005 +<BR> +<?makeman .SH NAME ?> +<?makeman pam - Netpbm common 2-dimensional bitmap format ?> + +<H2 id="general">GENERAL</H2> + +<p>The PAM image format is a lowest common denominator 2 dimensional map +format. + +<P>It is designed to be used for any of myriad kinds of graphics, but can +theoretically be used for any kind of data that is arranged as a two +dimensional rectangular array. Actually, from another perspective it +can be seen as a format for data arranged as a three dimensional +array. + +<P>The name "PAM" is an acronym derived from "Portable +Arbitrary Map." This derivation makes more sense if you consider +it in the context of the other Netpbm format names: PBM, PGM, and PPM. + +<P>This format does not define the meaning of the data at any particular +point in the array. It could be red, green, and blue light +intensities such that the array represents a visual image, or it could +be the same red, green, and blue components plus a transparency +component, or it could contain annual rainfalls for places on the +surface of the Earth. Any process that uses the PAM format must +further define the format to specify the meanings of the data. + +<P>A PAM image describes a two dimensional grid of tuples. The tuples +are arranged in rows and columns. The width of the image is the +number of columns. The height of the image is the number of rows. +All rows are the same width and all columns are the same height. The +tuples may have any degree, but all tuples have the same degree. The +degree of the tuples is called the depth of the image. Each member of +a tuple is called a sample. A sample is an unsigned integer which +represents a locus along a scale which starts at zero and ends at a +certain maximum value greater than zero called the maxval. The maxval +is the same for every sample in the image. The two dimensional array +of all the Nth samples of each tuple is called the Nth plane or Nth +channel of the image. + +<P>Though the basic format does not assign any meaning to the tuple values, it +does include an optional string that describes that meaning. The +contents of this string, called the tuple type, are arbitrary from the +point of view of the basic PAM format, but users of the format may assign +meaning to it by convention so they can identify their particular +implementations of the PAM format. Some tuple types are defined as +official subformats of PAM. See <a href="#tupletype">Defined Tuple Types</a>. + +<H2 id="format_universe">The Confusing Universe of Netpbm Formats</H2> + +<P>It is easy to get confused about the relationship between the PAM +format and PBM, PGM, PPM, and PNM. Here is a little enlightenment: + +<P>"PNM" is not really a format. It is a shorthand for the PBM, PGM, +and PPM formats collectively. It is also the name of a group of +library functions that can each handle all three of those formats. + +<P>"PAM" is in fact a fourth format. But it is so general +that you can represent the same information in a PAM image as you can +in a PBM, PGM, or PPM image. And in fact a program that is designed +to read PBM, PGM, or PPM and does so with a recent version of the +Netpbm library, will read an equivalent PAM image just fine and the +program will never know the difference. + +<P>To confuse things more, there is a collection of library routines +called the "pam" functions that read and write the PAM +format, but also read and write the PBM, PGM, and PPM formats. They +do this because the latter formats are much older and more popular, so +even a new program must work with them. Having the library handle all +the formats makes it convenient to write programs that use the newer +PAM format as well. + +<H2 id="layout">THE LAYOUT</H2> + +<P>A convenient way to read and write the PAM format accurately is via the +<a href="libnetpbm.html">libnetpbm</a> C subroutine library. + +<P>A PAM file consists of a sequence of one or more PAM images. There are +no data, delimiters, or padding before, after, or between images. + +<P> +Each PAM image consists of a header followed immediately by a raster. +<P> +Here is an example header: +<P> +<B>P7</B> + +<BR> + +<B>WIDTH 227</B> + +<BR> + +<B>HEIGHT 149</B> + +<BR> + +<B>DEPTH 3</B> + +<BR> + +<B>MAXVAL 255</B> + +<BR> + +<B>TUPLTYPE RGB</B> + +<BR> + +<B>ENDHDR</B> + +<P>The header begins with the ASCII characters "P7" followed +by newline. This is the magic number. + +<P>Note: <b>xv</b> thumbnail images also start with the "P7" magic number. +(This and PAM were independent extensions to the Netpbm formats). The rest +of the format makes it easy to distinguish PAM from that format, though). + +<P>The header continues with an arbitrary number of lines of ASCII +text. Each line ends with and is delimited by a newline character. + +<P>Each header line consists of zero or more whitespace-delimited +tokens or begins with "#". If it begins with "#" +it is a comment and the rest of this specification does not apply to +it. + +<P>A header line which has zero tokens is valid but has no meaning. + +<P>The type of header line is identified by its first token, which is +8 characters or less: + +<DL COMPACT> +<DT><B>ENDHDR </B> + +<DD>This is the last line in the header. The header must contain +exactly one of these header lines. + +<DT><B>HEIGHT </B> + +<DD>The second token is a decimal number representing the height +of the image (number of rows). The header must contain exactly one +of these header lines. + +<DT><B>WIDTH</B> + +<DD>The second token is a decimal number representing the width of the +image (number of columns). The header must contain exactly one of +these header lines. + +<DT><B>DEPTH</B> + +<DD>The second token is a decimal number representing the depth of the +image (number of planes or channels). The header must contain exactly +one of these header lines. + +<DT><B>MAXVAL</B> + +<DD>The second token is a decimal number representing the maxval of the image. +The header must contain exactly one of these header lines. + +<DT><B>TUPLTYPE</B> + +<DD>The header may contain any number of these header lines, including +zero. The rest of the line is part of the tuple type. The rest of +the line is not tokenized, but the tuple type does not include any +white space immediately following <B>TUPLTYPE </B> or at the very end +of the line. It does not include a newline. If there are multiple +<B>TUPLTYPE</B> header lines, the tuple type is the concatenation of +the values from each of them, separated by a single blank, in the +order in which they appear in the header. If there are no +<B>TUPLTYPE</B> header lines the tuple type is the null string. + +</DL> + +<P> +The raster consists of each row of the image, in order from top to bottom, +consecutive with no delimiter of any kind between, before, or after, rows. +<P> +Each row consists of every tuple in the row, in order from left to +right, consecutive with no delimiter of any kind between, before, or +after, tuples. +<P> +Each tuple consists of every sample in the tuple, in order, +consecutive with no delimiter of any kind between, before, or after, +samples. +<P> +Each sample consists of an unsigned integer in pure binary format, +with the most significant byte first. The number of bytes is the +minimum number of bytes required to represent the maxval of the image. + +<H2 id="limitations">LIMITATIONS</H2> + +<P>The maxval of an image is never greater than 65535. (The reason it is +limited is to make it easier to build an image processor, in which +intermediate arithmetic values often have to fit within 31 or 32 bits). +There was no specified limitation before October, 2005, but essentially +all implementations have always observed it. + +<p>Height and width are at least 1. + +<p>Height and width have no defined maximum, but processors and generators +of images usually have their own limitations. + +<H2 id="tupletype">DEFINED TUPLE TYPES</h2> + +<p>Some tuple types are defined in this specification to specify +official subformats of PAM for especially popular applications of the +format. Users of the format may also define their own tuple types, +and thus their own subformats. + +<A NAME="visual"> </A> +<H3>PAM Used For Visual Images</H3> + +<P>A common use of PAM images is to represent visual images such +as are typically represented by images in the older and more concrete +PBM, PGM, and PPM formats. + +<h4>Black And White (PBM)</h4> + +<P>A black and white image, such as would be represented by a PBM +image, has a tuple type of "BLACKANDWHITE". Such a PAM image +has a depth of 1 and maxval 1 where the one sample in each tuple is 0 +to represent a black pixel and 1 to represent a white one. The +height, width, and raster bear the obvious relationship to those of +the equivalent PBM image. + +<P>Note that in the PBM format, a zero value means white, but in PAM, +zero means black. + +<h4>Grayscale (PGM)</h4> + +<P>A grayscale image, such as would be represented by a PGM image, has +a tuple type of "GRAYSCALE". Such a PAM image has a depth of 1. The +maxval, height, width, and raster bear the obvious relationship to +those of the equivalent PGM image. + +<h4>Color (PPM)</h4> + +<P>A color image, such as would be represented by a PPM image, has a +typle type of "RGB". Such a PAM image has a depth of 3. The maxval, +height, width, and raster bear the obvious relationship to those of +the PPM image. The first plane represents red, the second blue, and +the third green. + +<h4>Transparent</h4> + +<p>Each of the visual image formats mentioned above has a variation that +contains transparency information. In that variation, the tuple type +has "_ALPHA" added to it (e.g. "RGB_ALPHA") and one +more plane. The highest numbered plane is the opacity plane (sometimes +called an alpha plane or transparency plane). + +<p>In this kind of image, the color represented by a pixel is actually +a combination of an explicitly specified foreground color and a background +color to be identified later. + +<p>The planes other than the opacity plane describe the foreground +color. A sample in the opacity plane tells how opaque the pixel is, by +telling what fraction of the pixel's light comes from the foreground +color. The rest of the pixel's light comes from the (unspecified) +background color. + +<p>For example, in a GRAYSCALE_ALPHA image, assume Plane 0 indicates +a gray tone 60% of white and Plane 1 indicates opacity 25%. The +foreground color is the 60% gray, and 25% of that contributes to the +ultimate color of the pixel. The other 75% comes from some background +color. So let's assume further that the background color of the pixel +is full white. Then the color of the pixel is 90% of white: 25% of +the foreground 60%, plus 75% of the background 100%. + +<p>The sample value is the opacity fraction just described, as a fraction +of the maxval. Note that it is <em>not</em> gamma-adjusted like the +foreground color samples. + + +<H2 id="seealso">SEE ALSO</H2> + +<B><A HREF="index.html">Netpbm</A></B>, +<B><A HREF="pbm.html">pbm</A></B>, +<B><A HREF="pgm.html">pgm</A></B>, +<B><A HREF="ppm.html">ppm</A></B>, +<B><A HREF="pnm.html">pnm</A></B>, +<B><A HREF="libnetpbm.html">libnetpbm</A></B> + + +<HR> +<H2 id="contents">Table Of Contents</H2> +<UL> + <LI><A HREF="#general">GENERAL</A> + <LI><A HREF="#layout">THE LAYOUT</A> + <LI><A HREF="#limitations">LIMITATIONS</A> + <LI><A HREF="#format_universe">The Confusing Universe of Netpbm Formats</A> + <LI><A HREF="#tupletype">DEFINED TUPLE TYPES</A> + <UL> + <LI><A HREF="#visual">PAM Used For Visual Images</A> + <UL> + <LI>Black And White + <LI>Grayscale + <LI>Color + </UL> + </UL> + <LI><A HREF="#seealso">SEE ALSO</A> +</UL> + +</BODY> +</HTML> |