1Libnetpbm Image Processing MLainburaalr(y3)FunctionLsibMnaentupablm Image Processing Manual(3)
2
6 libnetpbm_ug - netpbm sample code
7
10 The Libnetpbm programming library is part of Netpbm(1).
11
14 •
15 Example ⟨#example⟩
17 •
19 libnetpbm Classes ⟨#classes⟩
21 •
23 Library Initialization classes ⟨#initialization⟩
25 •
27 The pam Structure ⟨#pamstruct⟩
29 •
31 Plain versus Raw Format ⟨#plainvsraw⟩
33 •
35 Reference ⟨#reference⟩
37
41 Here is an example of a C program that uses libnetpbm to read a Netpbm
42 image input and produce a Netpbm image output.
43 /* Example program fragment to read a PAM or PNM image
45 from stdin, add up the values of every sample in it
46 (I don't know why), and write the image unchanged to
47 stdout. */
48 #include <netpbm/pam.h>
50 struct pam inpam, outpam;
52 tuple * tuplerow;
53 unsigned int row;
54 pm_init(argv[0], 0);
56 pnm_readpaminit(stdin, &inpam, PAM_STRUCT_SIZE(tuple_type));
58 outpam = inpam; outpam.file = stdout;
60 pnm_writepaminit(&outpam);
62 tuplerow = pnm_allocpamrow(&inpam);
64 for (row = 0; row < inpam.height; ++row) {
66 unsigned int column;
67 pnm_readpamrow(&inpam, tuplerow);
68 for (column = 0; column < inpam.width; ++column) {
69 unsigned int plane;
70 for (plane = 0; plane < inpam.depth; ++plane) {
71 grand_total += tuplerow[column][plane];
72 }
73 }
74 pnm_writepamrow(&outpam, tuplerow);
75 }
76 pnm_freepamrow(tuplerow);
77
82 In this section, Guide To Using Libnetpbm, we cover only the PAM func‐
83 tions in libnetpbm. As described in the introduction to libnetpbm"
84 (1), there are four other classes of image processing functions (PBM,
85 PGM, PPM, PNM). They are less important, since you can do everything
86 more easily with the PAM functions, but if you're working on old pro‐
87 grams or need the extra efficiency those older functions can sometimes
88 provide, you can find them documented as here: PBM Function Manual(1),
89 PGM Function Manual(1), PPM Function Manual(1), and PNM Function Man‐
90 ual(1).
91 In case you're wondering, what makes the PAM functions easier to use
93 is:
94 • Each function handles all the formats. It does so without con‐
97 verting to a common format, so your program can treat the dif‐
98 ferent formats differently if it wants. However, the interface
99 makes it easy for your program to ignore the differences between
100 the formats if that's what you want.
101 • The PAM function parameter lists convey most information about
104 the image with which you're working with a single pam structure,
105 which you can build once and use over and over, whereas the
106 older functions require you to pass up to 5 pieces of image in‐
107 formation (height, width, etc.) as separate arguments to every
108 function.
109
114 Every program that uses the library must initialize the library, i.e.
115 set up the process to use the library, as described in Initialization
116 ⟨libpm.html#initialization⟩ . That is the purpose of the call to
117 pm_init() in the example above.
118
122 The PAM functions take most of their arguments in the form of a single
123 pam structure. This is not an opaque object, but just a convenient way
124 to organize the information upon which most the functions depend. So
125 you are free to access or set the elements of the structure however you
126 want. But you will find in most cases it is most convenient to call
127 pnm_readpaminit() or pnm_writepaminit() to set the members in the pam
128 structure before calling any other pam functions, and then just to pass
129 the structure unchanged in all future calls to pam functions.
130 It depends upon the function to which you pass the structure what mem‐
132 bers are inputs, what members are outputs, and what members are irrele‐
133 vant.
134 It is possible for a pam structure not to specify some members, by op‐
136 eration of its len member. When you supply a pam structure as an argu‐
137 ment to a function, the function has default behavior defined for un‐
138 specified members. All the functions require that you specify at least
139 up through maxval, and some require more.
140 Likewise, a function the returns a pam structure can return only a sub‐
142 set of the members defined here, according to its setting of the len
143 member. But this normally happens only because the library is old and
144 predates the existence of the omitted members.
145 The members are:
147 size The storage size in bytes of this entire structure.
151 len The length, in bytes, of the information in this structure. The
154 information starts in the first byte and is contiguous. This
155 cannot be greater than size. size and len can be used to make
156 programs compatible with newer and older versions of the Netpbm
157 libraries.
158 file The file.
161 format The format code of the image, which tells which of the various
164 Netpbm image formats is being processed. The following macros
165 stand for those format codes:
166 PAM_FORMAT
171 PAM
172 RPBM_FORMAT
175 raw PBM format
176 RPGM_FORMAT
179 raw PGM format
180 RPPM_FORMAT
183 raw PPM format
184 PBM_FORMAT
187 plain PBM format
188 PGM_FORMAT
191 plain PGM format
192 PPM_FORMAT
195 plain PPM format
196 There is an important quirk in the meaning of this member when
200 you use the pam structure to write an image: Only the type por‐
201 tion of it is meaningful. A Netpbm format code conveys two
202 pieces of information: The format type (PBM, PGM, PPM, or PAM)
203 and the plainness (plain PBM vs raw PBM, etc.). But when writ‐
204 ing, libnetpbm ignores the plainness part and instead takes the
205 plainness from the plainformat member. So PBM_FORMAT and
206 RPBM_FORMAT are identical when writing.
207 This quirk exists for historical purposes; it's necessary for
209 consistency with the older functions such as pnm_writepnmrow()
210 whose format and forceplain arguments are analogous.
211 Before Netpbm 10.32 (February 2006), libnetpbm did not ignore
213 the plainness. This caused many programs to behave poorly, pro‐
214 ducing plain format output when they should, for backward com‐
215 patibility at the very least, produce raw format output.
216 A common way to use this member is to copy it and the plainfor‐
218 mat member from a pam for an input image to a pam for an output
219 image. When you do that, your output image will be raw format
220 regardless of whether your input image was plain or raw, and
221 this is the conventional behavior of Netpbm programs.
222 plainformat
225 This is a boolean value (0 = false, 1 = true), meaningful only
226 when writing an image file. It means to write in the plain
227 (text) version of the format indicated by format as opposed to
228 the raw (binary) version. Note that the format code in format
229 would appear to completely specify the format, making plainfor‐
230 mat redundant. But see the description of format for why that
231 isn't true.
232 Until Netpbm 10.32 (February 2006), this was defined a little
234 differently. The format member did in fact completely identify
235 the format and plainformat was redundant and existed as a sepa‐
236 rate member only for computational speed. But this was incon‐
237 sistent with the older libnetpbm interface (e.g. pnm_writepnm(),
238 and it made it difficult to write backward compatible programs.
239 Before Netpbm 10.32, it affected reading as well as writing.
240 libnetpbm image reading functions set this member to false, for
242 your convenience in building an output image pam from an input
243 image pam.
244 height The height of the image in rows.
247 width The width of the image in number of columns (tuples per row).
250 depth The depth of the image (degree of or number of samples in each
253 tuple).
254 maxval The maxval of the image. See definitions in pam(1).
257 bytes_per_sample
260 The number of bytes used to represent each sample in the image
261 file. See the format definition in pam(1). This is entirely
262 redundant with maxval. It exists as a separate member for com‐
263 putational speed.
264 tuple_type
267 The tuple type of the image. See definitions in pam(1). Netpbm
268 defines values for the most common types of visual images, but
269 any value is legal. There are macros for these values:
270 PAM_PBM_TUPLETYPE
274 black and white image, such as would alternatively be repre‐
275 sented by a PBM image.
276 PAM_PGM_TUPLETYPE
278 grayscale image, such as would alternatively be represented by a
279 PGM image.
280 PAM_PPM_TUPLETYPE
282 color image, such as would alternatively be represented by a PPM
283 image.
284 PAM_PBM_ALPHA_TUPLETYPE
286 black and white with a transparency (alpha) information.
287 PAM_PGM_ALPHA_TUPLETYPE
289 grayscale with a transparency (alpha) information.
290 PAM_PPM_ALPHA_TUPLETYPE
292 color with a transparency (alpha) information.
293 allocation_depth
297 The number of samples for which memory is allocated for any tu‐
298 ple associated with this PAM structure. This must be at least
299 as great as 'depth'. Only the first 'depth' of the samples of a
300 tuple are meaningful.
301 The purpose of this is to make it possible for a program to
303 change the type of a tuple to one with more or fewer planes.
304 0 means the allocation depth is the same as the image depth.
306 comment_p
309 Pointer to a pointer to a NUL-terminated ASCII string of com‐
310 ments. When reading an image, this contains the comments from
311 the image's PAM header; when writing, the image gets these as
312 comments, right after the magic number line. The individual
313 comments are delimited by newlines and are in the same order as
314 in the PAM header. The "#" at the beginning of a PAM header
315 line that indicates the line is a comment is not part of the
316 comment.
317 On output, NULL means no comments.
319 On input, libnetpbm mallocs storage for the comments and placed
321 the pointer at *comment_p. Caller must free it. NULL means
322 libnetpbm does not return comments and does not allocate any
323 storage.
324 Examples:
326 const char * comments;
328 ...
329 pam.comment_p = &comments;
330 pnm_readpaminit(fileP, &pam, PAM_STRUCT_SIZE(comment_p));
331 printf("The comments are:\n");
332 printf("%s", comments)
333 free(comments);
334 const char * comments;
337 ...
338 comments = strdup("This is a comment 1\nThis is comment 2\n");
339 pam.comment_p = &comments;
340 pnm_writepaminit(&pam);
341 free(comments);
342 This works only for PAM images. If you read a PNM image, you
345 always get back a null string. If you write a PNM image, you
346 always get an image that contains no comments.
347 This member does not exist before Netpbm 10.35 (August 2006).
349 Before that, there is no way with libnetpbm to get or set com‐
350 ments. The macro PAM_HAVE_COMMENT_P is defined in pam.h where
351 the member exists.
352
359 The PNM formats each come in two varieties: the older plain (text) for‐
360 mat and the newer raw (binary) format. There are different format
361 codes for the plain and raw formats, but which of the two formats the
362 pnm and pam functions write is independent of the format code you pass
363 to them.
364 The pam functions always write raw formats. If you specify the format
366 code for a plain format, a pam function assumes instead the raw version
367 of that format.
368 The pnm functions choose between plain and raw based on the forceplain
370 parameter that every write-type pnm function has. If this boolean
371 value is true, the function writes the plain version of the format
372 specified by the format code. If it is false, the function writes the
373 raw version of the format specified by the format code.
374 We are trying to stamp out the older plain formats, so it would be a
376 wise choice not to write a program that sets forceplain true under any
377 circumstance. A user who needs a plain format can use the pnmto‐
378 plainpnm program to convert the output of your program to plain format.
379
382 The Libnetpbm Netpbm Image Processing Manual" (1) describes the lib‐
383 netpbm functions for processing image data.
384 The Libnetpbm Utility Manual(1) describes the functions that are not
386 specifically related to the Netpbm image formats.
387
389 This manual page was generated by the Netpbm tool 'makeman' from HTML
390 source. The master documentation is at
391 http://netpbm.sourceforge.net/doc/libnetpbm_ug.html
393netpbm documentation Libnetpbm Image Processing Manual(3)