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
81 In this section, Guide To Using Libnetpbm, we cover only the PAM func‐
82 tions in libnetpbm. As described in the introduction to libnetpbm"
83 (1), there are four other classes of image processing functions (PBM,
84 PGM, PPM, PNM). They are less important, since you can do everything
85 more easily with the PAM functions, but if you're working on old pro‐
86 grams or need the extra efficiency those older functions can sometimes
87 provide, you can find them documented as here: PBM Function Manual(1),
88 PGM Function Manual(1), PPM Function Manual(1), and PNM Function Man‐
89 ual(1).
90 In case you're wondering, what makes the PAM functions easier to use
92 is:
93 · Each function handles all the formats. It does so without con‐
96 verting to a common format, so your program can treat the dif‐
97 ferent formats differently if it wants. However, the interface
98 makes it easy for your program to ignore the differences between
99 the formats if that's what you want.
100 · The PAM function parameter lists convey most information about
103 the image with which you're working with a single pam structure,
104 which you can build once and use over and over, whereas the
105 older functions require you to pass up to 5 pieces of image
106 information (height, width, etc.) as separate arguments to every
107 function.
108
113 Every program that uses the library must initialize the library, i.e.
114 set up the process to use the library, as described in Initialization
115 ⟨libpm.html#initialization⟩ . That is the purpose of the call to
116 pm_init() in the example above.
117
121 The PAM functions take most of their arguments in the form of a single
122 pam structure. This is not an opaque object, but just a convenient way
123 to organize the information upon which most the functions depend. So
124 you are free to access or set the elements of the structure however you
125 want. But you will find in most cases it is most convenient to call
126 pnm_readpaminit() or pnm_writepaminit() to set the members in the pam
127 structure before calling any other pam functions, and then just to pass
128 the structure unchanged in all future calls to pam functions.
129 It depends upon the function to which you pass the structure what mem‐
131 bers are inputs, what members are outputs, and what members are irrele‐
132 vant.
133 It is possible for a pam structure not to specify some members, by
135 operation of its len member. When you supply a pam structure as an
136 argument to a function, the function has default behavior defined for
137 unspecified members. All the functions require that you specify at
138 least up through maxval, and some require more.
139 Likewise, a function the returns a pam structure can return only a sub‐
141 set of the members defined here, according to its setting of the len
142 member. But this normally happens only because the library is old and
143 predates the existence of the omitted members.
144 The members are:
146 size The storage size in bytes of this entire structure.
150 len The length, in bytes, of the information in this structure. The
153 information starts in the first byte and is contiguous. This
154 cannot be greater than size. size and len can be used to make
155 programs compatible with newer and older versions of the Netpbm
156 libraries.
157 file The file.
160 format The format code of the image, which tells which of the various
163 Netpbm image formats is being processed. The following macros
164 stand for those format codes:
165 PAM_FORMAT
170 PAM
171 RPBM_FORMAT
174 raw PBM format
175 RPGM_FORMAT
178 raw PGM format
179 RPPM_FORMAT
182 raw PPM format
183 PBM_FORMAT
186 plain PBM format
187 PGM_FORMAT
190 plain PGM format
191 PPM_FORMAT
194 plain PPM format
195 There is an important quirk in the meaning of this member when
199 you use the pam structure to write an image: Only the type por‐
200 tion of it is meaningful. A Netpbm format code conveys two
201 pieces of information: The format type (PBM, PGM, PPM, or PAM)
202 and the plainness (plain PBM vs raw PBM, etc.). But when writ‐
203 ing, libnetpbm ignores the plainness part and instead takes the
204 plainness from the plainformat member. So PBM_FORMAT and
205 RPBM_FORMAT are identical when writing.
206 This quirk exists for historical purposes; it's necessary for
208 consistency with the older functions such as pnm_writepnmrow()
209 whose format and forceplain arguments are analogous.
210 Before Netpbm 10.32 (February 2006), libnetpbm did not ignore
212 the plainness. This caused many programs to behave poorly, pro‐
213 ducing plain format output when they should, for backward com‐
214 patibility at the very least, produce raw format output.
215 A common way to use this member is to copy it and the plainfor‐
217 mat member from a pam for an input image to a pam for an output
218 image. When you do that, your output image will be raw format
219 regardless of whether your input image was plain or raw, and
220 this is the conventional behavior of Netpbm programs.
221 plainformat
224 This is a boolean value (0 = false, 1 = true), meaningful only
225 when writing an image file. It means to write in the plain
226 (text) version of the format indicated by format as opposed to
227 the raw (binary) version. Note that the format code in format
228 would appear to completely specify the format, making plainfor‐
229 mat redundant. But see the description of format for why that
230 isn't true.
231 Until Netpbm 10.32 (February 2006), this was defined a little
233 differently. The format member did in fact completely identify
234 the format and plainformat was redundant and existed as a sepa‐
235 rate member only for computational speed. But this was incon‐
236 sistent with the older libnetpbm interface (e.g. pnm_writepnm(),
237 and it made it difficult to write backward compatible programs.
238 Before Netpbm 10.32, it affected reading as well as writing.
239 libnetpbm image reading functions set this member to false, for
241 your convenience in building an output image pam from an input
242 image pam.
243 height The height of the image in rows.
246 width The width of the image in number of columns (tuples per row).
249 depth The depth of the image (degree of or number of samples in each
252 tuple).
253 maxval The maxval of the image. See definitions in pam(1).
256 bytes_per_sample
259 The number of bytes used to represent each sample in the image
260 file. See the format definition in pam(1). This is entirely
261 redundant with maxval. It exists as a separate member for com‐
262 putational speed.
263 tuple_type
266 The tuple type of the image. See definitions in pam(1). Netpbm
267 defines values for the most common types of visual images, but
268 any value is legal. There are macros for these values:
269 PAM_PBM_TUPLETYPE
273 black and white image, such as would alternatively be repre‐
274 sented by a PBM image.
275 PAM_PGM_TUPLETYPE
277 grayscale image, such as would alternatively be represented by a
278 PGM image.
279 PAM_PPM_TUPLETYPE
281 color image, such as would alternatively be represented by a PPM
282 image.
283 PAM_PBM_ALPHA_TUPLETYPE
285 black and white with a transparency (alpha) information.
286 PAM_PGM_ALPHA_TUPLETYPE
288 grayscale with a transparency (alpha) information.
289 PAM_PPM_ALPHA_TUPLETYPE
291 color with a transparency (alpha) information.
292 allocation_depth
296 The number of samples for which memory is allocated for any
297 tuple associated with this PAM structure. This must be at least
298 as great as 'depth'. Only the first 'depth' of the samples of a
299 tuple are meaningful.
300 The purpose of this is to make it possible for a program to
302 change the type of a tuple to one with more or fewer planes.
303 0 means the allocation depth is the same as the image depth.
305 comment_p
308 Pointer to a pointer to a NUL-terminated ASCII string of com‐
309 ments. When reading an image, this contains the comments from
310 the image's PAM header; when writing, the image gets these as
311 comments, right after the magic number line. The individual
312 comments are delimited by newlines and are in the same order as
313 in the PAM header. The "#" at the beginning of a PAM header
314 line that indicates the line is a comment is not part of the
315 comment.
316 On output, NULL means no comments.
318 On input, libnetpbm mallocs storage for the comments and placed
320 the pointer at *comment_p. Caller must free it. NULL means
321 libnetpbm does not return comments and does not allocate any
322 storage.
323 Examples:
325 const char * comments;
327 ...
328 pam.comment_p = &comments;
329 pnm_readpaminit(fileP, &pam, PAM_STRUCT_SIZE(comment_p));
330 printf("The comments are:\n");
331 printf("%s", comments)
332 free(comments);
333 const char * comments;
335 ...
336 comments = strdup("This is a comment 1\nThis is comment 2\n");
337 pam.comment_p = &comments;
338 pnm_writepaminit(&pam);
339 free(comments);
340 This works only for PAM images. If you read a PNM image, you
342 always get back a null string. If you write a PNM image, you
343 always get an image that contains no comments.
344 This member does not exist before Netpbm 10.35 (August 2006).
346 Before that, there is no way with libnetpbm to get or set com‐
347 ments. The macro PAM_HAVE_COMMENT_P is defined in pam.h where
348 the member exists.
349
356 The PNM formats each come in two varieties: the older plain (text) for‐
357 mat and the newer raw (binary) format. There are different format
358 codes for the plain and raw formats, but which of the two formats the
359 pnm and pam functions write is independent of the format code you pass
360 to them.
361 The pam functions always write raw formats. If you specify the format
363 code for a plain format, a pam function assumes instead the raw version
364 of that format.
365 The pnm functions choose between plain and raw based on the forceplain
367 parameter that every write-type pnm function has. If this boolean
368 value is true, the function writes the plain version of the format
369 specified by the format code. If it is false, the function writes the
370 raw version of the format specified by the format code.
371 We are trying to stamp out the older plain formats, so it would be a
373 wise choice not to write a program that sets forceplain true under any
374 circumstance. A user who needs a plain format can use the pnmto‐
375 plainpnm program to convert the output of your program to plain format.
376
379 The Libnetpbm Netpbm Image Processing Manual" (1) describes the lib‐
380 netpbm functions for processing image data.
381 The Libnetpbm Utility Manual(1) describes the functions that are not
383 specifically related to the Netpbm image formats.
384
386 This manual page was generated by the Netpbm tool 'makeman' from HTML
387 source. The master documentation is at
388 http://netpbm.sourceforge.net/doc/libnetpbm_ug.html
390netpbm documentation Libnetpbm Image Processing Manual(3)