1 files changed, 370 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/pnmremap.1 b/upstream/mageia-cauldron/man1/pnmremap.1
new file mode 100644
index 00000000..515ef488
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pnmremap.1
@@ -0,0 +1,370 @@
+\
+.\" 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 "Pnmremap User Manual" 0 "13 November 2014" "netpbm documentation"
+
+.SH NAME
+pnmremap - replace colors in a PNM image with colors from another set
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmremap\fP
+
+\fB-mapfile=\fP\fIpalettefile\fP
+
+[\fB-floyd\fP|\fB-fs\fP|\fB-nfloyd\fP|\fB-nofs\fP]
+
+{[\fB-norandom\fP]|\fBrandomseed=\fP\fIn\fP}
+
+[\fB-firstisdefault\fP]
+
+[\fB-verbose\fP]
+
+[\fB-missingcolor=\fP\fIcolorspec\fP]
+
+[\fIpnmfile\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one to designate an option.  You
+may use either white space or an equals sign between an option name
+and its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmremap\fP replaces the colors in an input image with those
+from a palette you specify.  Where colors in the input are present in
+the palette, they just stay the same in the output.  But where the
+input contains a color that is not in the palette, \fBpnmremap\fP
+gives you these choices:
+
+
+.IP \(bu
+Choose the closest color from the palette.
+
+.IP \(bu
+Choose the first color from the palette.
+
+.IP \(bu
+Use a color specified by a command option (\fB-missing\fP).
+
+.IP \(bu
+Dither.  This means rather than mapping pixel by pixel,
+\fBpnmremap\fP uses colors from the palette to try to make
+multi-pixel regions of the output have the same average color as the
+input (for another kind of dithering, see \fBppmdither\fP).
+
+
+.PP
+Two reasons to use this program are: 1) you want to reduce the
+number of colors in the input image; and 2) you need to feed the image
+to something that can handle only certain colors.
+.PP
+To reduce colors, you can generate the palette with
+\fBpnmcolormap\fP.
+.PP
+By default, \fBpnmremap\fP maps an input color that is not in the
+palette to the closest color that \fIis\fP in the palette.  Closest
+means with the smallest Cartesian distance in the red, green, blue
+brightness space (smallest sum of the squares of the differences in
+red, green, and blue ITU-R Recommendation BT.709 gamma-adjusted
+intensities).
+.PP
+You can instead specify a single default color for \fBpnmremap\fP
+to use for any color in the input image that is not in the palette.
+Use the \fB-missing\fP option for this.
+.PP
+You can also specify that the first color in the palette image
+is the default.  Use the \fB-firstisdefault\fP option for this.
+.PP
+The palette is simply a PNM image.  The colors of the pixels in the
+image are the colors in the palette.  Where the pixels appear in the
+image, and the dimensions of the image, are irrelevant.  Multiple
+pixels of the same color are fine.  However, a palette image is
+typically a single row with one pixel per color.
+.PP
+If you specify \fB-missing\fP, the color you so specify is in
+the palette in addition to whatever is in the palette image.
+.PP
+For historical reasons, Netpbm sometimes calls the palette a
+"colormap." But it doesn't really map anything.
+\fBpnmremap\fP creates its own map, based on the palette, to map
+colors from the input image to output colors.
+
+.UN mismatch
+.SS Palette/Image Type Mismatch
+.PP
+In the simple case, the palette image is of the same depth (number
+of planes, i.e. number of components in each tuple (pixel)) as the
+input image and \fBpnmremap\fP just does a straightforward search of
+the palette for each input tuple (pixel).  In fact, \fBpnmremap\fP
+doesn't even care if the image is a visual image.
+.PP
+But what about when the depths differ?  In that case,
+\fBpnmremap\fP converts the input image (in its own memory) to match
+the palette and then proceeds as above.
+.PP
+There are only two such cases in which \fBpnmremap\fP knows how to
+do the conversion:  when one of them is tuple type RGB, depth 3, and the
+other is tuple type GRAYSCALE or BLACKANDWHITE, depth 1; and vice
+versa.
+.PP
+In any other case, \fBpnmremap\fP issues and error message and fails.
+.PP
+Note that as long as your input and palette images are PNM, they'll
+always fall into one of the cases \fBpnmremap\fP can handle.  There's an
+issue only if you're using some exotic PAM image.
+.PP
+Before Netpbm 10.27 (March 2005), \fBpnmremap\fP could not handle
+the case of a palette of greater depth than the input image.  (It would
+issue an error message and fail in that case).  You can use \fBppmtoppm\fP
+to increase the depth of the input image to work around this limitation.
+.PP
+In any case, the output image has the same tuple type and depth as
+the palette image.
+
+.UN multiple
+.SS Multiple Image Stream
+.PP
+\fBpnmremap\fP handles a multiple image input stream, producing a
+multiple image output stream.  The input images need not be similar in
+any way.
+.PP
+Before Netpbm 10.30 (October 2005), \fBpnmremap\fP ignored any image
+after the first.
+
+
+.UN example
+.SS Examples
+
+.nf
+pnmcolormap testimg.ppm 256 >palette.ppm
+
+pnmremap -map=palette.ppm testimg.ppm >reduced_testimg.ppm
+
+.fi
+.PP
+To limit colors to a certain set, a typical example is to create an
+image for posting on the World Wide Web, where different browsers know
+different colors.  But all browsers are supposed to know the 216
+"web safe" colors which are essentially all the colors you
+can represent in a PPM image with a maxval of 5.  So you can do this:
+
+.nf
+pamseq 3 5 >websafe.pam
+
+pnmremap -map=websafe.pam testimg.ppm >websafe_testimg.ppm
+
+.fi
+.PP
+Another useful palette is one for the 8 color IBM TTL color set, which
+you can create with
+.nf
+pamseq 3 1 >ibmttl.pam
+
+.fi
+.PP
+If you want to quantize one image to use the colors in another one,
+just use the second one as the palette.  You don't have to reduce it
+down to only one pixel of each color, just use it as is.
+.PP
+The output image has the same type and maxval as the palette image.
+
+.UN parameters
+.SH PARAMETERS
+.PP
+There is one parameter, which is required: The file specification of
+the input PNM file.
+
+
+.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
+\&), \fBpnmremap\fP recognizes the following
+command line options:
+
+
+
+.TP
+\fB-mapfile=\fP\fIpalettefilename\fP
+This names the file that contains the palette image.
+.sp
+This option is mandatory.
+
+.TP
+\fB-floyd\fP
+.TP
+\fB-fs\fP
+.TP
+\fB-nofloyd\fP
+.TP
+\fB-nofs\fP
+These options determine whether \fBpnmremap\fP does Floyd-Steinberg
+dithering.  Without Floyd-Steinberg, \fBpnmremap\fP selects the output color
+of a pixel based on the color of only the corresponding input pixel.  With
+Floyd-Steinberg, \fBpnmremap\fP considers regions of pixels such that the
+average color of a region is the same in the output as in the input.  The
+dithering effect appears as a dot pattern up close, but from a distance, the
+dots blend so that you see more colors than are present in the color map.
+.sp
+As an example, if your color map contains only black and white, and
+the input image has 4 adjacent pixels of gray, \fBpnmremap\fP with
+Floyd-Steinberg would generate output pixels black, white, black, white,
+which from a distance looks gray.  But without Floyd-Steinberg,
+\fBpnmremap\fP would generate 4 white pixels, white being the single-pixel
+approximation of gray.
+.sp
+Floyd-Steinberg gives vastly better results on images where
+unmodified quantization has banding or other artifacts, especially
+when going to a small number of colors such as the above IBM set.
+However, it does take substantially more CPU time.
+.sp
+\fB-fs\fP is a synonym for \fB-floyd\fP.  \fB-nofs\fP is a
+synonym for \fB-nofloyd\fP.
+.sp
+The default is \fB-nofloyd\fP.
+.sp
+Before Netpbm 10.46 (March 2009), dithering doesn't work quite as you
+expect if the color map has a lower maxval than the input.  \fBpnmremap\fP
+reduces the color resolution to the color map's maxval before doing any
+dithering, so the dithering does not have the effect of making the image,
+at a distance, appear to have the original maxval.  In current Netpbm, it
+does.
+
+.TP
+\fB-norandom\fP
+This option affects a detail of the Floyd-Steinberg dithering process.
+It has no effect if you aren't doing Floyd-Steinberg dithering.
+.sp
+By default, \fBpnmremap\fP initializes the error propagation
+accumulator to random values to avoid the appearance of unwanted
+patterns.  This is an extension of the original Floyd-Steinberg
+algorithm.
+.sp
+A drawback of this is that the same \fBpnmremap\fP on the same
+input produces slightly different output every time, which makes
+comparison difficult.
+.sp
+With \fB-norandom\fP, \fBpnmremap\fP initializes the error
+accumulators to zero and the output is completely predictable.
+.sp
+Alternatively, you can use \fB-randomseed\fP to get randomization
+across the image, but still have repeatable results.
+.sp
+You cannot specify this along with \fB-randomseed\fP.
+.sp
+\fB-norandom\fP was new in Netpbm 10.39 (June 2007).
+
+
+.TP
+\fB-randomseed=\fP\fIn\fP
+This option affects a detail of the Floyd-Steinberg dithering process.
+It has no effect if you aren't doing Floyd-Steinberg dithering.
+.sp
+This option supplies the seed for the random number generator used in the
+randomization process described in the explanation of the \fB-norandom\fP
+option.  If you run \fBpnmremap\fP twice with the same \fB-randomseed\fP
+value, you will get identical results.
+.sp
+If you do not specify \fB-randomseed\fP, \fBpnmremap\fP chooses a seed
+at random, adding another level of randomness to the dithering.
+.sp
+You cannot specify this along with \fB-norandom\fP.
+.sp
+This option was new in Netpbm 10.82 (March 2018).
+  
+
+.TP
+\fB-firstisdefault\fP
+This tells \fBpnmremap\fP to map any input color that is not in
+the palette to the first color in the palette (the color of the pixel
+in the top left corner of the palette image)
+.sp
+See 
+.UR #description
+DESCRIPTION
+.UE
+\&.
+.sp
+If you specify \fB-firstisdefault\fP, the maxval of your input
+must match the maxval of your palette image.
+
+.TP
+\fB-missingcolor=\fP\fIcolorspec\fP
+This specifies the default color for \fBpnmremap\fP to map to a
+color in the input image that isn't in the palette.  \fIcolor\fP may
+or may not be in the palette image; it is part of the palette
+regardless.
+.sp
+\fIcolorspec\fP is as described for
+the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+If you specify \fB-missingcolor\fP, the maxval of your input must
+match the maxval of your palette image.
+
+.TP
+\fB-verbose\fP
+Display helpful messages about the mapping process.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmcolormap" (1)\c
+\&,
+.BR "pamlookup" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "ppmquantall" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "ppmdither" (1)\c
+\&,
+.BR "ppmquant" (1)\c
+\&,
+.BR "pamseq" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&
+
+.UN history
+.SH HISTORY
+.PP
+\fBpnmremap\fP first appeared in Netpbm 9.23 (January 2002).
+Before that, its function was available only as part of the function
+of \fBpnmquant\fP (which was derived from the much older
+\fBppmquant\fP).  Color quantization really has two main subfunctions, so
+Netpbm 9.23 split it out into two separate programs:
+\fBpnmcolormap\fP and \fBpnmremap\fP and then Netpbm 9.24 replaced
+\fBpnmquant\fP with a program that simply calls \fBpnmcolormap\fP and
+\fBpnmremap\fP.
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.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/pnmremap.html
+.PP
+\ No newline at end of file