|
Packit |
78deda |
|
|
Packit |
78deda |
<HTML>
|
|
Packit |
78deda |
<HEAD><TITLE>Pamfunc User Manual</TITLE></HEAD>
|
|
Packit |
78deda |
|
|
Packit |
78deda |
<BODY>
|
|
Packit |
78deda |
pamfunc
|
|
Packit |
78deda |
Updated: December 2013
|
|
Packit |
78deda |
|
|
Packit |
78deda |
Table Of Contents
|
|
Packit |
78deda |
|
|
Packit |
78deda |
NAME
|
|
Packit |
78deda |
pamfunc - Apply a simple monadic arithmetic function to a Netpbm image
|
|
Packit |
78deda |
|
|
Packit |
78deda |
SYNOPSIS
|
|
Packit |
78deda |
|
|
Packit |
78deda |
pamfunc
|
|
Packit |
78deda |
{
|
|
Packit |
78deda |
-multiplier=realnum |
|
|
Packit |
78deda |
-divisor=realnum |
|
|
Packit |
78deda |
-adder=integer |
|
|
Packit |
78deda |
-subtractor=integer |
|
|
Packit |
78deda |
-min=wholenum |
|
|
Packit |
78deda |
-max=wholenum
|
|
Packit |
78deda |
-andmask=hexmask
|
|
Packit |
78deda |
-ormask=hexmask
|
|
Packit |
78deda |
-xormask=hexmask
|
|
Packit |
78deda |
-not
|
|
Packit |
78deda |
-shiftleft=count
|
|
Packit |
78deda |
-shiftright=count
|
|
Packit |
78deda |
[-changemaxval]
|
|
Packit |
78deda |
}
|
|
Packit |
78deda |
[filespec]
|
|
Packit |
78deda |
|
|
Packit |
78deda |
All options can be abbreviated to their shortest unique prefix.
|
|
Packit |
78deda |
You may use two hyphens instead of one. You may separate an option
|
|
Packit |
78deda |
name and its value with white space instead of an equals sign.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
DESCRIPTION
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This program is part of Netpbm.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
pamfunc reads a Netpbm image as input and produces a Netpbm
|
|
Packit |
78deda |
image as output, with the same format, and dimensions as the
|
|
Packit |
78deda |
input. pamfunc applies a simple transfer function to each
|
|
Packit |
78deda |
sample in the input to generate the corresponding sample in the
|
|
Packit |
78deda |
output. The options determine what function.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
pamarith is the same thing for binary functions -- it takes
|
|
Packit |
78deda |
two images as input and applies a specified simple arithmetic function
|
|
Packit |
78deda |
(e.g. addition) on pairs of samples from the two to produce the single
|
|
Packit |
78deda |
output image.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
Values
|
|
Packit |
78deda |
|
|
Packit |
78deda |
The functions fall into two categories: arithmetic (such as multiply by 5)
|
|
Packit |
78deda |
and bit string (such as and with 01001000). For the arithmetic functions, the
|
|
Packit |
78deda |
function arguments and results are the fraction that a sample is of the
|
|
Packit |
78deda |
maxval, i.e. normal interpretation of PAM tuples. But for the bit string
|
|
Packit Service |
2370ca |
functions, the value is the the bit string whose value as a binary cipher is
|
|
Packit |
78deda |
the sample value, and the maxval indicates the width of the bit string.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
Arithmetic functions
|
|
Packit |
78deda |
|
|
Packit |
78deda |
The arithmetic functions are those selected by the options
|
|
Packit |
78deda |
-multiplier, -divisor, -adder, -subtractor,
|
|
Packit |
78deda |
-min, and -max.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
As an example, consider an image with maxval 100 and a sample value of 10
|
|
Packit |
78deda |
and a function of "multiply by 5." The argument to the function is
|
|
Packit |
78deda |
10/100 (0.1) and the result is 5 * 0.1 = 0.5. In the simplest case, the
|
|
Packit |
78deda |
maxval of the output is also 100, so the output sample value is 0.5 * 100 =
|
|
Packit |
78deda |
50. As you can see, we could just talk about the sample values themselves
|
|
Packit |
78deda |
instead of these fractions and get the same result (10 * 5 = 50), but we
|
|
Packit |
78deda |
don't.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
Where it makes a practical difference whether we consider the values to be
|
|
Packit |
78deda |
the fraction of the maxval or the sample value alone is where pamfunc
|
|
Packit |
78deda |
uses a different maxval in the output image than it finds in the input
|
|
Packit |
78deda |
image. See -changemaxval.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
So remember in reading the descriptions below that the values are 0.1 and
|
|
Packit |
78deda |
0.5 in this example, not 10 and 50. All arguments and results are in the
|
|
Packit |
78deda |
range [0,1].
|
|
Packit |
78deda |
|
|
Packit |
78deda |
Bit string functions
|
|
Packit |
78deda |
|
|
Packit |
78deda |
The bit string functions are those selected by the options
|
|
Packit |
78deda |
-andmask, -ormask, -xormask, -not,
|
|
Packit |
78deda |
-shiftleft, and -shiftright.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
With these functions, the maxval has a very different meaning than in
|
|
Packit |
78deda |
normal Netpbm images: it tells how wide (how many bits) the bit string is.
|
|
Packit |
78deda |
The maxval must be a full binary count (a power of two minus one, such as
|
|
Packit |
78deda |
0xff) and the number of ones in it is the width of the bit string.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
As an example, consider an image with maxval 15 and a sample value of 5
|
|
Packit |
78deda |
and a function of "and with 0100". The argument to the function is
|
|
Packit |
78deda |
0101 and the result is 0100.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
In this example, it doesn't make any practical difference what we consider
|
|
Packit |
78deda |
the width of the string to be, as long as it is at least 3. If the maxval
|
|
Packit |
78deda |
were 255, the result would be the same. But with a bit shift operation,
|
|
Packit |
78deda |
it matters. Consider shifting left by 2 bits. In the example, where
|
|
Packit |
78deda |
the input value is 0101, the result is 0100. But if the maxval were 255,
|
|
Packit |
78deda |
the result would be 00010100.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
For a masking function, the mask value you specify must not have
|
|
Packit |
78deda |
more significant bits than the width indicated by the maxval.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
For a shifting operation, the shift count you specify must not be
|
|
Packit |
78deda |
greater than the width indicated by the maxval.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
OPTIONS
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-multiplier=realnum
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of multiplying by
|
|
Packit |
78deda |
realnum. realnum must be nonnegative. If the result
|
|
Packit |
78deda |
is greater than one, it is clipped to one.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
Where the input is a PGM or PPM image, this has the effect of
|
|
Packit |
78deda |
dimming or brightening it. For a different kind of brightening,
|
|
Packit |
78deda |
see ppmbrighten and
|
|
Packit |
78deda |
ppmflash
|
|
Packit |
78deda |
|
|
Packit |
78deda |
Also, see ppmdim, which does the same
|
|
Packit |
78deda |
thing as pamfunc -multiplier on a PPM image with a multiplier
|
|
Packit |
78deda |
between zero and one, except it uses integer arithmetic, so it may be
|
|
Packit |
78deda |
faster.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
And ppmfade can generate a whole
|
|
Packit |
78deda |
sequence of images of brightness declining to black or increasing to
|
|
Packit |
78deda |
white, if that's what you want.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-divisor=realnum
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of dividing by
|
|
Packit |
78deda |
realnum. realnum must be nonnegative. If the result
|
|
Packit |
78deda |
is greater than one, it is clipped to one.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This is the same function as you would get with -multiplier,
|
|
Packit |
78deda |
specifying the multiplicative inverse of realnum.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-adder=integer
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of adding
|
|
Packit |
78deda |
integer/maxval. If the result is greater than one, it is
|
|
Packit |
78deda |
clipped to one. If it is less than zero, it is clipped to zero.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
Note that in mathematics, this entity is called an "addend,"
|
|
Packit |
78deda |
and an "adder" is a snake. We use "adder" because
|
|
Packit |
78deda |
it makes more sense.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-subtractor=integer
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of subtracting
|
|
Packit |
78deda |
integer/maxval. If the result is greater than one, it is
|
|
Packit |
78deda |
clipped to one. If it is less than zero, it is clipped to zero.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
Note that in mathematics, this entity is called a
|
|
Packit |
78deda |
"subtrahend" rather than a "subtractor." We use
|
|
Packit |
78deda |
"subtractor" because it makes more sense.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This is the same function as you would get with -adder,
|
|
Packit |
78deda |
specifying the negative of integer.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-min=wholenum
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of taking the maximum of
|
|
Packit |
78deda |
the argument and wholenum/maxval. I.e the minimum value in
|
|
Packit |
78deda |
the output will be wholenum/maxval.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
If wholenum/maxval is greater than one, though, every value
|
|
Packit |
78deda |
in the output will be one.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-max=wholenum
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of taking the minimum of
|
|
Packit |
78deda |
the argument and wholenum/maxval. I.e the maximum value in
|
|
Packit |
78deda |
the output will be wholenum/maxval.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
If wholenum/maxval is greater than one, the function is
|
|
Packit |
78deda |
idempotent -- the output is identical to the input.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-andmask=hexmask
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of bitwise anding
|
|
Packit |
78deda |
with hexmask.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
hexmask is in hexadecimal. Example: 0f
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option was new in Netpbm 10.40 (September 2007).
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-ormask=hexmask
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of bitwise
|
|
Packit |
78deda |
inclusive oring with hexmask.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This is analogous to -andmask.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option was new in Netpbm 10.40 (September 2007).
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-xormask=hexmask
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of bitwise
|
|
Packit |
78deda |
exclusive oring with hexmask.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This is analogous to -andmask.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option was new in Netpbm 10.40 (September 2007).
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-not
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of bitwise logical
|
|
Packit |
78deda |
inversion (e.g. sample value 0xAA becomes 0x55).
|
|
Packit |
78deda |
|
|
Packit |
78deda |
pnminvert does the same thing for a bilevel visual image
|
|
Packit |
78deda |
which has maxval 1 or is of PBM type.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option was new in Netpbm 10.40 (September 2007).
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-shiftleft=count
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of bitwise shifting
|
|
Packit |
78deda |
left by count bits.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option was new in Netpbm 10.40 (September 2007).
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-shiftright=count
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option makes the transfer function that of bitwise shifting
|
|
Packit |
78deda |
right by count bits.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This is analogous to -shiftleft.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option was new in Netpbm 10.40 (September 2007).
|
|
Packit |
78deda |
|
|
Packit |
78deda |
-changemaxval
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option tells pamfunc to use a different maxval in the output
|
|
Packit |
78deda |
image than the maxval of the input image, if it helps. By default, the maxval
|
|
Packit |
78deda |
of the output is unchanged from the input and pamfunc modifies the
|
|
Packit |
78deda |
sample values as necessary to perform the operation.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
But there is one case where pamfunc can achieve the same result just
|
|
Packit |
78deda |
by changing the maxval and leaving the sample values unchanged: dividing by a
|
|
Packit |
78deda |
number 1 or greater, or multiplying by a number 1 or less. For example, to
|
|
Packit |
78deda |
halve all of the values, pamfunc can just double the maxval.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
With -changemaxval, pamfunc will do just that.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
As the Netpbm formats have a maximum maxval of 65535, for large divisors,
|
|
Packit |
78deda |
pamfunc may not be able to use this method.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
An advantage of dividing by changing the maxval is that you don't lose
|
|
Packit |
78deda |
precision. The higher maxval means higher precision. For example, consider
|
|
Packit |
78deda |
an image with a maxval of 100 and sample value of 10. You divide by 21 and
|
|
Packit |
78deda |
then multiply by 21 again. If pamfunc does this by changing the sample
|
|
Packit |
78deda |
values while retaining maxval 100, the division will result in a sample value
|
|
Packit |
78deda |
of 0 and the multiplication will also result in zero. But if pamfunc
|
|
Packit |
78deda |
instead keeps the sample value 10 and changes the maxval, the division will
|
|
Packit |
78deda |
result in a maxval of 2100 and the multiplication will change it back to 100,
|
|
Packit |
78deda |
and the round trip is idempotent.
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This option was new in Netpbm 10.65 (December 2013).
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
SEE ALSO
|
|
Packit |
78deda |
|
|
Packit |
78deda |
ppmdim,
|
|
Packit |
78deda |
ppmbrighten,
|
|
Packit |
78deda |
pamdepth,
|
|
Packit |
78deda |
pamarith,
|
|
Packit |
78deda |
pamsummcol,
|
|
Packit |
78deda |
pamsumm,
|
|
Packit |
78deda |
ppmfade,
|
|
Packit |
78deda |
pnminvert,
|
|
Packit |
78deda |
|
|
Packit |
78deda |
pam,
|
|
Packit |
78deda |
|
|
Packit |
78deda |
pnm,
|
|
Packit |
78deda |
|
|
Packit |
78deda |
HISTORY
|
|
Packit |
78deda |
|
|
Packit |
78deda |
This program was added to Netpbm in Release 10.3 (June 2002).
|
|
Packit |
78deda |
|
|
Packit |
78deda |
|
|
Packit |
78deda |
Table Of Contents
|
|
Packit |
78deda |
|
|
Packit |
78deda |
SYNOPSIS
|
|
Packit |
78deda |
DESCRIPTION
|
|
Packit |
78deda |
|
|
Packit |
78deda |
Values
|
|
Packit |
78deda |
|
|
Packit |
78deda |
OPTIONS
|
|
Packit |
78deda |
SEE ALSO
|
|
Packit |
78deda |
HISTORY
|
|
Packit |
78deda |
|
|
Packit |
78deda |
</BODY>
|
|
Packit |
78deda |
</HTML>
|