diff options
Diffstat (limited to 'upstream/opensuse-leap-15-6/man1/pnmremap.1')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man1/pnmremap.1 | 337 |
1 files changed, 337 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man1/pnmremap.1 b/upstream/opensuse-leap-15-6/man1/pnmremap.1 new file mode 100644 index 00000000..d4eb11b8 --- /dev/null +++ b/upstream/opensuse-leap-15-6/man1/pnmremap.1 @@ -0,0 +1,337 @@ +\ +.\" 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] + +[\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 + + + +.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 +\fB-norandom\fP was new in Netpbm 10.39 (June 2007). + + +.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 libppm.html#colorname +argument of the \fBppm_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" (5)\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 |