1PAM format specification(5)   File Formats Manual  PAM format specification(5)
2
3
4

NAME

6       pam - Netpbm common 2-dimensional bitmap format
7
8

GENERAL

10       The  PAM  image format is a lowest common denominator 2 dimensional map
11       format.
12
13       It is designed to be used for any of myriad kinds of graphics, but  can
14       theoretically  be  used  for any kind of data that is arranged as a two
15       dimensional rectangular array.  Actually, from another  perspective  it
16       can be seen as a format for data arranged as a three dimensional array.
17
18       The  name  'PAM'  is  an acronym derived from 'Portable Arbitrary Map.'
19       This derivation makes more sense if you consider it in the  context  of
20       the other Netpbm format names: PBM, PGM, and PPM.
21
22       This  format  does not define the meaning of the data at any particular
23       point in the array.  It could be red, green, and blue light intensities
24       such  that the array represents a visual image, or it could be the same
25       red, green, and blue components plus a transparency  component,  or  it
26       could  contain annual rainfalls for places on the surface of the Earth.
27       Any process that uses the PAM format must further define the format  to
28       specify the meanings of the data.
29
30       A PAM image describes a two dimensional grid of tuples.  The tuples are
31       arranged in rows and columns.  The width of the image is the number  of
32       columns.   The height of the image is the number of rows.  All rows are
33       the same width and all columns are the same  height.   The  tuples  may
34       have  any  degree,  but all tuples have the same degree.  The degree of
35       the tuples is called the depth of the image.  Each member of a tuple is
36       called  a  sample.   A sample is an unsigned integer which represents a
37       locus along a scale which starts at zero and ends at a certain  maximum
38       value  called  the  maxval.  The maxval is the same for every sample in
39       the image.  The two dimensional array of all the Nth  samples  of  each
40       tuple is called the Nth plane or Nth channel of the image.
41
42       Though  the  basic format does not assign any meaning to the tuple val‐
43       ues, it does include an optional string that  describes  that  meaning.
44       The  contents of this string, called the tuple type, are arbitrary from
45       the point of view of the basic PAM format, but users of the format  may
46       assign  meaning to it by convention so they can identify their particu‐
47       lar implementations of the PAM format.  Some tuple types are defined as
48       official subformats of PAM.  See Defined Tuple Types ⟨#tupletype⟩ .
49
50

The Confusing Universe of Netpbm Formats

52       It  is easy to get confused about the relationship between the PAM for‐
53       mat and PBM, PGM, PPM, and PNM.  Here is a little enlightenment:
54
55       "PNM" is not really a format.  It is a shorthand for the PBM, PGM,  and
56       PPM  formats  collectively.   It is also the name of a group of library
57       functions that can each handle all three of those formats.
58
59       'PAM' is in fact a fourth format.  But it is so general  that  you  can
60       represent the same information in a PAM image as you can in a PBM, PGM,
61       or PPM image.  And in fact a program that is designed to read PBM, PGM,
62       or  PPM  and  does so with a recent version of the Netpbm library, will
63       read an equivalent PAM image just fine and the program will never  know
64       the difference.
65
66       To  confuse  things  more,  there  is  a collection of library routines
67       called the 'pam' functions that read and write the PAM format, but also
68       read and write the PBM, PGM, and PPM formats.  They do this because the
69       latter formats are much older and more popular, so even a  new  program
70       must  work  with them.  Having the library handle all the formats makes
71       it convenient to write programs that use the newer PAM format as well.
72
73

THE LAYOUT

75       A convenient way to read and write the PAM format accurately is via the
76       libnetpbm(1)Csubroutinelibrary.
77
78       A PAM file consists of a sequence of one or more PAM images.  There are
79       no data, delimiters, or padding before, after, or between images.
80
81       Each PAM image consists of a header followed immediately by a raster.
82
83       Here is an example header:
84
85       P7
86       WIDTH 227
87       HEIGHT 149
88       DEPTH 3
89       MAXVAL 255
90       TUPLTYPE RGB
91       ENDHDR
92
93       The header begins with the ASCII characters 'P7' followed  by  newline.
94       This is the magic number.
95
96       Note: xv thumbnail images also start with the "P7" magic number.  (This
97       and PAM were independent extensions to the Netpbm formats).   The  rest
98       of  the  format  makes  it  easy  to  distinguish PAM from that format,
99       though).
100
101       The header continues with an arbitrary number of lines of  ASCII  text.
102       Each line ends with and is delimited by a newline character.
103
104       Each  header  line consists of zero or more whitespace-delimited tokens
105       or begins with '#'.  If it begins with '#' it is a comment and the rest
106       of this specification does not apply to it.
107
108       A header line which has zero tokens is valid but has no meaning.
109
110       The  type  of  header line is identified by its first token, which is 8
111       characters or less:
112
113
114
115       ENDHDR This is the last line in the header.  The  header  must  contain
116              exactly one of these header lines.
117
118
119       HEIGHT The  second token is a decimal number representing the height of
120              the image (number of rows).  The header must contain exactly one
121              of these header lines.
122
123
124       WIDTH  The  second  token is a decimal number representing the width of
125              the image (number of columns).  The header must contain  exactly
126              one of these header lines.
127
128
129       DEPTH  The  second  token is a decimal number representing the depth of
130              the image (number of planes or channels).  The header must  con‐
131              tain exactly one of these header lines.
132
133
134       MAXVAL The  second token is a decimal number representing the maxval of
135              the image.  The header must contain exactly one of these  header
136              lines.
137
138
139       TUPLTYPE
140              The header may contain any number of these header lines, includ‐
141              ing zero.  The rest of the line is part of the tuple type.   The
142              rest  of  the line is not tokenized, but the tuple type does not
143              include any white space immediately following  TUPLTYPE   or  at
144              the very end of the line.  It does not include a newline.  There
145              must be something other than  white  space  after  the  TUPLTYPE
146              token.
147
148              If  there  are multiple TUPLTYPE header lines, the tuple type is
149              the concatenation of the values from each of them, separated  by
150              a single blank, in the order in which they appear in the header.
151              If there are no TUPLTYPE header lines the tuple type is the null
152              string.
153
154
155
156       The raster consists of each row of the image, in order from top to bot‐
157       tom, consecutive with no delimiter of  any  kind  between,  before,  or
158       after, rows.
159
160       Each  row  consists  of  every  tuple in the row, in order from left to
161       right, consecutive with no delimiter of any kind  between,  before,  or
162       after, tuples.
163
164       Each tuple consists of every sample in the tuple, in order, consecutive
165       with no delimiter of any kind between, before, or after, samples.
166
167       Each sample consists of an unsigned integer in pure binary format, with
168       the  most  significant  byte first.  The number of bytes is the minimum
169       number of bytes required to represent the maxval of the image.
170
171       The character referred to as 'newline' herein is the character known in
172       ASCII as Line Feed or LF.
173
174

