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
15       because 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
19       except for the meaning of individual pixel values.  For most  purposes,
20       a  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
94              input 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
105              between, 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       There is a newline character at the end of each of these lines.
173
174       Programs  that  read  this  format  should  be  as lenient as possible,
175       accepting anything that looks remotely like a PGM.
176
177
178

INTERNET MEDIA TYPE

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

FILE NAME

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

COMPATIBILITY

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

SEE ALSO

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

AUTHOR

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

DOCUMENT SOURCE

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