Debian Codegraph @

upstream/debian-trixie/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 "27 June 2024" "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.
88 "newline" refers to the character known in ASCII as Line
89 Feed or LF. A "white space" character is space, CR, LF,
90 TAB, VT, or FF (I.e. what the ANSI standard C isspace() function
91 calls white space).
92
93
94 .UN plainpbm
95 .SS Plain PBM
96 .PP
97 There is actually another version of the PBM format, even more
98 simplistic, more lavishly wasteful of space than PBM, called Plain
99 PBM. Plain PBM actually came first, but even its inventor couldn't
100 stand its recklessly squanderous use of resources after a while and
101 switched to what we now know as the regular PBM format. But Plain PBM
102 is so redundant -- so overstated -- that it's virtually impossible to
103 break. You can send it through the most liberal mail system (which
104 was the original purpose of the PBM format) and it will arrive still
105 readable. You can flip a dozen random bits and easily piece back
106 together the original image. And we hardly need to define the format
107 here, because you can decode it by inspection.
108 .PP
109 Netpbm programs generate Raw PBM format instead of Plain PBM by
110 default, but the
111 .UR index.html#commonoptions
112 common option
113 .UE
114 \&
115 \fB-plain\fP chooses Plain PBM.
116 .PP
117 The difference is:
118
119 .IP \(bu
120 There is exactly one image in a file.
121 .IP \(bu
122 The "magic number" is "P1" instead of "P4".
123 .IP \(bu
124 Each pixel in the raster is represented by a byte containing ASCII '1' or '0',
125 representing black and white respectively. There are no fill bits at the
126 end of a row.
127 .IP \(bu
128 White space in the raster section is ignored.
129 .IP \(bu
130 You can put any junk you want after the raster, if it starts with a
131 white space character.
132 .IP \(bu
133 No line should be longer than 70 characters.
134
135
136 Here is an example of a small image in the plain PBM format.
137 .nf
138 P1
139 # feep.pbm
140 24 7
141 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
142 0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0
143 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 1 0
144 0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 1 0
145 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0
146 0 1 0 0 0 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 0 0 0 0
147 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
148
149 .fi
150 .PP
151 There is a newline character at the end of each of these lines.
152 .PP
153 You can generate the Plain PBM format from the regular PBM format
154 (first image in the file only) with the \fBpnmtoplainpnm\fP program.
155 .PP
156 Programs that read this format should be as lenient as possible,
157 accepting anything that looks remotely like a bitmap.
158
159
160 .UN internetmediatype
161 .SH INTERNET MEDIA TYPE
162 .PP
163 No Internet Media Type (aka MIME type, content type) for PBM has been
164 registered with IANA, but the value \f(CWimage/x-portable-bitmap\fP
165 is conventional.
166 .PP
167 Note that the PNM Internet Media Type \f(CWimage/x-portable-anymap\fP
168 also applies.
169
170
171 .UN filename
172 .SH FILE NAME
173 .PP
174 There are no requirements on the name of a PBM file, but the convention is
175 to use the suffix ".pbm". "pnm" is also conventional, for
176 cases where distinguishing between the particular subformats of PNM is not
177 convenient.
178
179
180 .UN compatibility
181 .SH COMPATIBILITY
182 .PP
183 Before July 2000, there could be at most one image in a PBM file. As
184 a result, most tools to process PBM files ignore (and don't read) any
185 data after the first image.
186
187 .UN seealso
188 .SH SEE ALSO
189 .BR "libnetpbm" (1)\c
190 \&,
191 .BR "pnm" (1)\c
192 \&,
193 .BR "pgm" (1)\c
194 \&,
195 .BR "ppm" (1)\c
196 \&,
197 .BR "pam" (1)\c
198 \&,
199 .BR "programs that process PBM" (1)\c
200 \&
201 .SH DOCUMENT SOURCE
202 This manual page was generated by the Netpbm tool 'makeman' from HTML
203 source. The master documentation is at
204 .IP
205 .B http://netpbm.sourceforge.net/doc/pbm.html
206 .PP