LIMITATIONS

176       Height, width, depth, and maxval are at least 1.
177
178       Height,  width,  and  depth have no defined maximum, but processors and
179       generators of images usually have their own limitations.
180
181       The maxval of an image is never greater than 65535.  (The reason it  is
182       limited  is  to  make  it  easier to build an image processor, in which
183       intermediate arithmetic values often have to fit within 31 or 32 bits).
184       There was no specified limitation before October, 2005, but essentially
185       all implementations have always observed it.
186
187

DEFINED TUPLE TYPES

189       Some tuple types are defined in this specification to specify  official
190       subformats  of  PAM  for especially popular applications of the format.
191       Users of the format may also define their own  tuple  types,  and  thus
192       their own subformats.
193
194
195   PAM Used For Visual Images
196       A  common  use  of PAM images is to represent visual images such as are
197       typically represented by images in the older  and  more  concrete  PBM,
198       PGM, and PPM formats.
199
200       Black And White (PBM)
201
202       A  black  and white image, such as would be represented by a PBM image,
203       has a tuple type of "BLACKANDWHITE".  Such a PAM image has a depth of 1
204       and  maxval  1  where  the one sample in each tuple is 0 to represent a
205       black pixel and 1 to represent a white one.   The  height,  width,  and
206       raster  bear  the  obvious  relationship to those of the equivalent PBM
207       image.
208
209       Note that in the PBM format, a zero value means white, but in PAM, zero
210       means black.
211
212       Grayscale (PGM)
213
214       A  grayscale  image, such as would be represented by a PGM image, has a
215       tuple type of "GRAYSCALE".  Such a PAM image has a  depth  of  1.   The
216       maxval,  height,  width,  and  raster  bear the obvious relationship to
217       those of the equivalent PGM image.
218
219       Color (PPM)
220
221       A color image, such as would be represented by a PPM image, has a typle
222       type of "RGB".  Such a PAM image has a depth of 3.  The maxval, height,
223       width, and raster bear the obvious relationship to  those  of  the  PPM
224       image.  The first plane represents red, the second green, and the third
225       blue.
226
227       Transparent
228
229       Each of the visual image formats mentioned above has a  variation  that
230       contains  transparency  information.  In that variation, the tuple type
231       has '_ALPHA' added to it (e.g. 'RGB_ALPHA') and one  more  plane.   The
232       highest  numbered plane is the opacity plane (sometimes called an alpha
233       plane or transparency plane).
234
235       In this kind of image, the color represented by a pixel is  actually  a
236       combination  of  an  explicitly  specified foreground color and a back‐
237       ground color to be identified later.
238
239       The planes other than the opacity plane describe the foreground  color.
240       A sample in the opacity plane tells how opaque the pixel is, by telling
241       what fraction of the pixel's light comes  from  the  foreground  color.
242       The  rest  of the pixel's light comes from the (unspecified) background
243       color.
244
245       For example, in a GRAYSCALE_ALPHA image, assume  Plane  0  indicates  a
246       gray  tone  60%  of white and Plane 1 indicates opacity 25%.  The fore‐
247       ground color is the 60% gray, and 25% of that contributes to the  ulti‐
248       mate  color  of  the  pixel.   The other 75% comes from some background
249       color.  So let's assume further that the background color of the  pixel
250       is  full  white.   Then the color of the pixel is 90% of white:  25% of
251       the foreground 60%, plus 75% of the background 100%.
252
253       The sample value is the opacity fraction just described, as a  fraction
254       of  the maxval.  Note that it is not gamma-adjusted like the foreground
255       color samples.
256
257
258

SEE ALSO

260       Netpbm(1), pbm(1), pgm(1), ppm(1), pnm(1), libnetpbm(1)
261
262
263
264netpbm documentation            09 October 2005    PAM format specification(5)
Impressum