Debian Codegraph @

upstream/debian-unstable/man5/pbm.5

raw
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