Pamfunc User Manual(0)					Pamfunc User Manual(0)



NAME
       pamfunc - Apply a simple monadic arithmetic function to a Netpbm image


SYNOPSIS
       pamfunc	{  -multiplier=realnum	|  -divisor=realnum | -adder=integer |
       -subtractor=integer | -min=wholenum  |  -max=wholenum  -andmask=hexmask
       -ormask=hexmask	     -xormask=hexmask	    -not      -shiftleft=count
       -shiftright=count } [filespec]

       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.


DESCRIPTION
       This program is part of Netpbm(1).

       pamfunc reads a Netpbm image as input and produces a  Netpbm  image  as
       output,	with  the  same	 format,  maxval, and dimensions as the input.
       pamfunc applies a simple transfer function to each sample in the	 input
       to generate the corresponding sample in the output.  The options deter-
       mine what function.

       pamarith is the same thing for binary functions -- it takes two	images
       as input and applies a specified simple arithmetic function (e.g. addi-
       tion) on pairs of samples from the two to  produce  the	single	output
       image.



OPTIONS
       -multiplier=realnum

	      This option makes the transfer function that of multiplying by
		   realnum.  realnum must be nonnegative.  If the result
		   is greater than the image maxval, it is clipped to the max-
	      val.

	      Where the input is a PGM or PPM image, this has the effect of
		   dimming or brightening it.  For a different kind of bright-
	      ening,
		   see ppmbrighten(1)and ppmflash(1)

	      Also, see ppmdim(1),whichdoesthe
		   same thing as pamfunc -multiplier on a PPM image with a
		   multiplier between 0 and 1,
		   except it uses integer arithmetic, so it may be faster.

	      And ppmfade(1)cangenerateawhole
		   sequence  of	 images	 of  brightness	 declining to black or
	      increasing to
		   white, if that's what you want.


       -divisor=realnum

	      This option makes the transfer function that of dividing by
		   realnum.  realnum must be nonnegative.  If the result
		   is greater than the image maxval, it is clipped to the max-
	      val.

	      This is the same function as you would get with -multiplier,
		   specifying the multiplicative inverse of realnum.


       -adder=integer

	      This option makes the transfer function that of adding
		   wholenum.  If the result is greater than the image maxval,
		   it  is  clipped to the maxval.  If it is less than zero, it
	      is
		   clipped to zero.

	      Note that in mathematics, this entity is called an 'addend,'
		   and an 'adder' is a snake.  We use 'adder' because
		   it makes more sense.


       -subtractor=integer

	      This option makes the transfer function that of subtracting
		   wholenum.  If the result is greater than the image maxval,
		   it is clipped to the maxval.	 If it is less than  zero,  it
	      is
		   clipped to zero.

	      Note that in mathematics, this entity is called a
		   'subtrahend' rather than a 'subtractor.'  We
		   use 'subtractor' because it makes more sense.

	      This is the same function as you would get with -adder,
		   specifying the negative of integer.


       -min=wholenum

	      This option makes the transfer function that of taking the
		   maximum of the argument and wholenum.  I.e the minimum
		   value in the output will be wholenum.

		   If  wholenum is greater than the maxval, though, every sam-
	      ple
		   in the output will be maxval.


       -max=wholenum

	      This option makes the transfer function that of taking the
		   minimum of the argument and wholenum.  I.e the maximum
		   value in the output will be wholenum.

		   If wholenum is greater than the maxval, the function is
		   idempotent -- the output is identical to the input.


       -andmask=hexmask

	      This option makes the transfer function that of bitwise anding
		   with hexmask.

	      hexmask is in hexadecimal.  Example: 0f

	      See section Maxval <#maxval>  for the special
		   meaning of maxval with respect  to  bit  string  operations
	      such as
		   this.

	      This option was new in Netpbm 10.40 (September 2007).


       -ormask=hexmask

	      This option makes the transfer function that of bitwise
		   inclusive oring with hexmask.

	      This is analogous to -andmask.

	      This option was new in Netpbm 10.40 (September 2007).


       -xormask=hexmask

	      This option makes the transfer function that of bitwise
		   exclusive oring with hexmask.

	      This is analogous to -andmask.

	      This option was new in Netpbm 10.40 (September 2007).


       -not

	      This option makes the transfer function that of bitwise logical
		   inversion (e.g. sample value 0xAA becomes 0x55).

	      See section Maxval <#maxval>  for the special
		   meaning  of	maxval	with  respect to bit string operations
	      such as
		   this.

	      pnminvert does the same thing for a bilevel visual image
		   which has maxval 1 or is of PBM type.

	      This option was new in Netpbm 10.40 (September 2007).


       -shiftleft=count

	      This option makes the transfer function that of bitwise shifting
		   left by count bits.

	      See section Maxval <#maxval>  for the special
		   meaning of maxval with respect  to  bit  string  operations
	      such as
		   this.

	      This option was new in Netpbm 10.40 (September 2007).


       -shiftright=count

	      This option makes the transfer function that of bitwise shifting
		   right by count bits.

	      This is analogous to -shiftleft.

	      This option was new in Netpbm 10.40 (September 2007).




MAXVAL
       For  the arithmetic functions, the maxval has no meaning.  The function
       applies to the sample value as an integer.   (Note  that	 this  differs
       from  the  usual interpretation of PAM samples as being a fraction of a
       maxval, but does produce more intuitive result: 2 times 5 is 10.

       But with the bit string operations, the maxval has a  special  meaning.
       The  functions  in  question  are:  -andmask,  -ormask, -xormask, -not,
       -shiftleft, and -shiftright.

       With these, each sample value the input image, 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 a masking function, the mask value you specify must not  have  more
       significant bits than the width indicated by the maxval.

       For  a  shifting	 operation,  the  shift	 count you specify must not be
       greater than the width indicated by the maxval.

       The maxval of the output image is the same as that of the input image.



SEE ALSO
       ppmdim(1),  ppmbrighten(1),  pamdepth(1),  pamarith(1),	pamsummcol(1),
       pamsumm(1), ppmfade(1), pnminvert(1), pam(1), pnm(1),


HISTORY
       This program was added to Netpbm in Release 10.3 (June 2002).



netpbm documentation		   July 2007		Pamfunc User Manual(0)