1Libnetpbm Image Processing MLainburaalr(y3)FunctionLsibMnaentupablm Image Processing Manual(3)
2
3
4

NAME

6       libnetpbm_ug - netpbm sample code
7
8

DESCRIPTION

10       The Libnetpbm programming library is part of Netpbm(1).
11
12

Example

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
17          /* 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
22          #include <netpbm/pam.h>
23
24          struct pam inpam, outpam;
25          tuple * tuplerow;
26          unsigned int row;
27
28          pm_init(argv[0], 0);
29
30          pnm_readpaminit(stdin, &inpam, PAM_STRUCT_SIZE(tuple_type));
31
32          outpam = inpam; outpam.file = stdout;
33
34          pnm_writepaminit(&outpam);
35
36          tuplerow = pnm_allocpamrow(&inpam);
37
38          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
49          pnm_freepamrow(tuplerow);
50
51
52

Guide To Using Libnetpbm

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
64       In  case  you're  wondering, what makes the PAM functions easier to use
65       is:
66
67
68       ·      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
74
75       ·      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
82
83
84   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
94       The fields are:
95
96
97
98       size   The storage size in bytes of this entire structure.
99
100
101       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
107
108       file   The file.
109
110
111       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
115              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
124              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
128              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
133              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
139
140       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
149              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
157              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
161
162       height The height of the image in rows.
163
164
165       width  The width of the image in number of columns (tuples per row).
166
167
168       depth  The depth of the image (degree of or number of samples  in  each
169              tuple).
170
171
172       maxval The maxval of the image.  See definitions in pam(1).
173
174
175       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
181
182       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
189
190       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
196              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
199              0 means the allocation depth is the same as the image depth.
200
201
202       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
212              On output, NULL means no comments.
213
214              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
219              Examples:
220
221                  const char * comments;
222                  ...
223                  pam.comment_p = &comments;
224                  pnm_readpaminit(fileP, &pam, PAM_STRUCT_SIZE(comment_p));
225                  printf('The comments are:\n');
226                  printf('%s', comments)
227                  free(comments);
228
229                  const char * comments;
230                  ...
231                  comments = strdup('This is a comment 1\nThis is comment 2\n');
232                  pam.comment_p = &comments;
233                  pnm_writepaminit(&pam);
234                  free(comments);
235
236              This works only for PAM images.  If you read a  PNM  image,  you
237              always  get  back  a null string.  If you write a PNM image, you
238              always get an image that contains no comments.
239
240              This member does not exist before Netpbm  10.35  (August  2006).
241              Before  that,  there is no way with libnetpbm to get or set com‐
242              ments.  The macro PAM_HAVE_COMMENT_P is defined in  pam.h  where
243              the member exists.
244
245
246
247
248
249
250   PLAIN VERSUS RAW FORMAT
251       The PNM formats each come in two varieties: the older plain (text) for‐
252       mat and the newer raw (binary)  format.   There  are  different  format
253       codes  for  the plain and raw formats, but which of the two formats the
254       pnm and pam functions write is independent of the format code you  pass
255       to them.
256
257       The  pam functions always write raw formats.  If you specify the format
258       code for a plain format, a pam function assumes instead the raw version
259       of that format.
260
261       The  pnm functions choose between plain and raw based on the forceplain
262       parameter that every write-type pnm  function  has.   If  this  boolean
263       value  is  true,  the  function  writes the plain version of the format
264       specified by the format code.  If it is false, the function writes  the
265       raw version of the format specified by the format code.
266
267       We  are  trying  to stamp out the older plain formats, so it would be a
268       wise choice not to write a program that sets forceplain true under  any
269       circumstance.   A  user  who  needs  a  plain format can use the pnmto‐
270       plainpnm program to convert the output of your program to plain format.
271
272
273   Reference
274       The LibnetpbmNetpbmImage Processing Manual (1) describes the  the  lib‐
275       netpbm functions for processing image data.
276
277       The  LibnetpbmUtilityManual(1)  describes  the  functions  that are not
278       specifically related to the Netpbm image formats.
279
280
281
282netpbm documentation                      Libnetpbm Image Processing Manual(3)
Impressum