diff options
Diffstat (limited to 'libnetpbm_ug.html')
| -rw-r--r-- | libnetpbm_ug.html | 303 |
1 files changed, 303 insertions, 0 deletions
diff --git a/libnetpbm_ug.html b/libnetpbm_ug.html new file mode 100644 index 00000000..6eb3081b --- /dev/null +++ b/libnetpbm_ug.html @@ -0,0 +1,303 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> +<HEAD> +<TITLE>Libnetpbm Image Processing Manual</TITLE> +<META NAME="manual_section" CONTENT="3"> +</HEAD> +<BODY> +<H1>Libnetpbm User's Guide</H1> +<?makeman .SH NAME ?> +<?makeman libnetpbm_ug \- netpbm sample code ?> + +<p>The Libnetpbm programming library is part of <a +href="index.html">Netpbm</a>. + +<H2>Example</H2> + +<p>Here is an example of a C program that uses <b>libnetpbm</b> to read a +Netpbm image input and produce a Netpbm image output. + +<pre> + /* Example program fragment to read a PAM or PNM image + from stdin, add up the values of every sample in it + (I don't know why), and write the image unchanged to + stdout. */ + + #include <pam.h> + + struct pam inpam, outpam; + unsigned int row; + + pnm_init(&argc, argv); + + pnm_readpaminit(stdin, &inpam, PAM_STRUCT_SIZE(tuple_type)); + + outpam = inpam; outpam.file = stdout; + + pnm_writepaminit(&outpam); + + tuplerow = pnm_allocpamrow(&inpam); + + for (row = 0; row < inpam.height; row++) { + unsigned int column; + pnm_readpamrow(&inpam, tuplerow); + for (column = 0; column < inpam.width; ++column) { + unsigned int plane; + for (plane = 0; plane < inpam.depth; ++plane) { + grand_total += tuplerow[column][plane]; + } + } + pnm_writepamrow(&outpam, tuplerow); } + + pnm_freepamrow(tuplerow); + +</pre> + +<H2>Guide To Using Libnetpbm</H2> + +<h3><b>libnetpbm classes</b></h3> + +<p>In this section, we cover only the PAM functions in +<b>libnetpbm</b>. As described in <a href="libnetpbm.html">the +introduction to <b>libnetpbm</b></a>, there are four other classes of +image processing functions (PBM, PGM, PPM, PNM). They are less +important, since you can do everything more easily with the PAM +functions, but if you're working on old programs or need the extra +efficiency those older functions can sometimes provide, you can find +them documented as here: <a href="libpbm.html">PBM Function Manual</a>, +<a href="libpgm.html">PGM Function Manual</a>,<a +href="libppm.html">PPM Function Manual</a>, and <a +href="libpnm.html">PNM Function Manual</a>. + +<p>In case you're wondering, what makes the PAM functions easier to use +is: +<ul> +<li>Each function handles all the formats. It does so without converting +to a common format, so your program can treat the different formats +differently if it wants. However, the interface makes it easy for your +program to ignore the differences between the formats if that's what you +want. + +<li>The PAM function parameter lists convey most information about the +image with which you're working with a single <b>pam</b> structure, +which you can build once and use over and over, whereas the older +functions require you to pass up to 5 pieces of image information +(height, width, etc.) as separate arguments to every function. +</ul> + +<H3 id="pamstruct">THE pam STRUCTURE</H3> + +<P>The PAM functions take most of their arguments in the form of a +single <B>pam</B> structure. This is not an opaque object, but just a +convenient way to organize the information upon which most the +functions depend. So you are free to access or set the elements of +the structure however you want. But you will find in most cases it is +most convenient to call <B>pnm_readpaminit()</B> or +<B>pnm_writepaminit()</B> to set the fields in the <B>pam</B> +structure before calling any other pam functions, and then just to +pass the structure unchanged in all future calls to pam functions. + +<P>The fields are: + +<DL COMPACT> +<DT><B>size</B> +<DD> +The storage size in bytes of this entire structure. + +<DT><B>len</B> + +<DD>The length, in bytes, of the information in this structure. The +information starts in the first byte and is contiguous. This cannot +be greater than <B>size</B>. <B>size</B> and <B>len</B> can be used +to make programs compatible with newer and older versions of the +Netpbm libraries. + +<DT><B>file</B> + +<DD>The file. + +<DT><B>format</B> + +<DD>The format code of the image. This is <B>PAM_FORMAT</B> +unless the PAM image is really a view of a PBM, PGM, or PPM image. +Then it's <B>PBM_FORMAT</B>, <B>RPBM_FORMAT</B>, etc. +<p> +There is an important quirk in the meaning of this member when you use +the pam structure to write an image: Only the type portion of it is +meaningful. A Netpbm format code conveys two pieces of information: +The format type (PBM, PGM, PPM, or PAM) and the plainness (plain PBM +vs raw PBM, etc.). But when writing, <b>libnetpbm</b> ignores the +plainness part and instead takes the plainness from the +<b>plainformat</b> member. So <B>PBM_FORMAT</B> and +<B>RPBM_FORMAT</B> are identical when writing. +<p> +This quirk exists for historical purposes; it's necessary for consistency +with the older functions such as <b>pnm_writepnmrow()</b> whose +<i>format</i> and <i>forceplain</i> arguments are analogous. +<p> +Before Netpbm 10.32 (February 2006), <b>libnetpbm</b> did not ignore the +plainness. This caused many programs to behave poorly, producing plain +format output when they should, for backward compatibility at the very +least, produce raw format output. +<p> +A common way to use this member is to copy it and the +<b>plainformat</b> member from a pam for an input image to a pam for +an output image. When you do that, your output image will be raw +format regardless of whether your input image was plain or raw, and +this is the conventional behavior of Netpbm programs. + +<DT><B>plainformat</B> + +<DD>This is a boolean value (0 = false, 1 = true), meaningful only +when writing an image file. It means to write in the plain (text) +version of the format indicated by <b>format</b> as oppposed to the +raw (binary) version. Note that the format code in <b>format</b> +would appear to completely specify the format, making +<b>plainformat</b> redundant. But see the description of +<b>format</b> for why that isn't true. +<p> +Until Netpbm 10.32 (Februrary 2006), this was defined a little differently. +The <b>format</b> member did in fact completely identify the format and +<b>plainformat</b> was redundant and existed as a separate member only +for computational speed. But this was inconsistent with the older +<b>libnetpbm</b> interface (e.g. <b>pnm_writepnm()</b>, and it made it +difficult to write backward compatible programs. Before Netpbm 10.32, +it affected reading as well as writing. +<p> +<b>libnetpbm</b> image reading functions set this field to false, for your +convenience in building an output image pam from an input image pam. + +<DT><B>height</B> + +<DD>The height of the image in rows. + +<DT><B>width</B> + +<DD>The width of the image in number of columns (tuples per row). + +<DT><B>depth</B> + +<DD>The depth of the image (degree of or number of samples in each tuple). + +<DT><B>maxval</B> + +<DD>The maxval of the image. See definitions in <A HREF="pam.html">pam</A>. + +<DT><B>bytes_per_sample</B> + +<DD>The number of bytes used to represent each sample in the image +file. See the format definition in <A HREF="pam.html">pam</A>. This +is entirely redundant with <B>maxval</B>. It exists as a separate +member for computational speed. + +<DT><B>tuple_type</B> + +<DD>The tuple type of the image. See definitions in <A +HREF="pam.html">pam</A>. Netpbm does not define any values for this +except the following, which are used for a PAM image which is really a +view of a PBM, PGM, or PPM image: <B>PAM_PBM_TUPLETYPE</B>, +<B>PAM_PGM_TUPLETYPE</B>, <B>PAM_PPM_TUPLETYPE</B>. + +<DT><B>allocation_depth</B> + +<dd>The number of samples for which memory is allocated for any tuple +associated with this PAM structure. This must be at least as great as +'depth'. Only the first 'depth' of the samples of a tuple are +meaningful. + +<p>The purpose of this is to make it possible for a program to change +the type of a tuple to one with more or fewer planes. + +<p>0 means the allocation depth is the same as the image depth. + +<dt><b>comments_p</b> + +<dd>Pointer to a pointer to a NUL-terminated ASCII string of comments. +When reading an image, this contains the comments from the image's PAM +header; when writing, the image gets these as comments, right after +the magic number line. The individual comments are delimited by +newlines and are in the same order as in the PAM header. The "#" +at the beginning of a PAM header line that indicates the line is a comment +is not part of the comment. + +<p>On output, NULL means no comments. + +<p>On input, libnetpbm mallocs storage for the comments and placed the +pointer at *comment_p. Caller must free it. NULL means libnetpbm +does not return comments and does not allocate any storage. + +<p>Examples: + +<pre> +<code> + const char * comments; + ... + pam.comment_p = &comments; + pnm_readpaminit(fileP, &pam, PAM_STRUCT_SIZE(comment_p)); + printf("The comments are:\n"); + printf("%s", comments) + free(comments); +</code> +</pre> + +<pre> +<code> + const char * comments; + ... + comments = strdup("This is a comment 1\nThis is comment 2\n"); + pam.comment_p = &comments; + pnm_writepaminit(&pam); + free(comments); +</code> +</pre> + +<p>This works only for PAM images. If you read a PNM image, you +always get back a null string. If you write a PNM image, you always get +an image that contains no comments. + +<p>This member does not exist before Netpbm 10.35 (August 2006). Before that, +there is no way with libnetpbm to get or set comments. The macro +<B>PAM_HAVE_COMMENT_P</B> is defined in <b>pam.h</b> where the member +exists. + +</DL> + + + +<H3 id="plainvsraw">PLAIN VERSUS RAW FORMAT</H3> + +<P>The PNM formats each come in two varieties: the older plain (text) +format and the newer raw (binary) format. There are different format +codes for the plain and raw formats, but which of the two formats the +pnm and pam functions write is independent of the format code you pass +to them. + +<P>The pam functions always write raw formats. If you specify the format +code for a plain format, a pam function assumes instead the raw +version of that format. + +<P>The pnm functions choose between plain and raw based on the +<I>forceplain</I> parameter that every write-type pnm function has. +If this boolean value is true, the function writes the plain version +of the format specified by the format code. If it is false, the +function writes the raw version of the format specified by the format +code. + +<P>We are trying to stamp out the older plain formats, so it would be +a wise choice not to write a program that sets <I>forceplain</I> true +under any circumstance. A user who needs a plain format can use the +<B>pnmtoplainpnm</B> program to convert the output of your program to +plain format. + +<H3>Reference</h3> + +<p>The <a href="libnetpbm_image.html">Libnetpbm Netpbm Image +Processing Manual</a> describes the the <b>libnetpbm</b> functions for +processing image data. + +<p>The <a href="libpm.html">Libnetpbm Utility Manual</a> +describes the functions that are not specifically related to the Netpbm +image formats. + +</BODY> +</HTML> |