1PGM Format Specification(5)   File Formats Manual  PGM Format Specification(5)
2
3
4

NAME

6       pgm - Netpbm grayscale image format
7
8

DESCRIPTION

10       This program is part of Netpbm(1).
11
12       The  PGM  format  is a lowest common denominator grayscale file format.
13       It is designed to be extremely easy to learn and  write  programs  for.
14       (It's  so  simple  that most people will simply reverse engineer it be‐
15       cause it's easier than reading this specification).
16
17       A PGM image represents a  grayscale  graphic  image.   There  are  many
18       pseudo-PGM  formats  in use where everything is as specified herein ex‐
19       cept for the meaning of individual pixel values.  For most purposes,  a
20       PGM  image  can  just be thought of an array of arbitrary integers, and
21       all the programs in the world that think they're processing a grayscale
22       image can easily be tricked into processing something else.
23
24       The name "PGM" is an acronym derived from "Portable Gray Map."
25
26       One  official  variant of PGM is the transparency mask.  A transparency
27       mask in Netpbm is represented by a PGM image, except that in  place  of
28       pixel intensities, there are opaqueness values.  See below.
29
30

THE FORMAT

32       The  format  definition  is as follows.  You can use the libnetpbm(1) C
33       subroutine library to conveniently and accurately  read  and  interpret
34       the format.
35
36       A  PGM file consists of a sequence of one or more PGM images. There are
37       no data, delimiters, or padding before, after, or between images.
38
39       Each PGM image consists of the following:
40
41
42
43
44       •      A "magic number" for identifying the file type.  A  pgm  image's
45              magic number is the two characters "P5".
46
47
48       •      Whitespace (blanks, TABs, CRs, LFs).
49
50
51       •      A width, formatted as ASCII characters in decimal.
52
53
54       •      Whitespace.
55
56
57       •      A height, again in ASCII decimal.
58
59
60       •      Whitespace.
61
62
63       •      The  maximum  gray value (Maxval), again in ASCII decimal.  Must
64              be less than 65536, and more than zero.
65
66
67       •      A single whitespace character (usually a newline).
68
69
70       •      A raster of Height rows, in order from top to bottom.  Each  row
71              consists  of  Width  gray  values,  in order from left to right.
72              Each gray value is a number from 0 through Maxval, with 0  being
73              black and Maxval being white.  Each gray value is represented in
74              pure binary by either 1 or 2 bytes.  If the Maxval is less  than
75              256, it is 1 byte.  Otherwise, it is 2 bytes.  The most signifi‐
76              cant byte is first.
77
78              A row of an image is horizontal.  A  column  is  vertical.   The
79              pixels in the image are square and contiguous.
80
81              Each gray value is a number proportional to the intensity of the
82              pixel, adjusted by the ITU-R Recommendation BT.709 gamma  trans‐
83              fer  function.  (That transfer function specifies a gamma number
84              of 2.2 and has a linear section for small intensities).  A value
85              of  zero  is  therefore black.  A value of Maxval represents CIE
86              D65 white and the most intense value in the image and any  other
87              image to which the image might be compared.
88
89              BT.709's range of channel values (16-240) is irrelevant to PGM.
90
91              Note  that a common variation from the PGM format is to have the
92              gray value be "linear," i.e. as specified above  except  without
93              the  gamma adjustment.  pnmgamma takes such a PGM variant as in‐
94              put and produces a true PGM as output.
95
96              Another popular variation from PGM is to  substitute  the  newer
97              sRGB transfer function for the BT.709 one.  You can use pnmgamma
98              to convert between this variation and true PGM.
99
100              In the transparency mask variation from PGM,  the  value  repre‐
101              sents  opaqueness.  It is proportional to the fraction of inten‐
102              sity of a pixel that would show in place of an underlying pixel.
103              So  what  normally  means  white represents total opaqueness and
104              what normally means black represents total transparency.  In be‐
105              tween,  you  would compute the intensity of a composite pixel of
106              an "under" and "over" pixel as under *  (1-(alpha/alpha_maxval))
107              +  over  *  (alpha/alpha_maxval).   Note  that there is no gamma
108              transfer function in the transparency mask.
109
110
111
112       Strings starting with "#" may be comments, the same as with PBM(1).
113
114       Note that you can use pamdepth to convert between a the format  with  1
115       byte per gray value and the one with 2 bytes per gray value.
116
117       All  characters  referred  to  herein  are encoded in ASCII.  "newline"
118       refers to the character known in ASCII as Line Feed or  LF.   A  "white
119       space"  character  is space, CR, LF, TAB, VT, or FF (I.e. what the ANSI
120       standard C isspace() function calls white space).
121
122
123   Plain PGM
124       There is actually another version of the  PGM  format  that  is  fairly
125       rare: "plain" PGM format.  The format above, which generally considered
126       the normal one, is known as the "raw" PGM format.  See pbm(1) for  some
127       commentary  on  how plain and raw formats relate to one another and how
128       to use them.
129
130       The difference in the plain format is:
131
132
133
134
135
136              There is exactly one image in a file.
137
138
139
140              The magic number is P2 instead of P5.
141
142
143
144              Each pixel in the raster is represented as an ASCII decimal num‐
145              ber (of arbitrary size).
146
147
148
149              Each  pixel  in  the raster has white space before and after it.
150              There must be at least one character of white space between  any
151              two pixels, but there is no maximum.
152
153
154
155              No line should be longer than 70 characters.
156
157
158       Here is an example of a small image in the plain PGM format.
159
160       P2
161       # feep.pgm
162       24 7
163       15
164       0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
165       0  3  3  3  3  0  0  7  7  7  7  0  0 11 11 11 11  0  0 15 15 15 15  0
166       0  3  0  0  0  0  0  7  0  0  0  0  0 11  0  0  0  0  0 15  0  0 15  0
167       0  3  3  3  0  0  0  7  7  7  0  0  0 11 11 11  0  0  0 15 15 15 15  0
168       0  3  0  0  0  0  0  7  0  0  0  0  0 11  0  0  0  0  0 15  0  0  0  0
169       0  3  0  0  0  0  0  7  7  7  7  0  0 11 11 11 11  0  0 15  0  0  0  0
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
172
173       There is a newline character at the end of each of these lines.
174
175       Programs  that  read  this format should be as lenient as possible, ac‐
176       cepting anything that looks remotely like a PGM.
177
178
179

