| 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 "The PBM Format" 5 "07 November 2025" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
|
| 10 |
pbm - Netpbm bi-level 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 PBM format is a lowest common denominator monochrome file |
| 20 |
format. It serves as the common language of a large family of bitmap |
| 21 |
image conversion filters. Because the format pays no heed to |
| 22 |
efficiency, it is simple and general enough that one can easily |
| 23 |
develop programs to convert to and from just about any other graphics |
| 24 |
format, or to manipulate the image. |
| 25 |
.PP |
| 26 |
The name "PBM" is an acronym derived from "Portable Bit Map." |
| 27 |
.PP |
| 28 |
This is not a format that one would normally use to store a file |
| 29 |
or to transmit it to someone -- it's too expensive and not expressive |
| 30 |
enough for that. It's just an intermediary format. In it's purest |
| 31 |
use, it lives only in a pipe between two other programs. |
| 32 |
|
| 33 |
.UN layout |
| 34 |
.SH THE LAYOUT |
| 35 |
.PP |
| 36 |
The format definition is as follows. |
| 37 |
.PP |
| 38 |
A PBM file consists of a sequence of one or more PBM images. There are |
| 39 |
no data, delimiters, or padding before, after, or between images. |
| 40 |
.PP |
| 41 |
Each PBM image consists of the following: |
| 42 |
|
| 43 |
|
| 44 |
|
| 45 |
.IP \(bu |
| 46 |
A "magic number" for identifying the file type. |
| 47 |
A pbm image's magic number is the two characters "P4". |
| 48 |
|
| 49 |
.IP \(bu |
| 50 |
Whitespace (blanks, TABs, CRs, LFs). |
| 51 |
|
| 52 |
.IP \(bu |
| 53 |
The width in pixels of the image, formatted as ASCII characters in decimal. |
| 54 |
|
| 55 |
.IP \(bu |
| 56 |
Whitespace. |
| 57 |
|
| 58 |
.IP \(bu |
| 59 |
The height in pixels of the image, again in ASCII decimal. |
| 60 |
|
| 61 |
.IP \(bu |
| 62 |
A single whitespace character (usually a newline). |
| 63 |
|
| 64 |
.IP \(bu |
| 65 |
A raster of Height rows, in order from top to bottom. Each row is |
| 66 |
Width bits, packed 8 to a byte, with don't care bits to fill out the |
| 67 |
last byte in the row. Each bit represents a pixel: 1 is black, 0 is |
| 68 |
white. The order of the pixels is left to right. The order of their |
| 69 |
storage within each file byte is most significant bit to least |
| 70 |
significant bit. The order of the file bytes is from the beginning of |
| 71 |
the file toward the end of the file. |
| 72 |
.sp |
| 73 |
A row of an image is horizontal. A column is vertical. The pixels |
| 74 |
in the image are square and contiguous. |
| 75 |
|
| 76 |
.IP \(bu |
| 77 |
Before the whitespace character that delimits the raster, any |
| 78 |
characters from a "#" to but not including the next carriage return or |
| 79 |
newline character, or end of file, is a comment and is ignored. |
| 80 |
.sp |
| 81 |
(Before June 2024, the carriage return or line feed was specified to be |
| 82 |
part of the comment and ignored, but in the 22 years that comments had |
| 83 |
existed in the specification, Netpbm never implemented that). |
| 84 |
|
| 85 |
|
| 86 |
.PP |
| 87 |
All characters referred to herein are encoded in ASCII. "newline" refers |
| 88 |
to the character known in ASCII as Line Feed or LF. A "white space" character |
| 89 |
is space, CR, LF, TAB, VT, or FF (I.e. what the ANSI standard C isspace() |
| 90 |
function calls white space). |
| 91 |
|
| 92 |
.UN minimal |
| 93 |
.SS Minimal Subset |
| 94 |
.PP |
| 95 |
The PBM format is so simple that many programmers write programs to process |
| 96 |
it directly, without using a library such as \fBlibnetpbm\fP, reverse |
| 97 |
engineering a subset of the format from examples rather than using the |
| 98 |
specification. Therefore, if you want to produce an image that as many |
| 99 |
programs as possible can read, you should stick to the following subset. |
| 100 |
.PP |
| 101 |
The image consists of the following bytes: |
| 102 |
|
| 103 |
.IP \(bu |
| 104 |
\&'P4' followed by newline |
| 105 |
.IP \(bu |
| 106 |
width and height separated by a space (e.g. '50 100'), |
| 107 |
followed by newline |
| 108 |
.IP \(bu |
| 109 |
The raster |
| 110 |
|
| 111 |
.PP |
| 112 |
There is only one image in the file. |
| 113 |
.PP |
| 114 |
The program \fBpnmtopnm\fP produces this minimal subset, so if you have a |
| 115 |
more complex PBM image, you can pass it to to a less tolerant program |
| 116 |
through \fBpnmtopnm\fP. |
| 117 |
|
| 118 |
|
| 119 |
.UN plainpbm |
| 120 |
.SS Plain PBM |
| 121 |
.PP |
| 122 |
There is actually another version of the PBM format, even more |
| 123 |
simplistic, more lavishly wasteful of space than PBM, called Plain |
| 124 |
PBM. Plain PBM actually came first, but even its inventor couldn't |
| 125 |
stand its recklessly squanderous use of resources after a while and |
| 126 |
switched to what we now know as the regular PBM format. But Plain PBM |
| 127 |
is so redundant -- so overstated -- that it's virtually impossible to |
| 128 |
break. You can send it through the most liberal mail system (which |
| 129 |
was the original purpose of the PBM format) and it will arrive still |
| 130 |
readable. You can flip a dozen random bits and easily piece back |
| 131 |
together the original image. And we hardly need to define the format |
| 132 |
here, because you can decode it by inspection. |
| 133 |
.PP |
| 134 |
Netpbm programs generate Raw PBM format instead of Plain PBM by |
| 135 |
default, but the |
| 136 |
.UR index.html#commonoptions |
| 137 |
common option |
| 138 |
.UE |
| 139 |
\& |
| 140 |
\fB-plain\fP chooses Plain PBM. |
| 141 |
.PP |
| 142 |
The difference is: |
| 143 |
|
| 144 |
.IP \(bu |
| 145 |
There is exactly one image in a file. |
| 146 |
.IP \(bu |
| 147 |
The "magic number" is "P1" instead of "P4". |
| 148 |
.IP \(bu |
| 149 |
Each pixel in the raster is represented by a byte containing ASCII '1' or '0', |
| 150 |
representing black and white respectively. There are no fill bits at the |
| 151 |
end of a row. |
| 152 |
.IP \(bu |
| 153 |
White space in the raster section is ignored. |
| 154 |
.IP \(bu |
| 155 |
You can put any junk you want after the raster, if it starts with a |
| 156 |
white space character. |
| 157 |
.IP \(bu |
| 158 |
No line should be longer than 70 characters. |
| 159 |
|
| 160 |
|
| 161 |
Here is an example of a small image in the plain PBM format. |
| 162 |
.nf |
| 163 |
P1 |
| 164 |
# feep.pbm |
| 165 |
24 7 |
| 166 |
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 |
| 167 |
0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0 |
| 168 |
0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 1 0 |
| 169 |
0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 1 0 |
| 170 |
0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 |
| 171 |
0 1 0 0 0 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 0 0 0 0 |
| 172 |
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 |
| 173 |
|
| 174 |
.fi |
| 175 |
.PP |
| 176 |
There is a newline character at the end of each of these lines. |
| 177 |
.PP |
| 178 |
You can generate the Plain PBM format from the regular PBM format |
| 179 |
(first image in the file only) with the \fBpnmtoplainpnm\fP program. |
| 180 |
.PP |
| 181 |
Programs that read this format should be as lenient as possible, |
| 182 |
accepting anything that looks remotely like a bitmap. |
| 183 |
|
| 184 |
|
| 185 |
.UN internetmediatype |
| 186 |
.SH INTERNET MEDIA TYPE |
| 187 |
.PP |
| 188 |
No Internet Media Type (aka MIME type, content type) for PBM has been |
| 189 |
registered with IANA, but the value \f(CWimage/x-portable-bitmap\fP |
| 190 |
is conventional. |
| 191 |
.PP |
| 192 |
Note that the PNM Internet Media Type \f(CWimage/x-portable-anymap\fP |
| 193 |
also applies. |
| 194 |
|
| 195 |
|
| 196 |
.UN filename |
| 197 |
.SH FILE NAME |
| 198 |
.PP |
| 199 |
There are no requirements on the name of a PBM file, but the convention is |
| 200 |
to use the suffix ".pbm". "pnm" is also conventional, for |
| 201 |
cases where distinguishing between the particular subformats of PNM is not |
| 202 |
convenient. |
| 203 |
|
| 204 |
|
| 205 |
.UN compatibility |
| 206 |
.SH COMPATIBILITY |
| 207 |
.PP |
| 208 |
Before July 2000, there could be at most one image in a PBM file. As |
| 209 |
a result, most tools to process PBM files ignore (and don't read) any |
| 210 |
data after the first image. |
| 211 |
|
| 212 |
.UN seealso |
| 213 |
.SH SEE ALSO |
| 214 |
.BR "libnetpbm" (1)\c |
| 215 |
\&, |
| 216 |
.BR "pnm" (1)\c |
| 217 |
\&, |
| 218 |
.BR "pgm" (1)\c |
| 219 |
\&, |
| 220 |
.BR "ppm" (1)\c |
| 221 |
\&, |
| 222 |
.BR "pam" (1)\c |
| 223 |
\&, |
| 224 |
.BR "programs that process PBM" (1)\c |
| 225 |
\& |
| 226 |
.SH DOCUMENT SOURCE |
| 227 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 228 |
source. The master documentation is at |
| 229 |
.IP |
| 230 |
.B http://netpbm.sourceforge.net/doc/pbm.html |
| 231 |
.PP |