Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 404 insertions, 0 deletions

diff --git a/upstream/opensuse-tumbleweed/man1/pamlookup.1 b/upstream/opensuse-tumbleweed/man1/pamlookup.1
new file mode 100644
index 00000000..047fb145
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man1/pamlookup.1
@@ -0,0 +1,404 @@
+\
+.\" 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 "Pamlookup User Manual" 0 "25 July 2015" "netpbm documentation"
+
+.SH NAME
+pamlookup - map an image to a new image by using it as indices into a table
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamlookup\fP
+\fB-lookupfile=\fP\fIlookupfile\fP
+[\fB-byplane\fP]
+\fB-missingcolor=\fP\fIcolor\fP
+[\fB-fit\fP]
+\fIindexfile\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
+\fBpamlookup\fP takes a two dimensional array of indices and a lookup
+table as input.  For each position in the index array, it looks up the index
+in the lookup table and places the result of the lookup in the output image.
+
+There are two ways of indexing the lookup table: \fIwhole tuple\fP and
+\fIby plane\fP.  The \fB-byplane\fP option controls which \fBpamlookup\fP
+does.
+.PP
+In the simplest form of whole tuple indexing, each index in the index array
+is a single whole number and the lookup table associates a whole tuple with
+each possible whole number index.  So for example, the index array might have
+at Row 2, Column 9 the value 23.  The lookup table might associate the tuple
+(1,2,3) with the value 23.  In that case, the output image contains the tuple
+(1,2,3) at Row 2, Column 9.
+.PP
+In a more complex form of whole tuple indexing, each index in the index
+array is an ordered pair of whole numbers and the lookup table associates a
+whole tuple with each possible ordered pair index.  Modifying the example
+above, the index value could be (23, 5) instead of 23.
+.PP
+With whole tuple indexing, the output thus has the same width and height as
+the index image, and tuple depth and type and maxval are determined by the
+lookup table.
+.PP
+With whole tuple indexing, if the index image has depth 1, its sample
+values are single whole number indices.  If the index image has depth greater
+than 1, its tuples are ordered pair indices composed of the first and second
+sample in the tuple.
+.PP
+In by-plane indexing, the index image contains whole number indices.  Each
+sample in the index image is an index.  The lookup table maps each whole
+number index to another whole number.  \fBpamlookup\fP looks up the sample at
+each row, column, and plane in the index image in the lookup table and uses
+the resulting whole number as the sample value for the same row, column, and
+plane in the output.
+.PP
+With by-plane indexing, the output thus has the same dimensions as the
+index image an the same maxval as the lookup image.
+
+
+.UN lookupimage
+.SS The Lookup Table Image
+.PP
+The lookup table is a PAM or PNM image.  If the index image
+contains whole number indices, the lookup image is a single row and
+the index is a column number.  The lookup result is the value of the
+tuple or pixel at the indicated column in the one row in the lookup
+table.  If the index image contains ordered pair indices, the first
+element of the ordered pair is a row number and the second element of
+the ordered pair is a column number.  The lookup result is the value
+of the tuple or pixel at the indicated row and column in the lookup
+table.
+.PP
+The width of the lookup image should normally be the maxval of the index
+image plus one, so that each possible index sample value corresponds to one
+entry in the lookup table.  There are two ways \fBpamlookup\fP deals
+with a lookup image that does not have such a width: 
+
+
+.IP \(bu
+Scale the lookup image to the required width.  \fBpamlookup\fP always
+does this with by plane indexing, and with whole tuple indexing, does it when
+you specify \fB-fit\fP.
+
+.IP \(bu
+Use a default value for indices that exceed the width of the lookup image
+and ignore lookup image columns beyond the maxval of the index
+image.  \fBpamlookup\fP does this with whole tuple indexing when you don't
+specify \fB-fit\fP.
+.sp
+You specify the default value with a \fB-missingcolor\fP option; it defaults
+to the value from the top left corner of the lookup image.
+
+.PP
+With ordered pair indexes (which implies whole tuple indexing), the same
+rule applies to the height of the index image as to the width.
+.PP
+The mandatory \fB-lookupfile\fP option identifies the file containing the
+lookup table image.  \fB-\fP means Standard Input.  It won't work if both the
+index image file and lookup table file are Standard Input.
+.PP
+You can use \fBppmmake\fP and \fBpamcat\fP to create a lookup table file.
+
+
+.UN wholetuple
+.SS Example - Whole Tuple Indexing
+.PP
+Here is an example of \fBpamlookup\fP's function with whole
+tuple indexing (\fB-byplane\fP not specified).
+.PP
+Consider an index image consisting of a 3x2x1 PAM as follows:
+
+.TS
+l l l.
+0	1	0
+2	2	2
+.TE
+
+and a lookup table consisting of a 3x1 PPM image as follows:
+
+.TS
+l l l.
+red	yellow	beige
+.TE
+
+The lookup table above says Index 0 corresponds to the color red,
+Index 1 corresponds to yellow, and Index 2 corresponds to beige.  The output
+of \fBpamlookup\fP is the following PPM image:
+
+.TS
+l l l.
+red	yellow	red
+beige	beige	beige
+.TE
+.PP
+Now let's look at an example of the more complex case where the
+indices are ordered pairs of whole numbers instead of whole numbers.
+Our index image will be this 3x2x2 PAM image:
+
+.TS
+l l l.
+(0,0)	(0,1)	(0,0)
+(1,1)	(1,0)	(0,0)
+.TE
+
+Our lookup table for the example will be this two dimensional PPM:
+
+.TS
+l l l.
+red	yellow	red
+black	green	red
+.TE
+
+
+.UN byplane
+.SS Example - By Plane Indexing
+.PP
+Here is an example of \fBpamlookup\fP's function with by plane
+tuple indexing (\fB-byplane\fP specified).
+.PP
+Consider an index image consisting of a 3x2x3 PAM as follows:
+
+.TS
+l l l.
+(0,0,0)	(1,0,0)	(2,0,0)
+(2,2,0)	(2,0,2)	(2,0,0)
+.TE
+
+and a lookup table consisting of a 3x1x1 PAM image with maxval 7 as follows:
+
+.TS
+l l l.
+3	4	7
+.TE
+
+The lookup table above says Index 0 corresponds to the sample value 3, Index 1
+corresponds to 4, and Index 2 corresponds to 7.  The output of
+\fBpamlookup\fP is the following 3x2x3 PAM image:
+
+.TS
+l l l.
+(3,3,3)	(4,3,3)	(7,3,3)
+(7,7,3)	(7,3,7)	(7,3,3)
+.TE
+
+
+.UN misc
+.SS Miscellaneous
+.PP
+The \fIindexfile\fP argument identifies the file containing the index PAM
+or PNM image.  \fB-\fP means Standard Input.
+It won't work if both the
+index image file and lookup table file are Standard Input.
+
+The output image goes to Standard Output.
+.PP
+If you want to use two separate 1-plane images as indices (so that your
+output reflects the combination of both inputs), use \fBpamstack\fP to combine
+the two into one two-plane image (and use a 2-dimensional lookup table image).
+
+
+.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
+\&), \fBpamlookup\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-lookupfile=\fP\fIlookupfile\fP
+\fIlookupfile\fP names the file that contains the PAM or PNM
+image that is the lookup table.  This option is mandatory.
+
+.TP
+\fB-byplane\fP
+This options selects by plane indexing.  The default is whole tuple
+indexing.
+.sp
+This option was new in Netpbm 10.72 (September 2015).  Before that, there
+is no by plane indexing.
+
+.TP
+\fB-missingcolor=\fP\fIcolor\fP
+This option is meaningful only if the lookup image (and therefore the 
+output) is a PNM image.  \fIcolor\fP specifies the color that 
+is to go in the output wherever the index from the input is not present
+in the lookup table (not present means the index exceeds the dimensions
+of the lookup image -- e.g. index is 100 but the lookup image is a 50 x 1
+PPM).
+.sp
+If you don't specify this option or \fB-fit\fP, \fBpamlookup\fP
+uses the value from the top left corner of the lookup image whenever
+an index exceeds the dimensions of the lookup image.
+.sp
+Specify the color (\fIcolor\fP) as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+Another way to deal with a too-small lookup image is to use the 
+\fB-fit\fP option.
+.sp
+This option has no effect if you also specify \fB-fit\fP or
+\fB-byplane\fP.
+
+.TP
+\fB-fit\fP
+This option says to shrink or expand the lookup image as necessary
+to fit the indices present in the index image, per the index image's
+maxval.  For example, if your index image has a single plane and a
+maxval of 255 and your lookup image is 1 row of 10 columns,
+\fBpamlookup\fP stretches your lookup image to 255 columns before
+doing the lookups.  \fBpamlookup\fP does the stretching (or
+shrinking) with the
+.BR "\fBpamscale\fP" (1)\c
+\&
+program.
+.sp
+When you use \fB-fit\fP, \fBpamlookup\fP never fails or warns you
+because of invalid lookup image dimensions, and the \fB-missingcolor\fP
+option has no effect.
+.sp
+\fB-fit\fP has no effect when you specify \fB-byplane\fP.
+\fBpamlookup\fP always has the behavior requested by \fB-fit\fP when it does
+by plane indexing.
+
+
+
+.UN examples
+.SH EXAMPLES
+
+.SS Example: rainfall map
+.PP
+Say you have a set of rainfall data in a single plane PAM image.
+The rows and columns of the PAM indicate latitude and longitude.  The
+sample values are the annual rainfall in (whole) centimeters.  The highest
+rainfall value in the image is 199 centimeters.  The image is in the file
+rainfall.pam.
+.PP
+You want to produce a PPM rainfall map with green for the wettest places,
+red for the driest, and other colors in between.
+.PP
+First, compose a lookup table image, probably with a graphical editor
+and the image blown way up so you can work with individual pixels.  The
+image must have a single row and 200 columns.  Make the leftmost pixel 
+red and the rightmost pixel green and choose appropriate colors in between.
+Call it colorkey.ppm.
+
+.nf
+\f(CW
+    pamlookup rainfall.pam -lookupfile=colorkey.ppm >rainfallmap.ppm
+\fP
+
+.fi
+.PP
+Now lets say you're too lazy to type in 200 color values and nobody really
+cares about the places that have more than 99 centimeters of annual 
+rainfall.  In that case, just make colorkey.ppm 100 columns wide and do
+this:
+
+.nf
+\f(CW
+    pamlookup rainfall.ppm -lookupfile=colorkey.ppm -missingcolor=black \e
+       >rainfallmap.ppm
+\fP
+
+.fi
+
+Now if there are areas that get more than 100 centimeters of rainfall, they
+will just show up black in the output.
+
+.SS Example: graphical diff
+.PP
+Say you want to compare two PBM (black and white) images visually.  Each
+consists of black foreground pixels on a white background.  You want to
+create an image that contains background where both images contain background
+and foreground where both images contain foreground.  But where Image 1
+has a foreground pixel and Image 2 does not, you want red in the output;
+where Image 2 has a foreground pixel and Image 1 does not, you want green.
+.PP
+First, we create a single image that contains the information from both
+input PBMs:
+
+.nf
+\f(CW
+    pamstack image1.pbm image2.pbm >bothimages.pam
+\fP
+
+.fi
+
+Note that this image has 1 of 4 possible tuple values at each location:
+(0,0), (0,1), (1,0), or (1,1).
+.PP
+Now, we create a lookup table that we can index with those 4 values:
+
+.nf
+\f(CW
+    ppmmake white 1 1 >white.ppm
+    ppmmake black 1 1 >black.ppm
+    ppmmake red   1 1 >red.ppm
+    ppmmake green 1 1 >green.ppm
+    pamcat -leftright black.ppm red.ppm   >blackred.ppm
+    pamcat -leftright green.ppm white.ppm >greenwhite.ppm
+    pamcat -topbottom blackred.ppm greenwhite.ppm >lookup.ppm
+\fP
+
+.fi
+.PP
+Finally, we look up the indices from our index in our lookup table and
+produce the output:
+
+.nf
+\f(CW
+    pamlookup bothimages.ppm -lookupfile=lookup.ppm >imagediff.ppm
+\fP
+
+.fi
+
+     
+.UN seealso
+.SH SEE ALSO
+.BR "pamunlookup" (1)\c
+\&,
+.BR "pnmremap" (1)\c
+\&,
+.BR "ppmmake" (1)\c
+\&,
+.BR "pamcat" (1)\c
+\&,
+.BR "pamstack" (1)\c
+\&,
+.BR "pnm" (5)\c
+\&,
+.BR "pam" (5)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamlookup\fP was new in Netpbm 10.13 (December 2002).
+.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/pamlookup.html
+.PP
\ No newline at end of file