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 Here is an example of a C program that uses libnetpbm to read a Netpbm
15 image input and produce a Netpbm image output.
16 /* Example program fragment to read a PAM or PNM image
18 from stdin, add up the values of every sample in it
19 (I don't know why), and write the image unchanged to
20 stdout. */
21 #include <netpbm/pam.h>
23 struct pam inpam, outpam;
25 tuple * tuplerow;
26 unsigned int row;
27 pm_init(argv[0], 0);
29 pnm_readpaminit(stdin, &inpam, PAM_STRUCT_SIZE(tuple_type));
31 outpam = inpam; outpam.file = stdout;
33 pnm_writepaminit(&outpam);
35 tuplerow = pnm_allocpamrow(&inpam);
37 for (row = 0; row < inpam.height; row++) {
39 unsigned int column;
40 pnm_readpamrow(&inpam, tuplerow);
41 for (column = 0; column < inpam.width; ++column) {
42 unsigned int plane;
43 for (plane = 0; plane < inpam.depth; ++plane) {
44 grand_total += tuplerow[column][plane];
45 }
46 }
47 pnm_writepamrow(&outpam, tuplerow); }
48 pnm_freepamrow(tuplerow);
50
54 libnetpbm classes
55 In this section, we cover only the PAM functions in libnetpbm. As
56 described in the introduction to libnetpbm (1), there are four other
57 classes of image processing functions (PBM, PGM, PPM, PNM). They are
58 less important, since you can do everything more easily with the PAM
59 functions, but if you're working on old programs or need the extra
60 efficiency those older functions can sometimes provide, you can find
61 them documented as here: PBMFunctionManual(1), PGMFunctionManual(1),
62 PPMFunctionManual(1),and PNMFunctionManual(1).
63 In case you're wondering, what makes the PAM functions easier to use
65 is:
66 · Each function handles all the formats. It does so without con‐
69 verting to a common format, so your program can treat the dif‐
70 ferent formats differently if it wants. However, the interface
71 makes it easy for your program to ignore the differences between
72 the formats if that's what you want.
73 · The PAM function parameter lists convey most information about
76 the image with which you're working with a single pam structure,
77 which you can build once and use over and over, whereas the
78 older functions require you to pass up to 5 pieces of image
79 information (height, width, etc.) as separate arguments to every
80 function.
81 THE pam STRUCTURE
85 The PAM functions take most of their arguments in the form of a single
86 pam structure. This is not an opaque object, but just a convenient way
87 to organize the information upon which most the functions depend. So
88 you are free to access or set the elements of the structure however you
89 want. But you will find in most cases it is most convenient to call
90 pnm_readpaminit() or pnm_writepaminit() to set the fields in the pam
91 structure before calling any other pam functions, and then just to pass
92 the structure unchanged in all future calls to pam functions.
93 The fields are:
95 size The storage size in bytes of this entire structure.
99 len The length, in bytes, of the information in this structure. The
102 information starts in the first byte and is contiguous. This
103 cannot be greater than size. size and len can be used to make
104 programs compatible with newer and older versions of the Netpbm
105 libraries.
106 file The file.
109 format The format code of the image. This is PAM_FORMAT unless the PAM
112 image is really a view of a PBM, PGM, or PPM image. Then it's
113 PBM_FORMAT, RPBM_FORMAT, etc.
114 There is an important quirk in the meaning of this member when
116 you use the pam structure to write an image: Only the type por‐
117 tion of it is meaningful. A Netpbm format code conveys two
118 pieces of information: The format type (PBM, PGM, PPM, or PAM)
119 and the plainness (plain PBM vs raw PBM, etc.). But when writ‐
120 ing, libnetpbm ignores the plainness part and instead takes the
121 plainness from the plainformat member. So PBM_FORMAT and
122 RPBM_FORMAT are identical when writing.
123 This quirk exists for historical purposes; it's necessary for
125 consistency with the older functions such as pnm_writepnmrow()
126 whose format and forceplain arguments are analogous.
127 Before Netpbm 10.32 (February 2006), libnetpbm did not ignore
129 the plainness. This caused many programs to behave poorly, pro‐
130 ducing plain format output when they should, for backward com‐
131 patibility at the very least, produce raw format output.
132 A common way to use this member is to copy it and the plainfor‐
134 mat member from a pam for an input image to a pam for an output
135 image. When you do that, your output image will be raw format
136 regardless of whether your input image was plain or raw, and
137 this is the conventional behavior of Netpbm programs.
138 plainformat
141 This is a boolean value (0 = false, 1 = true), meaningful only
142 when writing an image file. It means to write in the plain
143 (text) version of the format indicated by format as oppposed to
144 the raw (binary) version. Note that the format code in format
145 would appear to completely specify the format, making plainfor‐
146 mat redundant. But see the description of format for why that
147 isn't true.
148 Until Netpbm 10.32 (Februrary 2006), this was defined a little
150 differently. The format member did in fact completely identify
151 the format and plainformat was redundant and existed as a sepa‐
152 rate member only for computational speed. But this was incon‐
153 sistent with the older libnetpbm interface (e.g. pnm_writepnm(),
154 and it made it difficult to write backward compatible programs.
155 Before Netpbm 10.32, it affected reading as well as writing.
156 libnetpbm image reading functions set this field to false, for
158 your convenience in building an output image pam from an input
159 image pam.
160 height The height of the image in rows.
163 width The width of the image in number of columns (tuples per row).
166 depth The depth of the image (degree of or number of samples in each
169 tuple).
170 maxval The maxval of the image. See definitions in pam(1).
173 bytes_per_sample
176 The number of bytes used to represent each sample in the image
177 file. See the format definition in pam(1).This is entirely
178 redundant with maxval. It exists as a separate member for com‐
179 putational speed.
180 tuple_type
183 The tuple type of the image. See definitions in pam(1).Netpbm‐
184 doesnotdefineanyvaluesforthis except the following, which are
185 used for a PAM image which is really a view of a PBM, PGM, or
186 PPM image: PAM_PBM_TUPLETYPE, PAM_PGM_TUPLETYPE, PAM_PPM_TUPLE‐
187 TYPE.
188 allocation_depth
191 The number of samples for which memory is allocated for any
192 tuple associated with this PAM structure. This must be at least
193 as great as 'depth'. Only the first 'depth' of the samples of a
194 tuple are meaningful.
195 The purpose of this is to make it possible for a program to
197 change the type of a tuple to one with more or fewer planes.
198 0 means the allocation depth is the same as the image depth.
200 comment_p
203 Pointer to a pointer to a NUL-terminated ASCII string of com‐
204 ments. When reading an image, this contains the comments from
205 the image's PAM header; when writing, the image gets these as
206 comments, right after the magic number line. The individual
207 comments are delimited by newlines and are in the same order as
208 in the PAM header. The '#' at the beginning of a PAM header
209 line that indicates the line is a comment is not part of the
210 comment.
211 On output, NULL means no comments.
213 On input, libnetpbm mallocs storage for the comments and placed
215 the pointer at *comment_p. Caller must free it. NULL means
216 libnetpbm does not return comments and does not allocate any
217 storage.
218 Examples:
220 <code>
222 const char * comments;
223 ...
224 pam.comment_p = &comments;
225 pnm_readpaminit(fileP, &pam, PAM_STRUCT_SIZE(comment_p));
226 printf('The comments are:0);
227 printf('%s', comments)
228 free(comments);
229 </code>
230 <code>
232 const char * comments;
233 ...
234 comments = strdup('This is a comment 10his is comment 20);
235 pam.comment_p = &comments;
236 pnm_writepaminit(&pam);
237 free(comments);
238 </code>
239 This works only for PAM images. If you read a PNM image, you
241 always get back a null string. If you write a PNM image, you
242 always get an image that contains no comments.
243 This member does not exist before Netpbm 10.35 (August 2006).
245 Before that, there is no way with libnetpbm to get or set com‐
246 ments. The macro PAM_HAVE_COMMENT_P is defined in pam.h where
247 the member exists.
248 PLAIN VERSUS RAW FORMAT
255 The PNM formats each come in two varieties: the older plain (text) for‐
256 mat and the newer raw (binary) format. There are different format
257 codes for the plain and raw formats, but which of the two formats the
258 pnm and pam functions write is independent of the format code you pass
259 to them.
260 The pam functions always write raw formats. If you specify the format
262 code for a plain format, a pam function assumes instead the raw version
263 of that format.
264 The pnm functions choose between plain and raw based on the forceplain
266 parameter that every write-type pnm function has. If this boolean
267 value is true, the function writes the plain version of the format
268 specified by the format code. If it is false, the function writes the
269 raw version of the format specified by the format code.
270 We are trying to stamp out the older plain formats, so it would be a
272 wise choice not to write a program that sets forceplain true under any
273 circumstance. A user who needs a plain format can use the pnmto‐
274 plainpnm program to convert the output of your program to plain format.
275 Reference
278 The LibnetpbmNetpbmImage Processing Manual (1) describes the the lib‐
279 netpbm functions for processing image data.
280 The LibnetpbmUtilityManual(1) describes the functions that are not
282 specifically related to the Netpbm image formats.
283netpbm documentation Libnetpbm Image Processing Manual(3)