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  greater than zero called the maxval.  The maxval is the same for
39       every sample in the image.  The two dimensional array of  all  the  Nth
40       samples  of  each  tuple  is called the Nth plane or Nth channel of the
41       image.
42
43       Though the basic format does not assign any meaning to the  tuple  val‐
44       ues,  it  does  include an optional string that describes that meaning.
45       The contents of this string, called the tuple type, are arbitrary  from
46       the  point of view of the basic PAM format, but users of the format may
47       assign meaning to it by convention so they can identify their  particu‐
48       lar implementations of the PAM format.  Some tuple types are defined as
49       official subformats of PAM.  See Defined Tuple Types ⟨#tupletype⟩ .
50
51       <H2 id="format_universe">The Confusing Universe of Netpbm Formats</H2>
52
53       It is easy to get confused about the relationship between the PAM  for‐
54       mat and PBM, PGM, PPM, and PNM.  Here is a little enlightenment:
55
56       "PNM"  is not really a format.  It is a shorthand for the PBM, PGM, and
57       PPM formats collectively.  It is also the name of a  group  of  library
58       functions that can each handle all three of those formats.
59
60       'PAM'  is  in  fact a fourth format.  But it is so general that you can
61       represent the same information in a PAM image as you can in a PBM, PGM,
62       or PPM image.  And in fact a program that is designed to read PBM, PGM,
63       or PPM and does so with a recent version of the  Netpbm  library,  will
64       read  an equivalent PAM image just fine and the program will never know
65       the difference.
66
67       To confuse things more, there  is  a  collection  of  library  routines
68       called the 'pam' functions that read and write the PAM format, but also
69       read and write the PBM, PGM, and PPM formats.  They do this because the
70       latter  formats  are much older and more popular, so even a new program
71       must work with them.  Having the library handle all the  formats  makes
72       it convenient to write programs that use the newer PAM format as well.
73
74

THE LAYOUT

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

LIMITATIONS

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

DEFINED TUPLE TYPES

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

SEE ALSO

255       Netpbm(1), pbm(1), pgm(1), ppm(1), pnm(1), libnetpbm(1)
256
257
258
259netpbm documentation            09 October 2005    PAM format specification(5)
Impressum