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