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

LIMITATIONS

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

DEFINED TUPLE TYPES

191       Some tuple types are defined in this specification to specify  official
192       subformats  of  PAM  for especially popular applications of the format.
193       Users of the format may also define their own  tuple  types,  and  thus
194       their own subformats.
195
196       Tuple type affects only the meanings of the samples (which are unsigned
197       integers) in the tuples of the image.  It does not affect how the  sam‐
198       ples  or  tuples  are  encoded.  Tuple type may affect the meaning of a
199       tuple's position in the array (e.g. it may indicate in a  visual  image
200       that  a  tuple  in Row 1 is one at the top of the image rather than the
201       bottom).
202
203       Tuple type never determines how many samples are in a  tuple  (that  is
204       instead determined by the DEPTH header line).  Tuple type could be said
205       to imply a depth (number of samples per tuple)  because  certain  tuple
206       types  are  valid only in combination with certain DEPTH values, but it
207       is good programming practice to use DEPTH for the depth  when  decoding
208       the  raster  and  separately validate that the depth is consistent with
209       the tuple type.  Also, it is good practice to accept a  depth  that  is
210       too great and just ignore the higher numbered planes.
211
212
213   PAM Used For Visual Images
214       A  common  use  of PAM images is to represent visual images such as are
215       typically represented by images in the older  and  more  concrete  PBM,
216       PGM, and PPM formats.
217
218       Black And White
219
220       A  black and white image, such as would alternatively be represented by
221       a PBM image, has a tuple type of "BLACKANDWHITE".  Such a PAM image has
222       a  depth  of  1 and maxval 1 where the one sample in each tuple is 0 to
223       represent a black pixel and 1 to represent a white  one.   The  maxval,
224       height, width, and order of tuples in the raster bear the obvious rela‐
225       tionship to those of the equivalent PGM image.
226
227       Note that in the PBM format, a sample value of zero means white, but in
228       PAM, zero means black.
229
230       Grayscale
231
232       A  grayscale image, such as would alternatively be represented by a PGM
233       image, has a tuple type of "GRAYSCALE".  Such a PAM image has  a  depth
234       of 1.  The maxval, height, width, and raster bear the obvious relation‐
235       ship to those of the equivalent PGM image.
236
237       Color
238
239       A color image, such as would alternatively  be  represented  by  a  PPM
240       image,  has  a tuple type of "RGB".  Such a PAM image has a depth of 3.
241       The maxval, height, width, and raster bear the obvious relationship  to
242       those  of  the  PPM  image.  The first plane represents red, the second
243       green, and the third blue.
244
245       Transparent
246
247       Each of the visual image formats mentioned above has a  variation  that
248       contains  transparency  information.  In that variation, the tuple type
249       has "_ALPHA" added to it (e.g. "RGB_ALPHA") and one  more  plane.   The
250       highest  numbered plane is the opacity plane (sometimes called an alpha
251       plane or transparency plane).
252
253       In this kind of image, the color represented by a pixel is  actually  a
254       combination  of  an  explicitly  specified foreground color and a back‐
255       ground color to be identified later.
256
257       The planes other than the opacity plane describe the foreground  color.
258       A sample in the opacity plane tells how opaque the pixel is, by telling
259       what fraction of the pixel's light comes  from  the  foreground  color.
260       The  rest  of the pixel's light comes from the (unspecified) background
261       color.
262
263       For example, in a GRAYSCALE_ALPHA image, assume  Plane  0  indicates  a
264       gray  tone  60%  of white and Plane 1 indicates opacity 25%.  The fore‐
265       ground color is the 60% gray, and 25% of that contributes to the  ulti‐
266       mate  color  of  the  pixel.   The other 75% comes from some background
267       color.  So let's assume further that the background color of the  pixel
268       is  full  white.   Then the color of the pixel is 90% of white:  25% of
269       the foreground 60%, plus 75% of the background 100%.
270
271       The sample value is the opacity fraction just described, as a  fraction
272       of  the maxval.  Note that it is not gamma-adjusted like the foreground
273       color samples.
274
275
276

INTERNET MEDIA TYPE

278       No Internet Media Type (aka MIME type, content type) for PBM  has  been
279       registered  with  IANA, but the unofficial value <span style="font-fam‐
280       ily:  monospace">image/x-portable-arbitrarymap</span>  is  assigned  by
281       this  specification,  to be consistent with conventional values for the
282       older Netpbm formats.
283
284

FILE NAME

286       The conventional suffix for the name of a PAM file is ".pam".  But this
287       is not required.
288
289
290

SEE ALSO

292       Netpbm(1), pbm(1), pgm(1), ppm(1), pnm(1), libnetpbm(1)
293

DOCUMENT SOURCE

295       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
296       source.  The master documentation is at
297
298              http://netpbm.sourceforge.net/doc/pam.html
299
300netpbm documentation           27 November 2013    PAM format specification(5)
Impressum