diff options
Diffstat (limited to '')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man1/pamlookup.1 | 404 |
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 |