Debian Codegraph @

upstream/debian-unstable/man5/pgm.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 "PGM Format Specification" 5 "07 November 2025" "netpbm documentation"
7
8 .SH NAME
9
10 pgm - Netpbm grayscale image format
11
12 .UN description
13 .SH DESCRIPTION
14 .PP
15 This program is part of
16 .BR "Netpbm" (1)\c
17 \&.
18 .PP
19 The PGM format is a lowest common denominator grayscale file format.
20 It is designed to be extremely easy to learn and write programs for.
21 (It's so simple that most people will simply reverse engineer it
22 because it's easier than reading this specification).
23 .PP
24 A PGM image represents a grayscale graphic image. There are many
25 pseudo-PGM formats in use where everything is as specified herein except
26 for the meaning of individual pixel values. For most purposes, a PGM
27 image can just be thought of an array of arbitrary integers, and all the
28 programs in the world that think they're processing a grayscale image
29 can easily be tricked into processing something else.
30 .PP
31 The name "PGM" is an acronym derived from "Portable Gray Map."
32 .PP
33 One official variant of PGM is the transparency mask. A transparency
34 mask in Netpbm is represented by a PGM image, except that in place of
35 pixel intensities, there are opaqueness values. See below.
36
37 .UN format
38 .SH THE FORMAT
39 .PP
40 The format definition is as follows. You can use the
41 .BR "libnetpbm" (1)\c
42 \& C subroutine library to conveniently
43 and accurately read and interpret the format.
44 .PP
45 A PGM file consists of a sequence of one or more PGM images. There are
46 no data, delimiters, or padding before, after, or between images.
47 .PP
48 Each PGM image consists of the following:
49
50
51
52 .IP \(bu
53 A "magic number" for identifying the file type.
54 A pgm image's magic number is the two characters "P5".
55
56 .IP \(bu
57 Whitespace (blanks, TABs, CRs, LFs).
58
59 .IP \(bu
60 A width, formatted as ASCII characters in decimal.
61
62 .IP \(bu
63 Whitespace.
64
65 .IP \(bu
66 A height, again in ASCII decimal.
67
68 .IP \(bu
69 Whitespace.
70
71 .IP \(bu
72 The maximum gray value (Maxval), again in ASCII decimal. Must be less
73 than 65536, and more than zero.
74
75 .IP \(bu
76 A single whitespace character (usually a newline).
77
78 .IP \(bu
79 A raster of Height rows, in order from top to bottom. Each row
80 consists of Width gray values, in order from left to right. Each gray
81 value is a number from 0 through Maxval, with 0 being black and Maxval
82 being white. Each gray value is represented in pure binary by either
83 1 or 2 bytes. If the Maxval is less than 256, it is 1 byte.
84 Otherwise, it is 2 bytes. The most significant byte is first.
85 .sp
86 A row of an image is horizontal. A column is vertical. The pixels
87 in the image are square and contiguous.
88 .sp
89 Each gray value is a number proportional to the intensity of the
90 pixel, adjusted by the ITU-R Recommendation BT.709 gamma transfer
91 function. (That transfer function specifies a gamma number of 2.2 and
92 has a linear section for small intensities). A value of zero is
93 therefore black. A value of Maxval represents CIE D65 white and the
94 most intense value in the image and any other image to which the image
95 might be compared.
96 .sp
97 BT.709's range of channel values (16-240) is irrelevant to PGM.
98 .sp
99 Note that a common variation from the PGM format is to have the
100 gray value be "linear," i.e. as specified above except
101 without the gamma adjustment. \fBpnmgamma\fP takes such a PGM
102 variant as input and produces a true PGM as output.
103 .sp
104 Another popular variation from PGM is to substitute the newer sRGB transfer
105 function for the BT.709 one. You can use \fBpnmgamma\fP to convert between
106 this variation and true PGM.
107 .sp
108 In the transparency mask variation from PGM, the value represents
109 opaqueness. It is proportional to the fraction of intensity of a
110 pixel that would show in place of an underlying pixel. So what
111 normally means white represents total opaqueness and what normally
112 means black represents total transparency. In between, you would
113 compute the intensity of a composite pixel of an "under" and
114 "over" pixel as under * (1-(alpha/alpha_maxval)) + over *
115 (alpha/alpha_maxval). Note that there is no gamma transfer function
116 in the transparency mask.
117
118
119 .PP
120 Strings starting with "#" may be comments, the same as
121 with
122 .BR "PBM" (1)\c
123 \&.
124 .PP
125 Note that you can use \fBpamdepth\fP to convert between the format with 1
126 byte per gray value and the one with 2 bytes per gray value.
127 .PP
128 All characters referred to herein are encoded in ASCII.
129 "newline" refers to the character known in ASCII as Line
130 Feed or LF. A "white space" character is space, CR, LF,
131 TAB, VT, or FF (I.e. what the ANSI standard C isspace() function
132 calls white space).
133
134 .UN minimal
135 .SS Minimal Subset
136 .PP
137 The PGM format is so simple that many programmers write programs to process
138 it directly, without using a library such as \fBlibnetpbm\fP, reverse
139 engineering a subset of the format from examples rather than using the
140 specification. Therefore, if you want to produce an image that as many
141 programs as possible can read, you should stick to the following subset.
142 .PP
143 The image consists of the following bytes:
144
145 .IP \(bu
146 \&'P5' followed by newline
147 .IP \(bu
148 width and height separated by a space (e.g. '50 100'),
149 followed by newline
150 .IP \(bu
151 maxval, followed by newline. At most 255; even more minimally, 255
152 exactly.
153 .IP \(bu
154 The raster
155
156 .PP
157 There is only one image in the file.
158 .PP
159 The program \fBpnmtopnm\fP produces this minimal subset, so if you have a
160 more complex PGM image, you can pass it to to a less tolerant program
161 through \fBpnmtopnm\fP. \fBpamdepth\fP can make the maxval 255.
162
163
164 .UN plainpgm
165 .SS Plain PGM
166 .PP
167 There is actually another version of the PGM format that is fairly
168 rare: "plain" PGM format. The format above, which generally
169 considered the normal one, is known as the "raw" PGM format.
170 See
171 .BR "pbm" (1)\c
172 \& for some commentary on how plain
173 and raw formats relate to one another and how to use them.
174 .PP
175 The difference in the plain format is:
176
177
178 .IP \(bu
179 There is exactly one image in a file.
180 .IP \(bu
181 The magic number is P2 instead of P5.
182 .IP \(bu
183 Each pixel in the raster is represented as an ASCII decimal number
184 (of arbitrary size).
185 .IP \(bu
186 Each pixel in the raster has white space before and after it. There must
187 be at least one character of white space between any two pixels, but there
188 is no maximum.
189 .IP \(bu
190 No line should be longer than 70 characters.
191
192 .PP
193 Here is an example of a small image in the plain PGM format.
194
195 .nf
196 P2
197 # feep.pgm
198 24 7
199 15
200 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
201 0 3 3 3 3 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 15 15 15 0
202 0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 15 0
203 0 3 3 3 0 0 0 7 7 7 0 0 0 11 11 11 0 0 0 15 15 15 15 0
204 0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 0 0
205 0 3 0 0 0 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 0 0 0 0
206 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
207
208 .fi
209 .PP
210 There is a newline character at the end of each of these lines.
211 .PP
212 Programs that read this format should be as lenient as possible,
213 accepting anything that looks remotely like a PGM image.
214
215
216 .UN internetmediatype
217 .SH INTERNET MEDIA TYPE
218 .PP
219 No Internet Media Type (aka MIME type, content type) for PGM has been
220 registered with IANA, but the value \f(CWimage/x-portable-graymap\fP
221 is conventional.
222 .PP
223 Note that the PNM Internet Media Type \f(CWimage/x-portable-anymap\fP
224 also applies.
225
226
227 .UN filename
228 .SH FILE NAME
229 .PP
230 There are no requirements on the name of a PGM file, but the convention is
231 to use the suffix ".pgm". "pnm" is also conventional, for
232 cases where distinguishing between the particular subformats of PNM is not
233 convenient.
234
235
236 .UN compatibility
237 .SH COMPATIBILITY
238 .PP
239 Before April 2000, a raw format PGM file could not have a maxval greater
240 than 255. Hence, it could not have more than one byte per sample. Old
241 programs may depend on this.
242 .PP
243 Before July 2000, there could be at most one image in a PGM file. As
244 a result, most tools to process PGM files ignore (and don't read) any
245 data after the first image.
246
247 .UN seealso
248 .SH SEE ALSO
249 .BR "pnm" (1)\c
250 \&,
251 .BR "pbm" (1)\c
252 \&,
253 .BR "ppm" (1)\c
254 \&,
255 .BR "pam" (1)\c
256 \&,
257 .BR "libnetpbm" (1)\c
258 \&,
259 .BR "programs that process PGM" (1)\c
260 \&
261
262 .UN author
263 .SH AUTHOR
264
265 Copyright (C) 1989, 1991 by Jef Poskanzer.
266 .SH DOCUMENT SOURCE
267 This manual page was generated by the Netpbm tool 'makeman' from HTML
268 source. The master documentation is at
269 .IP
270 .B http://netpbm.sourceforge.net/doc/pgm.html
271 .PP