Debian Codegraph @

upstream/debian-unstable/man5/pam.5

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "PAM format specification" 5 "27 November 2013" "netpbm documentation"
7
8 .SH NAME
9 pam - Netpbm common 2-dimensional bitmap format
10
11 .UN general
12 .SH GENERAL
13 .PP
14 The PAM image format is a lowest common denominator 2 dimensional map
15 format.
16 .PP
17 It is designed to be used for any of myriad kinds of graphics, but can
18 theoretically be used for any kind of data that is arranged as a two
19 dimensional rectangular array. Actually, from another perspective it
20 can be seen as a format for data arranged as a three dimensional
21 array.
22 .PP
23 The name "PAM" is an acronym derived from "Portable
24 Arbitrary Map." This derivation makes more sense if you consider
25 it in the context of the other Netpbm format names: PBM, PGM, and PPM.
26 .PP
27 This format does not define the meaning of the data at any particular
28 point in the array. It could be red, green, and blue light
29 intensities such that the array represents a visual image, or it could
30 be the same red, green, and blue components plus a transparency
31 component, or it could contain annual rainfalls for places on the
32 surface of the Earth. Any process that uses the PAM format must
33 further define the format to specify the meanings of the data.
34 .PP
35 A PAM image describes a two dimensional grid of tuples. The tuples are
36 arranged in rows and columns. The width of the image is the number of
37 columns. The height of the image is the number of rows. All rows are the
38 same width and all columns are the same height. The tuples may have any
39 degree, but all tuples have the same degree. The degree of the tuples is
40 called the depth of the image. Each member of a tuple is called a sample. A
41 sample is an unsigned integer which represents a locus along a scale which
42 starts at zero and ends at a certain maximum value called the maxval. The
43 maxval is the same for every sample in the image. The two dimensional array
44 of all the Nth samples of each tuple is called the Nth plane or Nth channel of
45 the image.
46 .PP
47 Though the basic format does not assign any meaning to the tuple values, it
48 does include an optional string that describes that meaning. The
49 contents of this string, called the tuple type, are arbitrary from the
50 point of view of the basic PAM format, but users of the format may assign
51 meaning to it by convention so they can identify their particular
52 implementations of the PAM format. Some tuple types are defined as
53 official subformats of PAM. See
54 .UR #tupletype
55 Defined Tuple Types
56 .UE
57 \&.
58
59 .UN format_universe
60 .SH The Confusing Universe of Netpbm Formats
61 .PP
62 It is easy to get confused about the relationship between the PAM
63 format and PBM, PGM, PPM, and PNM. Here is a little enlightenment:
64 .PP
65 "PNM" is not really a format. It is a shorthand for the PBM, PGM,
66 and PPM formats collectively. It is also the name of a group of
67 library functions that can each handle all three of those formats.
68 .PP
69 "PAM" is in fact a fourth format. But it is so general
70 that you can represent the same information in a PAM image as you can
71 in a PBM, PGM, or PPM image. And in fact a program that is designed
72 to read PBM, PGM, or PPM and does so with a recent version of the
73 Netpbm library will read an equivalent PAM image just fine and the
74 program will never know the difference.
75 .PP
76 To confuse things more, there is a collection of library routines
77 called the "pam" functions that read and write the PAM
78 format, but also read and write the PBM, PGM, and PPM formats. They
79 do this because the latter formats are much older and more popular, so
80 even a new program must work with them. Having the library handle all
81 the formats makes it convenient to write programs that use the newer
82 PAM format as well.
83
84 .UN layout
85 .SH THE LAYOUT
86 .PP
87 A convenient way to read and write the PAM format accurately is via the
88 .BR "libnetpbm" (1)\c
89 \& C subroutine library.
90 .PP
91 A PAM file consists of a sequence of one or more PAM images. There are
92 no data, delimiters, or padding before, after, or between images.
93 .PP
94 Each PAM image consists of a header followed immediately by a raster.
95 .PP
96 Here is an example header:
97
98 .nf
99
100 P7
101 WIDTH 227
102 HEIGHT 149
103 DEPTH 3
104 MAXVAL 255
105 TUPLTYPE RGB
106 ENDHDR
107
108
109 .fi
110 .PP
111 The header begins with the ASCII characters "P7" followed
112 by newline. This is the magic number.
113 .PP
114 Note: \fBxv\fP thumbnail images also start with the "P7" magic number.
115 (This and PAM were independent extensions to the Netpbm formats). The rest
116 of the format makes it easy to distinguish PAM from that format, though).
117 .PP
118 The header continues with an arbitrary number of lines of ASCII
119 text. Each line ends with and is delimited by a newline character.
120 .PP
121 Each header line consists of zero or more whitespace-delimited
122 tokens or begins with "#". If it begins with "#"
123 it is a comment and the rest of this specification does not apply to
124 it.
125 .PP
126 A header line which has zero tokens is valid but has no meaning.
127 .PP
128 The type of header line is identified by its first token, which is
129 8 characters or less:
130
131
132 .TP
133 \fBENDHDR \fP
134 This is the last line in the header. The header must contain
135 exactly one of these header lines.
136
137 .TP
138 \fBHEIGHT \fP
139 The second token is a decimal number representing the height
140 of the image (number of rows). The header must contain exactly one
141 of these header lines.
142
143 .TP
144 \fBWIDTH\fP
145 The second token is a decimal number representing the width of the
146 image (number of columns). The header must contain exactly one of
147 these header lines.
148
149 .TP
150 \fBDEPTH\fP
151 The second token is a decimal number representing the depth of the
152 image (number of planes or channels). The header must contain exactly
153 one of these header lines.
154
155 .TP
156 \fBMAXVAL\fP
157 The second token is a decimal number representing the maxval of the image.
158 The header must contain exactly one of these header lines.
159
160 .TP
161 \fBTUPLTYPE\fP
162 The header may contain any number of these header lines, including
163 zero. The rest of the line is part of the tuple type. The rest of
164 the line is not tokenized, but the tuple type does not include any
165 white space immediately following \fBTUPLTYPE \fP or at the very end
166 of the line. It does not include a newline. There must be something
167 other than white space after the \fBTUPLTYPE\fP token.
168 .sp
169 If there are multiple \fBTUPLTYPE\fP header lines, the tuple type
170 is the concatenation of the values from each of them, separated by a
171 single blank, in the order in which they appear in the header. If
172 there are no \fBTUPLTYPE\fP header lines the tuple type is the null
173 string.
174
175
176 .PP
177 The raster consists of each row of the image, in order from top to bottom,
178 consecutive with no delimiter of any kind between, before, or after, rows.
179 .PP
180 Each row consists of every tuple in the row, in order from left to
181 right, consecutive with no delimiter of any kind between, before, or
182 after, tuples.
183 .PP
184 Each tuple consists of every sample in the tuple, in order,
185 consecutive with no delimiter of any kind between, before, or after,
186 samples.
187 .PP
188 Each sample consists of an unsigned integer in pure binary format,
189 with the most significant byte first. The number of bytes is the
190 minimum number of bytes required to represent the maxval of the image.
191 .PP
192 The character referred to as "newline" herein is the
193 character known in ASCII as Line Feed or LF.
194
195 .UN limitations
196 .SH LIMITATIONS
197 .PP
198 Height, width, depth, and maxval are at least 1.
199 .PP
200 Height, width, and depth have no defined maximum, but processors and
201 generators of images usually have their own limitations.
202 .PP
203 The maxval of an image is never greater than 65535. (The reason it is
204 limited is to make it easier to build an image processor, in which
205 intermediate arithmetic values often have to fit within 31 or 32 bits).
206 There was no specified limitation before October, 2005, but essentially
207 all implementations have always observed it.
208
209 .UN tupletype
210 .SH DEFINED TUPLE TYPES
211 .PP
212 Some tuple types are defined in this specification to specify
213 official subformats of PAM for especially popular applications of the
214 format. Users of the format may also define their own tuple types,
215 and thus their own subformats.
216 .PP
217 Tuple type affects \fIonly\fP the meanings of the samples (which are
218 unsigned integers) in the tuples of the image. It does not affect how the
219 samples or tuples are encoded. Tuple type may affect the meaning of a tuple's
220 position in the array (e.g. it may indicate in a visual image that a tuple
221 in Row 1 is one at the top of the image rather than the bottom).
222 .PP
223 Tuple type never determines how many samples are in a tuple (that is
224 instead determined by the DEPTH header line). Tuple type could be said to
225 imply a depth (number of samples per tuple) because certain tuple types are
226 valid only in combination with certain DEPTH values, but it is good
227 programming practice to use DEPTH for the depth when decoding the raster and
228 separately validate that the depth is consistent with the tuple type. Also,
229 it is good practice to accept a depth that is too great and just ignore the
230 higher numbered planes.
231
232 .UN visual
233 .SS PAM Used For Visual Images
234 .PP
235 A common use of PAM images is to represent visual images such
236 as are typically represented by images in the older and more concrete
237 PBM, PGM, and PPM formats.
238
239 .B Black And White
240 .PP
241 A black and white image, such as would alternatively be represented by a
242 PBM image, has a tuple type of "BLACKANDWHITE". Such a PAM image has a depth
243 of 1 and maxval 1 where the one sample in each tuple is 0 to represent a black
244 pixel and 1 to represent a white one. The maxval, height, width, and order of
245 tuples in the raster bear the obvious relationship to those of the equivalent
246 PBM image.
247 .PP
248 Note that in the PBM format, a sample value of zero means white, but in
249 PAM, zero means black.
250
251 .B Grayscale
252 .PP
253 A grayscale image, such as would alternatively be represented by a PGM
254 image, has a tuple type of "GRAYSCALE". Such a PAM image has a depth of 1.
255 The maxval, height, width, and raster bear the obvious relationship to those
256 of the equivalent PGM image.
257
258 .B Color
259 .PP
260 A color image, such as would alternatively be represented by a PPM image,
261 has a tuple type of "RGB". Such a PAM image has a depth of 3. The maxval,
262 height, width, and raster bear the obvious relationship to those of the PPM
263 image. The first plane represents red, the second green, and the third blue.
264
265 .B Transparent
266 .PP
267 Each of the visual image formats mentioned above has a variation that
268 contains transparency information. In that variation, the tuple type
269 has "_ALPHA" added to it (e.g. "RGB_ALPHA") and one
270 more plane. The highest numbered plane is the opacity plane (sometimes
271 called an alpha plane or transparency plane).
272 .PP
273 In this kind of image, the color represented by a pixel is actually
274 a combination of an explicitly specified foreground color and a background
275 color to be identified later.
276 .PP
277 The planes other than the opacity plane describe the foreground
278 color. A sample in the opacity plane tells how opaque the pixel is, by
279 telling what fraction of the pixel's light comes from the foreground
280 color. The rest of the pixel's light comes from the (unspecified)
281 background color.
282 .PP
283 For example, in a GRAYSCALE_ALPHA image, assume Plane 0 indicates
284 a gray tone 60% of white and Plane 1 indicates opacity 25%. The
285 foreground color is the 60% gray, and 25% of that contributes to the
286 ultimate color of the pixel. The other 75% comes from some background
287 color. So let's assume further that the background color of the pixel
288 is full white. Then the color of the pixel is 90% of white: 25% of
289 the foreground 60%, plus 75% of the background 100%.
290 .PP
291 The sample value is the opacity fraction just described, as a fraction
292 of the maxval. Note that it is \fInot\fP gamma-adjusted like the
293 foreground color samples.
294
295
296 .UN internetmediatype
297 .SH INTERNET MEDIA TYPE
298 .PP
299 No Internet Media Type (aka MIME type, content type) for PAM has been
300 registered with IANA, but the unofficial value
301 image/x-portable-arbitrarymap is
302 assigned by this specification, to be consistent with conventional values for
303 the older Netpbm formats.
304
305 .UN filename
306 .SH FILE NAME
307 .PP
308 The conventional suffix for the name of a PAM file is ".pam".
309 But this is not required.
310
311
312 .UN seealso
313 .SH SEE ALSO
314 .BR "Netpbm" (1)\c
315 \&,
316 .BR "pbm" (1)\c
317 \&,
318 .BR "pgm" (1)\c
319 \&,
320 .BR "ppm" (1)\c
321 \&,
322 .BR "pnm" (1)\c
323 \&,
324 .BR "libnetpbm" (1)\c
325 \&
326 .SH DOCUMENT SOURCE
327 This manual page was generated by the Netpbm tool 'makeman' from HTML
328 source. The master documentation is at
329 .IP
330 .B http://netpbm.sourceforge.net/doc/pam.html
331 .PP