| 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 "PPM Format Specification" 5 "07 November 2025" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
|
| 10 |
PPM - Netpbm color 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 PPM format is a lowest common denominator color image file |
| 20 |
format. |
| 21 |
.PP |
| 22 |
It should be noted that this format is egregiously inefficient. |
| 23 |
It is highly redundant, while containing a lot of information that the |
| 24 |
human eye can't even discern. Furthermore, the format allows very |
| 25 |
little information about the image besides basic color, which means |
| 26 |
you may have to couple a file in this format with other independent |
| 27 |
information to get any decent use out of it. However, it is very easy |
| 28 |
to write and analyze programs to process this format, and that is the |
| 29 |
point. |
| 30 |
.PP |
| 31 |
It should also be noted that files often conform to this format in |
| 32 |
every respect except the precise semantics of the sample values. |
| 33 |
These files are useful because of the way PPM is used as an |
| 34 |
intermediary format. They are informally called PPM files, but to be |
| 35 |
absolutely precise, you should indicate the variation from true PPM. |
| 36 |
For example, "PPM using the red, green, and blue colors that the |
| 37 |
scanner in question uses." |
| 38 |
.PP |
| 39 |
The name "PPM" is an acronym derived from "Portable Pixel Map." |
| 40 |
Images in this format (or a precursor of it) were once also called |
| 41 |
"portable pixmaps." |
| 42 |
|
| 43 |
.UN format |
| 44 |
.SH THE FORMAT |
| 45 |
.PP |
| 46 |
The format definition is as follows. You can use the |
| 47 |
.BR "libnetpbm" (1)\c |
| 48 |
\& C subroutine library to read and |
| 49 |
interpret the format conveniently and accurately. |
| 50 |
.PP |
| 51 |
A PPM file consists of a sequence of one or more PPM images. There are |
| 52 |
no data, delimiters, or padding before, after, or between images. |
| 53 |
.PP |
| 54 |
Each PPM image consists of the following: |
| 55 |
|
| 56 |
|
| 57 |
.IP \(bu |
| 58 |
A "magic number" for identifying the file type. |
| 59 |
A ppm image's magic number is the two characters "P6". |
| 60 |
.IP \(bu |
| 61 |
Whitespace (blanks, TABs, CRs, LFs). |
| 62 |
.IP \(bu |
| 63 |
A width, formatted as ASCII characters in decimal. |
| 64 |
.IP \(bu |
| 65 |
Whitespace. |
| 66 |
.IP \(bu |
| 67 |
A height, again in ASCII decimal. |
| 68 |
.IP \(bu |
| 69 |
Whitespace. |
| 70 |
.IP \(bu |
| 71 |
The maximum color value (Maxval), again in ASCII decimal. Must be less |
| 72 |
than 65536 and more than zero. |
| 73 |
|
| 74 |
.IP \(bu |
| 75 |
A single whitespace character (usually a newline). |
| 76 |
|
| 77 |
.IP \(bu |
| 78 |
A raster of Height rows, in order from top to bottom. Each row |
| 79 |
consists of Width pixels, in order from left to right. Each pixel is |
| 80 |
a triplet of red, green, and blue samples, in that order. Each sample |
| 81 |
is represented in pure binary by either 1 or 2 bytes. If the Maxval |
| 82 |
is less than 256, it is 1 byte. Otherwise, it is 2 bytes. The most |
| 83 |
significant byte is first. |
| 84 |
.sp |
| 85 |
A row of an image is horizontal. A column is vertical. The pixels |
| 86 |
in the image are square and contiguous. |
| 87 |
.sp |
| 88 |
In the raster, the sample values are "nonlinear." They are |
| 89 |
proportional to the intensity of the ITU-R Recommendation BT.709 red, |
| 90 |
green, and blue in the pixel, adjusted by the 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 Maxval for |
| 93 |
all three samples represents CIE D65 white and the most intense color |
| 94 |
in the color universe of which the image is part (the color universe |
| 95 |
is all the colors in all images to which this image might be |
| 96 |
compared). |
| 97 |
.sp |
| 98 |
BT.709's range of channel values (16-240) is irrelevant to PPM. |
| 99 |
.sp |
| 100 |
ITU-R Recommendation BT.709 is a renaming of the former CCIR |
| 101 |
Recommendation 709. When CCIR was absorbed into its parent |
| 102 |
organization, the ITU, ca. 2000, the standard was renamed. This |
| 103 |
document once referred to the standard as CIE Rec. 709, but it isn't |
| 104 |
clear now that CIE ever sponsored such a standard. |
| 105 |
.sp |
| 106 |
Note that another popular color space is the newer sRGB. A common |
| 107 |
variation from PPM is to substitute this color space for the one specified. |
| 108 |
You can use \fBpnmgamma\fP to convert between this variation and true PPM. |
| 109 |
.sp |
| 110 |
Note that a common variation from the PPM format is to have the sample |
| 111 |
values be "linear," i.e. as specified above except without |
| 112 |
the gamma adjustment. \fBpnmgamma\fP takes such a PPM variant as |
| 113 |
input and produces a true PPM as output. |
| 114 |
|
| 115 |
|
| 116 |
.PP |
| 117 |
Strings starting with "#" may be comments, the same as |
| 118 |
with |
| 119 |
.BR "PBM" (1)\c |
| 120 |
\&. |
| 121 |
.PP |
| 122 |
Note that you can use \fBpamdepth\fP to convert between the format with 1 |
| 123 |
byte per sample and the one with 2 bytes per sample. |
| 124 |
.PP |
| 125 |
All characters referred to herein are encoded in ASCII. |
| 126 |
"newline" refers to the character known in ASCII as Line |
| 127 |
Feed or LF. A "white space" character is space, CR, LF, |
| 128 |
TAB, VT, or FF (I.e. what the ANSI standard C isspace() function |
| 129 |
calls white space). |
| 130 |
|
| 131 |
.UN minimal |
| 132 |
.SS Minimal Subset |
| 133 |
.PP |
| 134 |
The PPM format is so simple that many programmers write programs to process |
| 135 |
it directly, without using a library such as \fBlibnetpbm\fP, reverse |
| 136 |
engineering a subset of the format from examples rather than using the |
| 137 |
specification. Therefore, if you want to produce an image that as many |
| 138 |
programs as possible can read, you should stick to the following subset. |
| 139 |
.PP |
| 140 |
The image consists of the following bytes: |
| 141 |
|
| 142 |
.IP \(bu |
| 143 |
\&'P6' followed by newline |
| 144 |
.IP \(bu |
| 145 |
width and height separated by a space (e.g. '50 100'), |
| 146 |
followed by newline |
| 147 |
.IP \(bu |
| 148 |
maxval, followed by newline. At most 255; even more minimally, 255 |
| 149 |
exactly. |
| 150 |
.IP \(bu |
| 151 |
The raster |
| 152 |
|
| 153 |
.PP |
| 154 |
There is only one image in the file. |
| 155 |
.PP |
| 156 |
The program \fBpnmtopnm\fP produces this minimal subset, so if you have a |
| 157 |
more complex PGM image, you can pass it to to a less tolerant program |
| 158 |
through \fBpnmtopnm\fP. \fBpamdepth\fP can make the maxval 255. |
| 159 |
|
| 160 |
|
| 161 |
.UN plainppm |
| 162 |
.SS Plain PPM |
| 163 |
.PP |
| 164 |
There is actually another version of the PPM format that is fairly |
| 165 |
rare: "plain" PPM format. The format above, which generally |
| 166 |
considered the normal one, is known as the "raw" PPM format. |
| 167 |
See |
| 168 |
.BR "\fBpbm\fP " (1)\c |
| 169 |
\& for some commentary on how plain |
| 170 |
and raw formats relate to one another and how to use them. |
| 171 |
.PP |
| 172 |
The difference in the plain format is: |
| 173 |
|
| 174 |
|
| 175 |
.IP \(bu |
| 176 |
There is exactly one image in a file. |
| 177 |
.IP \(bu |
| 178 |
The magic number is P3 instead of P6. |
| 179 |
.IP \(bu |
| 180 |
Each sample in the raster is represented as an ASCII decimal number |
| 181 |
(of arbitrary size). |
| 182 |
.IP \(bu |
| 183 |
Each sample in the raster has white space before and after it. There must |
| 184 |
be at least one character of white space between any two samples, but there |
| 185 |
is no maximum. There is no particular separation of one pixel from another -- |
| 186 |
just the required separation between the blue sample of one pixel from the |
| 187 |
red sample of the next pixel. |
| 188 |
.IP \(bu |
| 189 |
No line should be longer than 70 characters. |
| 190 |
|
| 191 |
.PP |
| 192 |
Here is an example of a small image in this format. |
| 193 |
.nf |
| 194 |
P3 |
| 195 |
# feep.ppm |
| 196 |
4 4 |
| 197 |
15 |
| 198 |
0 0 0 0 0 0 0 0 0 15 0 15 |
| 199 |
0 0 0 0 15 7 0 0 0 0 0 0 |
| 200 |
0 0 0 0 0 0 0 15 7 0 0 0 |
| 201 |
15 0 15 0 0 0 0 0 0 0 0 0 |
| 202 |
|
| 203 |
.fi |
| 204 |
.PP |
| 205 |
There is a newline character at the end of each of these lines. |
| 206 |
.PP |
| 207 |
Programs that read this format should be as lenient as possible, |
| 208 |
accepting anything that looks remotely like a PPM image. |
| 209 |
|
| 210 |
|
| 211 |
.UN internetmediatype |
| 212 |
.SH INTERNET MEDIA TYPE |
| 213 |
.PP |
| 214 |
No Internet Media Type (aka MIME type, content type) for PPM has been |
| 215 |
registered with IANA, but the value \f(CWimage/x-portable-pixmap\fP is |
| 216 |
conventional. |
| 217 |
.PP |
| 218 |
Note that the PNM Internet Media Type \f(CWimage/x-portable-anymap\fP |
| 219 |
also applies. |
| 220 |
|
| 221 |
|
| 222 |
.UN filename |
| 223 |
.SH FILE NAME |
| 224 |
.PP |
| 225 |
There are no requirements on the name of a PPM file, but the convention is |
| 226 |
to use the suffix ".ppm". "pnm" is also conventional, for |
| 227 |
cases where distinguishing between the particular subformats of PNM is not |
| 228 |
convenient. |
| 229 |
|
| 230 |
|
| 231 |
.UN compatibility |
| 232 |
.SH COMPATIBILITY |
| 233 |
.PP |
| 234 |
Before April 2000, a raw format PPM file could not have a maxval greater |
| 235 |
than 255. Hence, it could not have more than one byte per sample. Old |
| 236 |
programs may depend on this. |
| 237 |
.PP |
| 238 |
Before July 2000, there could be at most one image in a PPM file. As |
| 239 |
a result, most tools to process PPM files ignore (and don't read) any |
| 240 |
data after the first image. |
| 241 |
|
| 242 |
.UN seealso |
| 243 |
.SH SEE ALSO |
| 244 |
.BR "pnm" (1)\c |
| 245 |
\&, |
| 246 |
.BR "pgm" (1)\c |
| 247 |
\&, |
| 248 |
.BR "pbm" (1)\c |
| 249 |
\&, |
| 250 |
.BR "pam" (1)\c |
| 251 |
\&, |
| 252 |
.BR "programs that process PPM" (1)\c |
| 253 |
\& |
| 254 |
.SH DOCUMENT SOURCE |
| 255 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 256 |
source. The master documentation is at |
| 257 |
.IP |
| 258 |
.B http://netpbm.sourceforge.net/doc/ppm.html |
| 259 |
.PP |