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

COMPATIBILITY

159       Before April 2000, a raw format  PGM  file  could  not  have  a  maxval
160       greater than 255.  Hence, it could not have more than one byte per sam‐
161       ple.  Old programs may depend on this.
162
163       Before July 2000, there could be at most one image in a PGM file.  As a
164       result,  most  tools  to  process PGM files ignore (and don't read) any
165       data after the first image.
166
167

SEE ALSO

169       pnm(1),  pbm(1),   ppm(1),   pam(1),   libnetpbm(1),   programsthatpro‐
170       cessPGM(1),
171
172

AUTHOR

174       Copyright (C) 1989, 1991 by Jef Poskanzer.
175
176
177
178netpbm documentation            03 October 2003    PGM Format Specification(5)