Penguin
Recent Changes
Annotated edit history of pam(5) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 pam
2 !!!pam
3 NAME
4 DESCRIPTION
5 SEE ALSO
6 ----
7 !!NAME
8
9
10 pam - portable arbitrary map file format
11 !!DESCRIPTION
12
13
14 The PAM image format is a lowest common denominator 2
15 dimensional map format.
16
17
18 It is designed to be used for any of myriad kinds of
19 graphics, but can theoretically be used for any kind of data
20 that is arranged as a two dimensional rectangular array.
21 Actually, from another perspective it can be seen as a
22 format for data arranged as a three dimensional
23 array.
24
25
26 This format does not define the meaning of the data at any
27 particular point in the array. It could be red, green, and
28 blue light intensities such that the array represents a
29 visual image, or it could be the same red, green, and blue
30 components plus a transparency component, or it could
31 contain annual rainfalls for places on the surface of the
32 Earth. Any process that uses the PAM format must further
33 define the format to specify the meanings of the
34 data.
35
36
37 A PAM image describes a two dimensional grid of tuples. The
38 tuples are arranged in rows and columns. The width of the
39 image is the number of columns. The height of the image is
40 the number of rows. All rows are the same width and all
41 columns are the same height. The tuples may have any degree,
42 but all tuples have the same degree. The degree of the
43 tuples is called the depth of the image. Each member of a
44 tuple is called a sample. A sample is an unsigned integer
45 which represents a locus along a scale which starts at zero
46 and ends at a certain maximum value greater than zero called
47 the maxval. The maxval is the same for every sample in the
48 image. The two dimensional array of all the Nth samples of
49 each tuple is called the Nth plane or Nth channel of the
50 image.
51
52
53 Though the format does not assign any meaning to the tuple
54 values, it does include an optional string that describes
55 that meaning. The contents of this string, called the tuple
56 type, are arbitrary from the point of view of the PAM
57 format, but users of the format may assign meaning to it by
58 convention so they can identify their particular
59 implementations of the PAM format.
60
61
62 __The Layout__
63
64
65 A PAM file consists of a sequence of one or more PAM images.
66 There are no data, delimiters, or padding before, after, or
67 between images.
68
69
70 Each PAM image consists of a header followed immediately by
71 a raster.
72
73
74 Here is an example header:
75
76
77 __P7
78 WIDTH 227
79 HEIGHT 149
80 DEPTH 3
81 MAXVAL 255
82 TUPLETYPE RGB
83 ENDHDR__
84
85
86 The header begins with the ASCII characters
87
88
89 The header continues with an arbitrary number of lines of
90 ASCII text. Each line ends with and is delimited by a
91 newline character.
92
93
94 Each header line consists of zero or more
95 whitespace-delimited tokens or begins with
96
97
98 A header line which has zero tokens is valid but has no
99 meaning.
100
101
102 The type of header line is identified by its first token,
103 which is 8 characters or less:
104
105
106 __ENDHDR__
107
108
109 This is the last line in the header. The header must contain
110 exactly one of these header lines.
111
112
113 __HEIGHT__
114
115
116 The second token is a decimal number representing the height
117 of the image (number of rows). The header must contain
118 exactly one of these header lines.
119
120
121 __WIDTH__
122
123
124 The second token is a decimal number representing the width
125 of the image (number of columns). The header must contain
126 exactly one of these header lines.
127
128
129 __DEPTH__
130
131
132 The second token is a decimal number representing the depth
133 of the image (number of planes or channels). The header must
134 contain exactly one of these header lines.
135
136
137 __MAXVAL__
138
139
140 The second token is a decimal number representing the maxval
141 of the image. The header must contain exactly one of these
142 header lines.
143
144
145 __TUPLTYPE__
146
147
148 The header may contain any number of these header lines,
149 including zero. The rest of the line is part of the tuple
150 type. The rest of the line is not tokenized, but the tuple
151 type does not include any white space immediately following
152 __TUPLTYPE__ or at the very end of the line. It does not
153 include a newline. If there are multiple __TUPLTYPE__
154 header lines, the tuple type is the concatenation of the
155 values from each of them, separated by a single blank, in
156 the order in which they appear in the header. If there are
157 no __TUPLETYPE__ header lines the tuple type is the null
158 string.
159
160
161 The raster consists of each row of the image, in order from
162 top to bottom, consecutive with no delimiter of any kind
163 between, before, or after, rows.
164
165
166 Each row consists of every tuple in the row, in order from
167 left to right, consecutive with no delimiter of any kind
168 between, before, or after, tuples.
169
170
171 Each tuple consists of every sample in the tuple, in order,
172 consecutive with no delimiter of any kind between, before,
173 or after, samples.
174
175
176 Each sample consists of an unsigned integer in pure binary
177 format, with the most significant byte first. The number of
178 bytes is the minimum number of bytes required to represent
179 the maxval of the image.
180
181
182 __PAM Used For PNM (PBM, PGM, or PPM)
183 Images__
184
185
186 A common use of PAM images is to represent the older and
187 more concrete PBM, PGM, and PPM images.
188
189
190 A PBM image is conventionally represented as a PAM image of
191 depth 1 with maxval 1 where the one sample in each tuple is
192 0 to represent a black pixel and 1 to represent a white one.
193 The height, width, and raster bear the obvious relationship
194 to those of the PBM image. The tuple type for PBM images
195 represented as PAM images is conventionally
196
197
198 A PGM image is conventionally represented as a PAM image of
199 depth 1. The maxval, height, width, and raster bear the
200 obvious relationship to those of the PGM image. The tuple
201 type for PGM images represented as PAM images is
202 conventionally
203
204
205 A PPM image is conventionally represented as a PAM image of
206 depth 3. The maxval, height, width, and raster bear the
207 obvious relationship to those of the PPM image. The first
208 plane represents red, the second blue, and the third green.
209 The tuple type for PPM images represented as PAM images is
210 conventionally
211
212
213 __The Confusing Universe of Netpbm Formats__
214
215
216 It is easy to get confused about the relationship between
217 the PAM format and PBM, PGM, PPM, and PNM. Here is a little
218 enlightenment:
219
220
221
222
223
224
225 To confuse things more, there is a collection of library
226 routines called the
227 !!SEE ALSO
228
229
230 pbm(5), pgm(5), ppm(5), pnm(5),
231 libpnm(3)
232 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.