Debian Codegraph @

upstream/debian-trixie/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 "09 October 2016" "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 plainpgm
135 .SS Plain PGM
136 .PP
137 There is actually another version of the PGM format that is fairly
138 rare: "plain" PGM format. The format above, which generally
139 considered the normal one, is known as the "raw" PGM format.
140 See
141 .BR "pbm" (1)\c
142 \& for some commentary on how plain
143 and raw formats relate to one another and how to use them.
144 .PP
145 The difference in the plain format is:
146
147
148 .IP \(bu
149 There is exactly one image in a file.
150 .IP \(bu
151 The magic number is P2 instead of P5.
152 .IP \(bu
153 Each pixel in the raster is represented as an ASCII decimal number
154 (of arbitrary size).
155 .IP \(bu
156 Each pixel in the raster has white space before and after it. There must
157 be at least one character of white space between any two pixels, but there
158 is no maximum.
159 .IP \(bu
160 No line should be longer than 70 characters.
161
162 .PP
163 Here is an example of a small image in the plain PGM format.
164
165 .nf
166 P2
167 # feep.pgm
168 24 7
169 15
170 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
171 0 3 3 3 3 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 15 15 15 0
172 0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 15 0
173 0 3 3 3 0 0 0 7 7 7 0 0 0 11 11 11 0 0 0 15 15 15 15 0
174 0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 0 0
175 0 3 0 0 0 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 0 0 0 0
176 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
177
178 .fi
179 .PP
180 There is a newline character at the end of each of these lines.
181 .PP
182 Programs that read this format should be as lenient as possible,
183 accepting anything that looks remotely like a PGM image.
184
185
186 .UN internetmediatype
187 .SH INTERNET MEDIA TYPE
188 .PP
189 No Internet Media Type (aka MIME type, content type) for PGM has been
190 registered with IANA, but the value \f(CWimage/x-portable-graymap\fP
191 is conventional.
192 .PP
193 Note that the PNM Internet Media Type \f(CWimage/x-portable-anymap\fP
194 also applies.
195
196
197 .UN filename
198 .SH FILE NAME
199 .PP
200 There are no requirements on the name of a PGM file, but the convention is
201 to use the suffix ".pgm". "pnm" is also conventional, for
202 cases where distinguishing between the particular subformats of PNM is not
203 convenient.
204
205
206 .UN compatibility
207 .SH COMPATIBILITY
208 .PP
209 Before April 2000, a raw format PGM file could not have a maxval greater
210 than 255. Hence, it could not have more than one byte per sample. Old
211 programs may depend on this.
212 .PP
213 Before July 2000, there could be at most one image in a PGM file. As
214 a result, most tools to process PGM files ignore (and don't read) any
215 data after the first image.
216
217 .UN seealso
218 .SH SEE ALSO
219 .BR "pnm" (1)\c
220 \&,
221 .BR "pbm" (1)\c
222 \&,
223 .BR "ppm" (1)\c
224 \&,
225 .BR "pam" (1)\c
226 \&,
227 .BR "libnetpbm" (1)\c
228 \&,
229 .BR "programs that process PGM" (1)\c
230 \&
231
232 .UN author
233 .SH AUTHOR
234
235 Copyright (C) 1989, 1991 by Jef Poskanzer.
236 .SH DOCUMENT SOURCE
237 This manual page was generated by the Netpbm tool 'makeman' from HTML
238 source. The master documentation is at
239 .IP
240 .B http://netpbm.sourceforge.net/doc/pgm.html
241 .PP