INTERNET MEDIA TYPE

181       No Internet Media Type (aka MIME type, content type) for PGM  has  been
182       registered with IANA, but the value image/x-portable-graymap is conven‐
183       tional.
184
185       Note that the PNM Internet Media Type image/x-portable-anymap also  ap‐
186       plies.
187
188
189

FILE NAME

191       There are no requirements on the name of a PGM file, but the convention
192       is to use the suffix ".pgm".  "pnm" is  also  conventional,  for  cases
193       where  distinguishing  between  the particular subformats of PNM is not
194       convenient.
195
196
197

COMPATIBILITY

199       Before April 2000, a raw format  PGM  file  could  not  have  a  maxval
200       greater than 255.  Hence, it could not have more than one byte per sam‐
201       ple.  Old programs may depend on this.
202
203       Before July 2000, there could be at most one image in a PGM file.  As a
204       result,  most  tools  to  process PGM files ignore (and don't read) any
205       data after the first image.
206
207

SEE ALSO

209       pnm(1), pbm(1), ppm(1), pam(1),  libnetpbm(1),  programs  that  process
210       PGM(1),
211
212

AUTHOR

214       Copyright (C) 1989, 1991 by Jef Poskanzer.
215

DOCUMENT SOURCE

217       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
218       source.  The master documentation is at
219
220              http://netpbm.sourceforge.net/doc/pgm.html
221
222netpbm documentation            09 October 2016    PGM Format Specification(5)
Impressum