Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 486 insertions, 0 deletions

diff --git a/upstream/fedora-40/man1/pnmconvol.1 b/upstream/fedora-40/man1/pnmconvol.1
new file mode 100644
index 00000000..cb5e2a29
--- /dev/null
+++ b/upstream/fedora-40/man1/pnmconvol.1
@@ -0,0 +1,486 @@
+\
+.\" 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 "Pnmconvol User Manual" 0 "30 November 2018" "netpbm documentation"
+
+.SH NAME
+pnmconvol - general MxN convolution on a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmconvol\fP
+{
+\fB-matrix=\fP\fIconvolution_matrix\fP
+|
+\fB-matrixfile=\fP\fIfilename\fP[\fB,\fP\fIfilename\fP[\fB,\fP ...]]
+}
+[\fB-normalize\fP]
+[\fB-bias=\fIn\fP\fP]
+
+[\fInetpbmfile\fP]
+.PP
+\fBpnmconvol\fP
+\fIconvolution_matrix_file\fP
+[\fB-normalize\fP]
+[\fB-nooffset\fP]
+[\fInetpbmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmconvol\fP reads a Netpbm image as input, convolves it with
+a specified convolution matrix, and writes a Netpbm image as output.
+.PP
+A command use for convolution is blurring.  See examples in the
+.BR "\fBpamgauss\fP" (1)\c
+\& manual.
+  
+.PP
+Convolution means replacing each pixel with a weighted average of
+the nearby pixels.  The weights and the area to average are determined
+by the convolution matrix (sometimes called a convolution kernel),
+which you supply in one of several ways.  See 
+.UR #convolmatrix
+ Convolution Matrix
+.UE
+\&.
+.PP
+At the edges of the convolved image, where the convolution matrix would
+extend over the edge of the image, \fBpnmconvol\fP just copies the input
+pixels directly to the output.  It's often better to deal with the pixels near
+an edge by assuming some blank or background color beyond the edge.  To do
+that, use \fBpnmpad\fP to add a margin all around whose size is half that of
+your convolution matrix size, not counting its center, in the same dimension.
+(E.g. if your convolution matrix is 5 wide by 3 high, use
+\f(CWpnmpad -left=2 -right=2 -top=1 -bottom=1\fP).  Feed that enlarged
+image to \fBpnmconvol\fP, then use \fBpamcut\fP to chop the edges off the
+convolved output, getting back to your original image dimensions.  (E.g.
+\f(CWpamcut -left=2 -right=-2 -top=1 -bottom=-1\fP).
+.PP
+The convolution computation can result in a value which is outside the
+range representable in the output.  When that happens, \fBpnmconvol\fP just
+clips the output, which means brightness is not conserved.
+.PP
+To avoid clipping, you may want to scale your input values.  For example,
+if your convolution matrix might produce an output value as much as double the
+maximum value in the input, then make sure the maxval of the input (which is
+also the maxval of the output) is at least twice the actual maximum value in
+the input.
+.PP
+Clipping negative numbers deserves special consideration.  If your
+convolution matrix includes negative numbers, it is possible for
+\fBpnmconvol\fP to calculate an output pixel as a negative value,
+which \fBpnmconvol\fP would of course clip to zero, since Netpbm formats
+cannot represent negative numbers.
+
+
+.UN convolmatrix
+.SS Convolution Matrix
+.PP
+There are three ways to specify the convolution matrix:
+
+
+.IP \(bu
+directly with a \fB-matrix\fP option.
+
+.IP \(bu
+In a file (or set of them) named by a \fB-matrixfile\fP option, whose
+contents are similar to a \fB-matrix\fP option value.
+
+.IP \(bu
+With a special PNM file.
+
+.PP
+The PNM file option is the hardest, and exists only because
+until Netpbm 10.49 (December 2009), it was the only way.
+.PP
+The regular convolution matrix file is slightly easier to read
+than the \fB-matrix\fP option value, and makes your command line
+less messy, but requires you to manage a separate file.  With the file,
+you can have separate convolution matrices for the individual color
+components, which you can't do with \fB-matrix\fP.
+.PP
+In any case, the convolution matrix \fBpnmconvol\fP uses is a
+matrix of real numbers.  They can be whole or fractional, positive,
+negative, or zero.
+.PP
+The convolution matrix always has an odd width and height, so that
+there is a center element.  \fBpnmconvol\fP figuratively places that
+center element over a pixel of the input image and weights that pixel
+and its neighbors as indicated by the convolution matrix to produce the
+pixel in the same location of the output image.
+.PP
+For a normal convolution, where you're neither adding nor subtracting total
+value from the image, but merely moving it around, you'll want to make sure
+that all the numbers in the matrix add up to 1.  If they don't,
+\fBpnmconvol\fP warns you.
+.PP
+The elements of the matrix are actually tuples, one for each sample in the
+input.  (I.e. if the input is an RGB image, each element of the convolution
+matrix has one weight for red, one for green, and one for blue.
+
+
+.UN matrixopt
+.B Directly On the Command Line
+.PP
+Here are examples of a \fB-matrix\fP option:
+
+.nf
+\f(CW
+    -matrix=0,.2,0;.2,.2,.2;0,.2,0
+\fP
+
+.fi
+
+.nf
+\f(CW
+    -matrix=-1,3,-1
+\fP
+
+.fi
+.PP
+The value consists of each row of the matrix from top to bottom, separated
+by semicolons.  Each row consists of the elements of the row from left to
+right, separated by commas.  You must of course have the same number of
+elements in each row.  Each element is a decimal floating point number
+and is the weight to give to each component of a pixel that corresponds to
+that matrix location.
+.PP
+Note that when you supply this option via a shell, semicolon
+(";") probably means something to the shell, so use quotation
+marks.
+.PP
+There is no way with this method to have different weights for different
+components of a pixel.
+.PP
+The \fB-normalize\fP option is often quite handy with \fB-matrix\fP
+because it lets you quickly throw together the command without working out the
+math to make sure the matrix isn't biased.  Note that if you use the
+\fB-normalize\fP option, the weights in the matrix aren't actually the
+numbers you specify in the \fB-matrix\fP option.
+
+
+.UN matrixfile
+.B Regular Matrix File
+.PP
+Specify the name of the matrix file with a \fB-matrixfile\fP
+option.  Or specify a list of them, one for each plane of the image.
+.PP
+Examples:
+
+.nf
+\f(CW
+    -matrixfile=mymatrix
+\fP
+
+\f(CW
+    -matrixfile=myred,mygreen,myblue
+\fP
+
+.fi
+.PP
+Each file applies to one plane of the image (e.g. red, green, or blue), in
+order.  The matrix in each file must have the same dimensions.  If the
+input image has more planes than the number of files you specify, the first
+file applies to the extra planes as well.
+.PP
+\fBpnmconvol\fP interprets the file as text, with lines delimited by Unix
+newline characters (line feeds).
+.PP
+Each line of the file is one row of the matrix, in order from top to
+bottom.
+.PP
+For each row, the file contains a floating point decimal number for each
+element in the row, from left to right, separated by spaces.  This is not just
+any old white space -- it is exactly one space.  Two spaces in a row mean
+you've specified a null string for an element (which is invalid).  If you
+want to line up your matrix visually, use leading and trailing zeroes
+in the floating point numbers to do it.
+.PP
+There is no way to put comments in the file.  There is no signature
+or any other metadata in the file.
+.PP
+Note that if you use the \fB-normalize\fP option, the weights in the
+matrix aren't actually what is in the file.
+
+
+.UN matrixpnm
+.B PNM File
+.PP
+Before Netpbm 10.49 (December 2009), this was the only way to 
+specify a convolution matrix.  \fBpnmconvol\fP used this method in
+an attempt to exploit the generic matrix processing capabilities of
+Netpbm, but as the Netpbm formats don't directly allow matrices with
+the kinds of numbers you need in a convolution matrix, it is quite
+cumbersome.  In fact, there simply is no way to specify some convolution
+matrices with a legal Netpbm image, so to make it work, \fBpnmconvol\fP has
+to relax the Netpbm file requirement that sample values be no greater
+than the image's maxval.  I.e. it isn't even a real PNM file.
+.PP
+The way you select this method of supplying the convolution matrix is to
+\fInot\fP specify \fB-matrix\fP or \fB-matrixfile\fP.  When you do that,
+you must specify a second non-option argument -- that is the name of the PNM
+file (or PNM equivalent PAM file).
+.PP
+There are two ways \fBpnmconvol\fP interprets the PNM convolution matrix
+image pixels as weights: with offsets, and without offsets.
+.PP
+The simpler of the two is without offsets.  That is what happens
+when you specify the \fB-nooffset\fP option.  In that case,
+\fBpnmconvol\fP simply normalizes the sample values in the PNM image
+by dividing by the maxval.
+.PP
+For example, here is a sample convolution file that causes an output pixel
+to be a simple average of its corresponding input pixel and its 8 neighbors,
+resulting in a smoothed image:
+
+.nf
+    P2
+    3 3
+    18
+    2 2 2
+    2 2 2
+    2 2 2
+
+.fi
+.PP
+(Note that the above text is an actual PGM file -- you can cut and paste
+it.  If you're not familiar with the plain PGM format, see
+.BR "the PGM format specification" (1)\c
+\&).
+.PP
+\fBpnmconvol\fP divides each of the sample values (2) by the maxval
+(18) so the weight of each of the 9 input pixels gets is 1/9, which is
+exactly what you want to keep the overall brightness of the image the
+same.  \fBpnmconvol\fP creates an output pixel by multiplying the
+values of each of 9 pixels by 1/9 and adding.
+.PP
+Note that with maxval 18, the range of possible values is 0 to 18.
+After scaling, the range is 0 to 1.
+.PP
+For a normal convolution, where you're neither adding nor
+subtracting total value from the image, but merely moving it around,
+you'll want to make sure that all the scaled values in (each plane of)
+your convolution PNM add up to 1, which means all the actual sample
+values add up to the maxval.  Alternatively, you can use the
+\fB-normalize\fP option to scale the scaled values further to make them all
+add up to 1 automatically.
+.PP
+When you \fIdon't\fP specify \fB-nooffset\fP, \fBpnmconvol\fP
+applies an offset, the purpose of which is to allow you to indicate
+negative weights even though PNM sample values are never negative.  In
+this case, \fBpnmconvol\fP subtracts half the maxval from each sample
+and then normalizes by dividing by half the maxval.  So to get the
+same result as we did above with \fB-nooffset\fP, the convolution
+matrix PNM image would have to look like this:
+
+.nf
+    P2
+    3 3
+    18
+    10 10 10
+    10 10 10
+    10 10 10
+
+.fi
+.PP
+To see how this works, do the above-mentioned offset: 10 - 18/2
+gives 1.  The normalization step divides by 18/2 = 9, which makes it
+1/9 - exactly what you want.  The equivalent matrix for 5x5 smoothing
+would have maxval 50 and be filled with 26.
+.PP
+Note that with maxval 18, the range of possible values is 0 to 18.
+After offset, that's -9 to 9, and after normalizing, the range is -1 to 1.
+.PP
+The convolution file will usually be a PGM, so that the same
+convolution gets applied to each color component.  However, if you
+want to use a PPM and do a different convolution to different
+colors, you can certainly do that.
+
+
+.UN otherconvol
+.SS Other Forms of Convolution
+.PP
+\fBpnmconvol\fP does only arithmetic, linear combination convolution.
+There are other forms of convolution that are especially useful in image
+processing.
+.PP
+\fBpgmmedian\fP does median filtering, which is a form of convolution
+where the output pixel value, rather than being a linear combination of the
+pixels in the window, is the median of a certain subset of them.
+.PP
+\fBpgmmorphconv\fP does dilation and erosion, which is like the median
+filter but the output value is the minimum or maximum of the values in the
+window.
+
+
+.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
+\&), \fBpnmconvol\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-matrix=\fP\fIconvolution_matrix\fP
+The value of the convolution matrix.  See
+.UR #matrixopt
+Convolution Matrix
+.UE
+\&.
+.sp
+You may not specify both this and \fB-matrixfile\fP.
+.sp
+This option was new in Netpbm 10.49 (December 2009).  Before
+that, use a PNM file for the convolution matrix.
+
+.TP
+\fB-matrixfile=\fP\fIfilename\fP
+This specifies that you are supplying the convolution matrix in
+a file and names that file.  See
+.UR #matrixfile
+Convolution Matrix
+.UE
+\&.
+.sp
+You may not specify both this and \fB-matrix\fP.
+.sp
+This option was new in Netpbm 10.49 (December 2009).  Before
+that, use a PNM file for the convolution matrix.
+
+.TP
+\fB-normalize\fP
+This option says to adjust the weights in your convolution matrix so they
+all add up to one.  You usually want them to add up to one so that the
+convolved result tends to have the same overall brightness as the input.  With
+\fB-normalize\fP, \fBpnmconvol\fP scales all the weights by the same factor
+to make the sum one.  It does this for each plane.
+.sp
+This can be quite convenient because you can just throw numbers into
+the matrix that have roughly the right relationship to each other and let
+\fBpnmconvol\fP do the work of normalizing them.  And you can adjust a matrix
+by raising or lowering certain weights without having to modify all the other
+weights to maintain normalcy.  And you can use friendly integers.
+.sp
+Example:
+
+.nf
+\f(CW
+    $ pnmconvol myimage.ppm -normalize -matrix=1,1,1;1,1,1;1,1,1
+\fP
+
+.fi
+.sp
+This is of course a basic 3x3 average, but without you having to
+specify 1/9 (.1111111) for each weight.
+.sp
+This option was new in Netpbm 10.50 (March 2010).  But before Netpbm 10.79
+(June 2017), it has no effect when you specify the convolution matrix via
+pseudo-PNM file.
+
+.TP
+\fB-bias=\fP\fIn\fP
+.sp
+This specifies an amount to add to the convolved value for each sample.
+.sp
+The purpose of this addition is normally to handle negative convolution
+results.  Because the convolution matrix can contain negative numbers, the
+convolved value for a pixel could be negative.  But Netpbm formats cannot
+contain negative sample values, so without any bias, such samples would get
+clipped to zero.  The bias allows the output image to retain the information,
+and a program that pocesses that output, knowing the bias value, could
+reconstruct the real convolved values.
+.sp
+For example, with \fBbias=100\fP, a sample whose convolved value is -5
+appears as 95 in the output, whereas a sample whose convolved value is 5
+appears as 105 in the output.
+.sp
+A typical value for the bias is half the maxval, allowing the same range on
+either side of zero.
+.sp
+If the sample value, after adding the bias, is still less than
+zero, \fBpnmconvol\fP clips it to zero.  If it exceeds the maxval of the
+output image, it clips it to the maxval.
+.sp
+The default is zero.
+.sp
+This option was new in Netpbm 10.68 (September 2014).
+
+.TP
+\fB-nooffset=\fP
+This is part of the obsolete PNM image method of specifying the
+convolution matrix.  See
+.UR #matrixpnm
+Convolution Matrix
+.UE
+\&.
+
+
+
+.UN history
+.SH HISTORY
+.PP
+The \fB-nooffset\fP option was new in Netpbm 10.23 (July 2004),
+making it substantially easier to specify a convolution matrix, but
+still hard.  In Netpbm 10.49 (December 2009), the PNM convolution
+matrix tyranny was finally ended with the \fB-matrix\fP and
+\fB-matrixfile\fP options.  In between, \fBpnmconvol\fP was broken
+for a while because the Netpbm library started enforcing the
+requirement that a sample value not exceed the maxval of the
+image.  \fBpnmconvol\fP used the Netpbm library to read the PNM
+convolution matrix file, but in the pseudo-PNM format
+that \fBpnmconvol\fP uses, a sample value sometimes has to exceed the
+maxval.
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmsmooth" (1)\c
+\&,
+.BR "pgmmorphconv" (1)\c
+\&,
+.BR "pgmmedian" (1)\c
+\&,
+.BR "pnmnlfilt" (1)\c
+\&,
+.BR "pgmkernel" (1)\c
+\&,
+.BR "pamgauss" (1)\c
+\&,
+.BR "pammasksharpen" (1)\c
+\&,
+.BR "pnmpad" (1)\c
+\&,
+.BR "pamcut" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN authors
+.SH AUTHORS
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+Modified 26 November 1994 by Mike Burns, \fIburns@chem.psu.edu\fP
+.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/pnmconvol.html
+.PP
\ No newline at end of file