diff options
| author | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2006-12-25 03:06:05 +0000 |
|---|---|---|
| committer | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2006-12-25 03:06:05 +0000 |
| commit | 1017cbebe5d5edd859e0fddad0a8600f509f4821 (patch) | |
| tree | 78bdf336648566f7a7d55f42837357dea3dd674c /pamarith.html | |
| parent | 16f2ac126651015a376eba864a3a35f738b0b25a (diff) | |
| download | netpbm-mirror-1017cbebe5d5edd859e0fddad0a8600f509f4821.tar.gz netpbm-mirror-1017cbebe5d5edd859e0fddad0a8600f509f4821.tar.xz netpbm-mirror-1017cbebe5d5edd859e0fddad0a8600f509f4821.zip | |
Place user guide into Subversion repository
git-svn-id: http://svn.code.sf.net/p/netpbm/code/userguide@181 9d0c8265-081b-0410-96cb-a4ca84ce46f8
Diffstat (limited to 'pamarith.html')
| -rw-r--r-- | pamarith.html | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/pamarith.html b/pamarith.html new file mode 100644 index 00000000..d2fa2c0b --- /dev/null +++ b/pamarith.html @@ -0,0 +1,253 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> +<HEAD><TITLE>Pamarith User Manual</TITLE></HEAD> +<BODY> +<H1>pamarith</H1> +Updated: 08 October 2005 +<BR> +<A HREF="#index">Table Of Contents</A> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> +pamarith - perform arithmetic on two Netpbm images + +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<B>pamarith</B> +<B>-add</B> | <B>-subtract</B> | <B>-multiply</B> | <b>-divide</b> | +<B>-difference</B> | +<B>-minimum</B> | <B>-maximum</B> | <B>-mean</B> | <B>-compare</B> | +<B>-and</B> | <B>-or</B> | <B>-nand</B> | <B>-nor</B> | <B>-xor</B> | +<B>-shiftleft</B> | <B>-shiftright</B> +<I>pamfile1</I> <I>pamfile2</I> + +<P>All options can be abbreviated to their shortest unique prefix. +You may use two hyphens instead of one. You may separate an option +name and its value with white space instead of an equals sign. + +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<p>This program is part of <a href="index.html">Netpbm</a>. + +<P><b>pamarith</b> reads two PBM, PGM, PPM, or PAM images as input. +It performs the specified binary arithmetic operation on their sample +values and produces an output of a format which is the more general of +the two input formats. The two input images must be of the same width +and height. The arithmetic is performed on each pair of identically +located tuples to generate the identically located tuple of the +output. + +<P>For the purpose of the calculation, it assumes any PBM, PGM, or PPM +input image is the equivalent PAM image of tuple type +<B>BLACKANDWHITE</B>, <B>GRAYSCALE</B>, or <B>RGB</B>, respectively, +and if it produces a PBM, PGM, or PPM output, produces the equivalent +of the PAM image which is the result of the calculation. + +<p>The first <i>pamfile</i> argument identifies the "left" +argument image; the second <i>pamfile</i> argument identifies the +"right" one. + +<p>If the output is PAM, the tuple type is the same as the tuple type of +the left input image. + +<P><b>pamarith</b> performs the arithmetic on each pair of identically +located tuples in the two input images. + +<p>The arithmetic operation is in all cases fundamentally a function +from two integers to an integer. The operation is performed on two +tuples as follows. The two input images must have the same depth, or +one of them must have depth one. <b>pamarith</b> fails if one of +these is not the case. + +<p>If they have the same depth, <b>pamarith</b> simply carries out the +arithmetic one sample at a time. I.e. if at a particular position the +left input image contains the tuple (s1,s2,...,sN) and the right +input image contains the tuple (t1,t2,...tN), and the function is f, +then the output image contains the tuple +(f(s1,t1),f(s2,t2),...,f(sN,tN)). + +<p>If one of the images has depth 1, the arithmetic is performed +between the one sample in that image and each of the samples in the +other. I.e. if at a particular position the left input image +contains the tuple (s) and the right input image contains the tuple +(t1,t2,...tN), and the function is f, then the output image contains +the tuple (f(s,t1),f(s,t2),...,f(s,tN)). + +<h3 id="maxval">Maxval</h3> + +<p>The meanings of the samples with respect to the maxval varies +according to the function you select. + +<p>In PAM images in general, the most usual meaning of a sample (the +one that applies when a PAM image represents a visual image), is that +it represents a fraction of some maximum. The maxval of the image +corresponds to some maximum value (in the case of a visual image, it +corresponds to "full intensity."), and a sample value +divided by the maxval gives the fraction. + +<p>For <b>pamarith</b>, this interpretation applies to the regular +arithmetic functions: <B>-add</B>, <B>-subtract</B>, <B>-multiply</B>, +<b>-divide</b>, +<B>-difference</B>, <B>-minimum</B>, <B>-maximum</B>, <B>-mean</B>, +and <B>-compare</B>. For those, you should think of the arguments and +result as numbers in the range [0,1). For example, if the maxval of +the left argument image is 100 and the maxval of the right argument +image is 200 and the maxval of the output image is 200, and the left +sample value in an <b>-add</b> calculation is 50 and the right sample +is 60, the actual calculation is 50/100 + 60/200 = 160/200, and +the output sample value is 160. + +<P>For these functions, <b>pamarith</b> makes the output image's +maxval the maximum of the two input maxvals, except with +<b>-compare</b>, where <b>pamarith</b> uses an output maxval of 2. + +<p>If the result of a calculation falls outside the range [0, 1), +<b>pamarith</b> clips it -- i.e. considers it to be zero or 1-. + +<p>In many cases, where both your input maxvals are the same, you can +just think of the operation as taking place between the sample values +directly, with no consideration of the maxval except for the clipping. +E.g. an <b>-add</b> of sample value 5 to sample value 8 yields sample +value 13. + +<p>But with <b>-multiply</b>, this doesn't work. Say your two input +images have maxval 255, which means the output image also has maxval +255. Consider a location in the image where the input sample values +are 5 and 10. You might think the multiplicative product of those +would yield 50 in the output. But <b>pamarith</b> carries out the +arithmetic on the fractions 5/255 and 10/255. It multiplies those +together and then rescales to the output maxval, giving a sample value +in the output PAM of 50/255 rounded to the nearest integer: 0. + +<P>With the bit string operations, the maxval has a whole different +meaning. The operations in question are: <B>-and</B>, <B>-or</B>, +<B>-nand</B>, <B>-nor</B>, <B>-xor</B>, and <B>-shiftleft</B>, +<B>-shiftright</B>. + +<p>With these, each sample value in one or both input images, and in +the output image, represents a bit string, not a number. The maxval +tells how wide the bit string is. The maxval must be a full binary +count (a power of two minus one, such as 0xff) and the number of ones +in it is the width of the bit string. For the dyadic bit string +operations (that's everything but the shift functions), the maxvals of +the input images must be the same and <b>pamarith</b> makes the maxval +of the output image the same. + +<p>For the bit shift operations, the output maxval is the same as the +left input maxval. The right input image (which contains the shift +counts) can have any maxval and the maxval is irrelevant to the +interpretation of the samples. The sample value is the actual shift +count. But it's still required that no sample value exceed the +maxval. + +<h3 id="operations">The Operations</h3> + +<p>Most of the operations are obvious from the option name. + +<P><B>-subtract</B> subtracts a value in the right input image from a +value in the left input image. + +<P><B>-difference</B> calculates the absolute value of +the difference. + +<p><b>-multiply</b> does an ordinary arithmetic multiplication, but +tends to produce nonobvious results because of the way <b>pamarith</b> +interprets sample values. See <a href="#maxval">Maxval</a>. + +<P><b>-divide</b> divides a value in the left input image by the value +in the left input image. But like <b>-multiply</b>, it tends to +produce nonobvious results. Note that <b>pamarith</b> clipping +behavior makes this of little use when the left argument (dividend) is +greater than the right argument (divisor) -- the result in that case +is always the maxval. If the divisor is 0, the result is the maxval. +This option was new in Netpbm 10.30 (October 2005). + +<P><B>-compare</B> produces the value <b>0</b> when the value in the +left input image is less than the value in the right input image, +<b>1</b> when the values are equal, and <b>2</b> when the left is +greater than the right. + +<p>If the maxvals of the input images are not identical, <b>pamarith</b> +may claim two values are not equal when in fact they are, due to +the precision with which it does the arithmetic. However, it will never +say A is greater than B if A is less than B. + +<p><b>-compare</b> was new in Netpbm 10.13 (December 2002). + +<p><b>-and</b>, <b>-nand</b>, <b>-or</b>, <b>-nor</b>, and <b>-xor</b> +consider the input and output images to contain bit strings; they compute +bitwise logic operations. + +<p><b>-shiftleft</b> and <b>-shiftright</b> consider the left input +image and output image to contain bit strings. They compute a bit +shift operation, with bits falling off the left or right end and +zeroes shifting in, as opposed to bits off one end to the other. The +right input image sample value is the number of bit positions to +shift. + +<p>Note that the maxval (see <a href="#maxval">Maxval</a>) determines +the width of the frame within which you are shifting. + +<h3 id="notes">Notes</h3> + +<P>If you want to apply a unary function, e.g. "halve", to a single +image, use <b>pamfunc</b>. + +<A NAME="lbAE"> </A> +<H2>SEE ALSO</H2> + +<A HREF="pamfunc.html"><b>pamfunc</b></A>, +<A HREF="pamsummcol.html"><b>pamsummcol</b></A>, +<A HREF="pamsumm.html"><b>pamsumm</b></A>, +<A HREF="pnminvert.html"><b>pnminvert</b></A>, +<A HREF="ppmbrighten.html"><b>ppmbrighten</b></A>, +<A HREF="ppmdim.html"><b>ppmdim</b></A>, +<A HREF="pnmconvol.html"><b>pnmconvol</b></A>, +<A HREF="pamdepth.html"><b>pamdepth</b></A>, +<A HREF="pnmpsnr.html"><b>pnmpsnr</b></A>, +<A HREF="pnm.html">pnm</A>, +<A HREF="pam.html">pam</A> + + +<A NAME="history"></A> +<H2>HISTORY</h2> + +<p><b>pamarith</b> replaced <b>pnmarith</b> in Netpbm 10.3 (June 2002). + +<p>In Netpbm 10.3 through 10.8, though, <b>pamarith</b> was not +backward compatible because it required the input images to be of the +same depth, so you could not multiply a PBM by a PPM as is often done +for masking. (It was not intended at the time that <b>pnmarith</b> +would be removed from Netpbm -- the plan was just to rewrite it to use +<b>pamarith</b>; it was removed by mistake). + +<p>But starting with Netpbm 10.9 (September 2002), <b>pamarith</b> allows +the images to have different depths as long as one of them has depth 1, and +that made it backward compatible with <b>pnmarith</b>. + +<P>The original <b>pnmarith</b> did not have the <b>-mean</b> option. + +<P>The <b>-compare</b> option was added in Netpbm 10.13 (December 2002). + +<p>The bit string operations were added in Netpbm 10.27 (March 2005). + +<P>The <b>-divide</b> option was added in Netpbm 10.30 (October 2005). + +<HR> +<A NAME="index"> </A> +<H2>Table Of Contents</H2> +<UL> +<LI><A HREF="#lbAB">NAME</A> +<LI><A HREF="#lbAC">SYNOPSIS</A> +<LI><A HREF="#lbAD">DESCRIPTION</A> +<LI><A HREF="#maxval">MAXVAL</A> +<LI><A HREF="#operations">THE OPERATIONS</A> +<LI><A HREF="#notes">NOTES</A> +<LI><A HREF="#history">HISTORY</A> +<LI><A HREF="#lbAE">SEE ALSO</A> +<LI><A HREF="#lbAF">AUTHOR</A> +</UL> +</BODY> +</HTML> |