Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 386 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/pamarith.1 b/upstream/mageia-cauldron/man1/pamarith.1
new file mode 100644
index 00000000..6f471b16
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamarith.1
@@ -0,0 +1,386 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamarith User Manual" 0 "24 October 2020" "netpbm documentation"
+
+.SH NAME
+pamarith - perform arithmetic on two Netpbm images
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamarith\fP
+\fB-add\fP | \fB-subtract\fP | \fB-multiply\fP | \fB-divide\fP |
+\fB-difference\fP |
+\fB-minimum\fP | \fB-maximum\fP | \fB-mean\fP |
+\fB-equal\fP | \fB-compare\fP |
+\fB-and\fP | \fB-or\fP | \fB-nand\fP | \fB-nor\fP | \fB-xor\fP |
+\fB-shiftleft\fP | \fB-shiftright\fP
+[\fB-closeness=\fP\fIN\fP]
+\fIpamfile1\fP \fIpamfile2\fP ...
+.PP
+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.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamarith\fP reads two or more 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.
+.PP
+For functions that are commutative and associative, \fBpamarith\fP applies
+  the binary function repetitively on as many input images as you supply.  For
+  example, for \fB-add\fP , the output is the sum of all the inputs.  For
+  other functions (e.g. \fB-subtract\fP), the program fails if you supply
+  more than two input images.  (Before Netpbm 10.93 (December 2020), the
+  program always failed with more than two input images).
+.PP
+For some other functions, \fBpamarith\fP could theoretically compute a
+  meaningful result for multiple arguments, but it fails nonetheless if you
+  give more than two input images.  \fB-mean\fP and \fB-equal\fP are in that
+  category.
+  
+.PP
+Most of what \fBpamarith\fP does is not meaningful for visual images.  It
+  works toward Netpbm's secondary purpose of just manipulating arbitrary
+  matrices of numbers.
+  
+.PP
+For the purpose of the calculation, it assumes any PBM, PGM, or PPM
+input image is the equivalent PAM image of tuple type
+\fBBLACKANDWHITE\fP, \fBGRAYSCALE\fP, or \fBRGB\fP, 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.
+.PP
+The first \fIpamfile\fP argument identifies the "left"
+argument image; the second \fIpamfile\fP argument identifies the
+"right" one.
+.PP
+If the output is PAM, the tuple type is the same as the tuple type of
+the left input image.
+.PP
+\fBpamarith\fP performs the arithmetic on each pair of identically
+located tuples in the two input images.
+.PP
+The arithmetic operation is in all cases fundamentally a function from two
+integers to an integer (but see below - the functions are defined in ways that
+you can effectively e.g. add real numbers).  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.  \fBpamarith\fP fails if one of these is not the
+case.
+.PP
+If they have the same depth, \fBpamarith\fP 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)).
+.PP
+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)).
+
+
+.UN pbmoddness
+.SS PBM Oddness
+.PP
+If you're familiar with the PBM format, you may find \fBpamarith\fP's
+operation on PBM images to be nonintuitive.  Because in PBM black is
+represented as 1 and white as 0, you might be expecting black minus black
+to be white.
+.PP
+But the PBM format is irrelevant, because \fBpamarith\fP operates on the
+numbers found in the PAM equivalent (see above).  In a PAM black and white
+image, black is 0 and white is 1.  So black minus black is black.
+
+  
+.UN maxval
+.SS Maxval
+.PP
+The meanings of the samples with respect to the maxval varies
+according to the function you select.
+.PP
+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.
+.PP
+For \fBpamarith\fP, this interpretation applies to the regular
+arithmetic functions: \fB-add\fP, \fB-subtract\fP, \fB-multiply\fP,
+\fB-divide\fP,
+\fB-difference\fP, \fB-minimum\fP, \fB-maximum\fP, \fB-mean\fP,
+\fB-equal\fP,
+and \fB-compare\fP.  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 \fB-add\fP 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.
+.PP
+For these functions, \fBpamarith\fP makes the output image's
+maxval the maximum of the two input maxvals, except with
+\fB-equal \fP and \fB-compare\fP.  For \fB-equal\fP, the output maxval is
+always 1.  For \fB-compare\fP, it is always 2.  (Before Netpbm 10.14
+(February 2003), there was no exception for \fB-compare\fP; in 10.14, the
+exception was just that the maxval was \fIat least\fP 2, and sometime
+between 10.18 and 10.26 (January 2005), it changed to being exactly 2).
+.PP
+If the result of a calculation falls outside the range [0, 1),
+\fBpamarith\fP clips it -- i.e.  considers it to be zero or 1-.
+.PP
+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 \fB-add\fP of sample value 5 to sample value 8 yields sample
+value 13.
+.PP
+But with \fB-multiply\fP, 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 \fBpamarith\fP 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.
+.PP
+With the bit string operations, the maxval has a whole different
+meaning.  The operations in question are: \fB-and\fP, \fB-or\fP,
+\fB-nand\fP, \fB-nor\fP, \fB-xor\fP, and \fB-shiftleft\fP,
+\fB-shiftright\fP.
+.PP
+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 \fBpamarith\fP makes the maxval
+of the output image the same.
+.PP
+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.
+
+
+.UN note
+.SH NOTE: UNARY FUNCTIONS
+.PP
+\fBpamarith\fP applies only binary functions.  If you want to apply a
+unary function, e.g. "halve", to a single image, use \fBpamfunc\fP.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamarith\fP recognizes the following
+command line options:
+
+.UN function
+.SS The Function
+.PP
+These options select the function that \fBpamarith\fP applies.
+.PP
+You must specify one of these, and cannot specify more than one.
+  
+
+
+.TP
+\fB-add\fP
+Adds the two values.  If the result is larger than maxval, it is
+clipped.
+
+.TP
+\fB-subtract\fP
+Subtracts a value in the right input image from a value in the left input
+image.
+
+.TP
+\fB-minimum\fP
+Chooses the smaller value of the two.
+
+.TP
+\fB-maximum\fP
+Chooses the larger value of the two.
+
+.TP
+\fB-difference\fP
+Calculates the absolute value of the difference.
+
+.TP
+\fB-multiply\fP
+Does an ordinary arithmetic multiplication, but tends to produce
+nonobvious results because of the way \fBpamarith\fP interprets
+sample values.  See 
+.UR #maxval
+Maxval
+.UE
+\&.
+
+.TP
+\fB-divide\fP
+Divides a value in the left input image by the value in the right
+input image.  But like \fB-multiply\fP, it tends to produce nonobvious
+results.  Note that \fBpamarith\fP 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.
+.sp
+\fB-divide\fP was new in Netpbm 10.30 (October 2005).
+
+.TP
+\fB-equal\fP
+Produces maxval when the values in the two images are equal and
+zero when they are not.  Note that the output maxval is always 1 for
+\fB-equal\fP.
+.sp
+If the maxvals of the input images are not identical, \fBpamarith\fP may
+claim two values are not equal when in fact they are, because of the precision
+with which it does the arithmetic.
+.sp
+You can make the equality test approximate with the \fB-closeness\fP
+option.  This gives the percentage of maxval by which the samples can
+differ and still be considered equal.
+.sp
+\fB-equal\fP was new in Netpbm 10.93 (December 2020).
+
+.TP
+\fB-compare\fP
+Produces the value \fB0\fP when the value in the
+left input image is less than the value in the right input image,
+\fB1\fP when the values are equal, and \fB2\fP when the left is
+greater than the right.
+.sp
+If the maxvals of the input images are not identical, \fBpamarith\fP
+may claim two values are not equal when in fact they are, because of
+the precision with which it does the arithmetic.  However, it will never
+say A is greater than B if A is less than B.
+.sp
+\fB-compare\fP was new in Netpbm 10.13 (December 2002).
+
+.TP
+\fB-and\fP, \fB-nand\fP, \fB-or\fP, \fB-nor\fP, \fB-xor\fP
+These consider the input and output images to contain bit strings;
+they compute bitwise logic operations.  Note that if the maxval is 1,
+you can also look at these as logic operations on boolean input values.
+See section 
+.UR #maxval
+Maxval
+.UE
+\& for the special meaning of
+maxval with respect to bit string operations such as these.
+
+.TP
+\fB-shiftleft\fP, \fB-shiftright\fP
+These 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.
+.sp
+Note that the maxval (see 
+.UR #maxval
+Maxval
+.UE
+\&) determines
+the width of the frame within which you are shifting.
+
+
+  
+.UN otheroptions
+.SS Other
+  
+
+
+.TP
+\fB-closeness\fP
+This changes the meaning of \fB-equal\fP.  It is not valid with any
+other function.  See the description of \fB-equal\fP.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "\fBpamfunc\fP" (1)\c
+\&,
+.BR "\fBpamsummcol\fP" (1)\c
+\&,
+.BR "\fBpamsumm\fP" (1)\c
+\&,
+.BR "\fBpnminvert\fP" (1)\c
+\&,
+.BR "\fBpambrighten\fP" (1)\c
+\&,
+.BR "\fBppmdim\fP" (1)\c
+\&,
+.BR "\fBpnmconvol\fP" (1)\c
+\&,
+.BR "\fBpamdepth\fP" (1)\c
+\&,
+.BR "\fBpnmpsnr\fP" (1)\c
+\&,
+.BR "\fBpnm\fP" (1)\c
+\&,
+.BR "\fBpam\fP" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamarith\fP replaced \fBpnmarith\fP in Netpbm 10.3 (June 2002).
+.PP
+In Netpbm 10.3 through 10.8, though, \fBpamarith\fP 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 \fBpnmarith\fP
+would be removed from Netpbm -- the plan was just to rewrite it to use
+\fBpamarith\fP; it was removed by mistake).
+.PP
+But starting with Netpbm 10.9 (September 2002), \fBpamarith\fP allows
+the images to have different depths as long as one of them has depth 1, and
+that made it backward compatible with \fBpnmarith\fP.
+.PP
+The original \fBpnmarith\fP did not have the \fB-mean\fP option.
+.PP
+The \fB-compare\fP option was added in Netpbm 10.13 (December 2002).
+.PP
+The bit string operations were added in Netpbm 10.27 (March 2005).
+.PP
+The \fB-divide\fP option was added in Netpbm 10.30 (October 2005).
+.PP
+The ability to have more than one input (operand) was added in Netpbm
+10.93 (December 2020).
+.PP
+The \fB-equal\fP option was added in Netpbm 10.93 (December 2020).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamarith.html
+.PP
\ No newline at end of file