diff options
Diffstat (limited to 'pnmcolormap.html')
| -rw-r--r-- | pnmcolormap.html | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/pnmcolormap.html b/pnmcolormap.html new file mode 100644 index 00000000..a7752d18 --- /dev/null +++ b/pnmcolormap.html @@ -0,0 +1,229 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML><HEAD><TITLE>Pnmcolormap User Manual</TITLE></HEAD> +<BODY> +<H1>pnmcolormap</H1> +Updated: 23 October 2005 +<BR> +<A HREF="#index">Table Of Contents</A> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +pnmcolormap - create quantization color map for a Netpbm image + +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<B>pnmcolormap</B> + +[<B>-center</B>|<B>-meancolor</B>|<B>-meanpixel</B>] + +[<B>-spreadbrightness</B>|<B>-spreadluminosity</B>] + +[<B>-sort</B>] + +[<B>-square</B>] + +<I>ncolors</I>|<B>all</B> + +[<I>pnmfile</I>] + +<P>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. + +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<p>This program is part of <a href="index.html">Netpbm</a>. + +<p><b>pnmcolormap</b> reads a PNM or PAM image as input, chooses +<I>ncolors</I> colors to best represent the image and writes a PNM +color map defining them as output. A PAM image may actually contain +tuples of any kind, but <b>pnmcolormap</b>'s concept of the tuple values +that best represent the ones present in the image may not make sense if +the tuple type isn't RGB or GRAYSCALE. The design of the program, and +the rest of this manual, assumes the tuples represent colors. + +<P>You can use this map as input to <B>pnmremap</B> on the same input +image to quantize the colors in that image, I.e. produce a similar +image with fewer colors. <B>pnmquant</B> does both the <B>pnmcolormap</B> +and <B>pnmremap</B> steps for you. + +<P>A PNM colormap is a PNM image of any dimensions that contains at +least one pixel of each color in the set of colors it represents. The +ones <b>pnmcolormap</b> generates have exactly one pixel of each color, +except where padding is necessary with the <b>-square</b> option. + +<P>The quantization method is Heckbert's "median cut". +See <a href="#quant">QUANTIZATION METHOD</a>. + +<P>The output image is of the same format (PBM, PGM, PPM, PAM) as the +input image. Note that a colormap of a PBM image is not very +interesting. + +<P>The colormap generally has the same maxval as the input image, but +<B>pnmcolormap</B> may reduce it if there are too many colors in the +input, as part of its quantization algorithm. + +<p><b>pnmcolormap</b> works on a multi-image input stream. In that +case, it produces one colormap that applies to all of the colors in +all of the input images. All the images must have the same format, +depth, and maxval (but may have different height and width). This is +useful if you need to quantize a bunch of images that will form a +movie or otherwise be used together -- you generally want them all to +draw from the same palette, whereas computing a colormap separately +from each image would make the same color in two images map to +different colors. Before Netpbm 10.31 (December 2005), <b>pnmcolormap</b> +ignored any image after the first. + +<P>If you want to create a colormap without basing it on the colors in +an input image, <B>pamseq</B>, <b>ppmmake</b>, and <b>pnmcat</b> can +be useful. + +<A NAME="lbAE"> </A> +<H2>PARAMETERS</H2> + +<P>The single parameter, which is required, is the number of colors you want +in the output colormap. <B>pnmcolormap</B> may produce a color map with slightly fewer colors than that. You may +specify <B>all</B> to get a colormap of every color in the input image (no quantization). + +<A NAME="options"> </A> +<H2>OPTIONS</H2> + +<DL COMPACT> +<DT><B>-sort</B> + +<DD>This option causes the output colormap to be sorted by the red +component intensity, then the green, then the blue in ascending order. +This is an insertion sort, so it is not very fast on large colormaps. +Sorting is useful because it allows you to compare two sets of colors. + +<DT><B>-square</B> + +<DD>By default, <B>pnmcolormap</B> produces as the color map a PPM +image with one row and one column for each color in the colormap. +This option causes <B>pnmcolormap</B> instead to produce a PPM image +that is within one row or column of being square, with the last pixel +duplicated as necessary to create a number of pixels which is such an +almost-perfect square. + +<DT><B>-verbose</B> + +<DD>This option causes <B>pnmcolormap</B> to display messages to +Standard Error about the quantization. <DT><B>-center</B> + +<DT><B>-meancolor</B> + +<DT><B>-meanpixel</B> + +<DT><B>-spreadbrightness</B> + +<DT><B>-spreadluminosity</B> + +<DD>These options control the quantization algorithm. See <a +href="#quant">QUANTIZATION METHOD</a>. + +</DL> + + +<A NAME="quant"> </A> +<H2>QUANTIZATION METHOD</H2> + +<P>A quantization method is a way to choose which colors, being fewer +in number than in the input, you want in the output. +<B>pnmcolormap</B> uses Heckbert's "median cut" quantization +method. + +<P>This method involves separating all the colors into +"boxes," each holding colors that represent about the same +number of pixels. You start with one box and split boxes in two until +the number of boxes is the same as the number of colors you want in +the output, and choose one color to represent each box. + +<P>When you split a box, you do it so that all the colors in one +sub-box are "greater" than all the colors in the other. +"Greater," for a particular box, means it is brighter in the +color component (red, green, blue) which has the largest spread in +that box. <B>pnmcolormap</B> gives you two ways to define +"largest spread.": 1) largest spread of brightness; 2) +largest spread of contribution to the luminosity of the color. +E.g. red is weighted much more than blue. Select among these with the +<B>-spreadbrightness</B> and <B>-spreadluminosity</B> options. The +default is <B>-spreadbrightness</B>. + +<P><B>pnmcolormap</B> provides three ways of choosing a color to +represent a box: 1) the center color - the color halfway between the +greatest and least colors in the box, using the above definition of +"greater"; 2) the mean of the colors (each component +averaged separately by brightness) in the box; 3) the mean weighted by +the number of pixels of a color in the image. + +<P>Note that in all three methods, there may be colors in the output +which do not appear in the input at all. + +<P>Select among these with the <B>-center</B>, <B>-meancolor</B>, and +<B>-meanpixel</B> options. The default is <B>-center</B>. + +<A NAME="lbAG"> </A> +<H2>REFERENCES</H2> + +"Color Image Quantization for Frame Buffer Display" by Paul Heckbert, +SIGGRAPH '82 Proceedings, page 297. + +<A NAME="lbAH"> </A> +<H2>SEE ALSO</H2> + +<B><A HREF="pnmremap.html">pnmremap</A></B>, +<B><A HREF="pnmquant.html">pnmquant</A></B>, +<B><A HREF="ppmquantall.html">ppmquantall</A></B>, +<B><A HREF="pamdepth.html">pamdepth</A></B>, +<B><A HREF="ppmdither.html">ppmdither</A></B>, +<B><A HREF="pamseq.html">pamseq</A></B>, +<B><A HREF="ppmmake.html">ppmmake</A></B>, +<B><A HREF="pnmcat.html">pnmcat</A></B>, +<B><A HREF="ppm.html">ppm</A></B> + +<A NAME="history"> </A> +<H2>HISTORY</H2> + +<P>Before Netpbm 10.15 (April 2003), <b>pnmcolormap</b> used a lot +more memory for large images because it kept the entire input image in +memory. Now, it processes it a row at a time, but because it +sometimes must make multiple passes through the image, it first copies +the input into a temporary seekable file if it is not already in a seekable +file. + +<p><b>pnmcolormap</b> first appeared in Netpbm 9.23 (January 2002). +Before that, its function was available only as part of the function +of <b>pnmquant</b> (which was derived from the much older +<b>ppmquant</b>). Color quantization really has two main subfunctions, so +Netpbm 9.23 split it out into two separate programs: +<b>pnmcolormap</b> and <b>pnmremap</b> and then Netpbm 9.24 replaced +<b>pnmquant</b> with a program that simply calls <b>pnmcolormap</b> and +<b>pnmremap</b>. + +<A NAME="lbAI"> </A> +<H2>AUTHOR</H2> + +Copyright (C) 1989, 1991 by Jef Poskanzer. + + +<HR> +<A NAME="index"> </A> +<H2>Table Of Contents</H2> +<UL> +<LI><A HREF="#lbAB">NAME</A> +<LI><A HREF="#lbAC">SYNOPSIS</A> +<LI><A HREF="#lbAD">DESCRIPTION</A> +<LI><A HREF="#lbAE">PARAMETERS</A> +<LI><A HREF="#options">OPTIONS</A> +<LI><A HREF="#quant">QUANTIZATION METHOD</A> +<LI><A HREF="#lbAG">REFERENCES</A> +<LI><A HREF="#lbAH">SEE ALSO</A> +<LI><A HREF="#history">HISTORY</A> +<LI><A HREF="#lbAI">AUTHOR</A> +</UL> +</BODY> +</HTML> |