264 lines
8.7 KiB
HTML
264 lines
8.7 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of pam</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>pam</H1>
|
|
Section: File Formats (5)<BR>Updated: 31 July 2000<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
pam - portable arbitrary map file format
|
|
<P>
|
|
<A NAME="lbAC"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
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>
|
|
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 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 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.
|
|
<P>
|
|
<A NAME="lbAD"> </A>
|
|
<H3>The Layout</H3>
|
|
|
|
<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>
|
|
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:
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="1"><B>ENDHDR </B>
|
|
|
|
<DD>
|
|
This is the last line in the header. The header must contain exactly
|
|
one of these header lines.
|
|
<P>
|
|
<DT id="2"><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.
|
|
<P>
|
|
<DT id="3"><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.
|
|
<P>
|
|
<DT id="4"><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.
|
|
<P>
|
|
<DT id="5"><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.
|
|
<P>
|
|
<P>
|
|
<DT id="6"><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.
|
|
<P>
|
|
</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.
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAE"> </A>
|
|
<H3>PAM Used For PNM (PBM, PGM, or PPM) Images</H3>
|
|
|
|
<P>
|
|
A common use of PAM images is to represent the older and more concrete
|
|
PBM, PGM, and PPM images.
|
|
<P>
|
|
A PBM image is conventionally represented as a PAM image of depth 1
|
|
with 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 PBM image.
|
|
The tuple type for PBM images represented as PAM images is
|
|
conventionally "BLACKANDWHITE".
|
|
<P>
|
|
A PGM image is conventionally represented as a PAM image of depth 1.
|
|
The maxval, height, width, and raster bear the obvious relationship
|
|
to those of the PGM image. The tuple type for PGM images represented
|
|
as PAM images is conventionally "GRAYSCALE".
|
|
<P>
|
|
A PPM image is conventionally represented as a PAM image of depth 3.
|
|
The maxval, height, width, and raster bear the obvious relationship to
|
|
those of the PPM image. The first plane represents red, the second
|
|
green, and the third blue. The tuple type for PPM images represented
|
|
as PAM images is conventionally "RGB".
|
|
<P>
|
|
<A NAME="lbAF"> </A>
|
|
<H3>The Confusing Universe of Netpbm Formats</H3>
|
|
|
|
<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 this
|
|
makes it convenient to write programs that use the newer PAM format.
|
|
<P>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?5+pbm">pbm</A></B>(5),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?5+pgm">pgm</A></B>(5),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?5+ppm">ppm</A></B>(5),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?5+pnm">pnm</A></B>(5),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+libpnm">libpnm</A></B>(3)
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="7"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="8"><A HREF="#lbAC">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="9"><A HREF="#lbAD">The Layout</A><DD>
|
|
<DT id="10"><A HREF="#lbAE">PAM Used For PNM (PBM, PGM, or PPM) Images</A><DD>
|
|
<DT id="11"><A HREF="#lbAF">The Confusing Universe of Netpbm Formats</A><DD>
|
|
</DL>
|
|
<DT id="12"><A HREF="#lbAG">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:04 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|