| 1 |
\ |
| 2 |
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. |
| 3 |
.\" Do not hand-hack it! If you have bug fixes or improvements, please find |
| 4 |
.\" the corresponding HTML page on the Netpbm website, generate a patch |
| 5 |
.\" against that, and send it to the Netpbm maintainer. |
| 6 |
.TH "Pnmcolormap User Manual" 1 "21 February 2023" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
|
| 10 |
pnmcolormap - create quantization color map for a Netpbm image |
| 11 |
|
| 12 |
.UN synopsis |
| 13 |
.SH SYNOPSIS |
| 14 |
|
| 15 |
\fBpnmcolormap\fP |
| 16 |
|
| 17 |
[\fB-center\fP|\fB-meancolor\fP|\fB-meanpixel\fP] |
| 18 |
|
| 19 |
[\fB-spreadbrightness\fP|\fB-spreadluminosity\fP] |
| 20 |
|
| 21 |
[\fB-splitpixelct\fP|\fB-splitcolorct\fP|\fB-splitspread\fP] |
| 22 |
|
| 23 |
[\fB-sort\fP] |
| 24 |
|
| 25 |
[\fB-square\fP] |
| 26 |
|
| 27 |
[\fB-verbose\fP] |
| 28 |
|
| 29 |
[\fB-debug\fP] |
| 30 |
|
| 31 |
\fIncolors\fP|\fBall\fP |
| 32 |
|
| 33 |
[\fIpnmfile\fP] |
| 34 |
|
| 35 |
.UN description |
| 36 |
.SH DESCRIPTION |
| 37 |
.PP |
| 38 |
This program is part of |
| 39 |
.BR "Netpbm" (1)\c |
| 40 |
\&. |
| 41 |
.PP |
| 42 |
\fBpnmcolormap\fP reads a PNM or PAM image as input, chooses |
| 43 |
\fIncolors\fP colors to best represent the image and writes a PNM |
| 44 |
color map defining them as output. A PAM image may actually contain |
| 45 |
tuples of any kind, but \fBpnmcolormap\fP's concept of the tuple values |
| 46 |
that best represent the ones present in the image may not make sense if |
| 47 |
the tuple type isn't RGB or GRAYSCALE. The design of the program, and |
| 48 |
the rest of this manual, assumes the tuples represent colors. |
| 49 |
.PP |
| 50 |
You can use this map as input to \fBpnmremap\fP on the same input |
| 51 |
image to quantize the colors in that image, I.e. produce a similar |
| 52 |
image with fewer colors. \fBpnmquant\fP does both the \fBpnmcolormap\fP |
| 53 |
and \fBpnmremap\fP steps for you. |
| 54 |
.PP |
| 55 |
A PNM colormap is a PNM image of any dimensions that contains at |
| 56 |
least one pixel of each color in the set of colors it represents. The |
| 57 |
ones \fBpnmcolormap\fP generates have exactly one pixel of each color, |
| 58 |
except where padding is necessary with the \fB-square\fP option. |
| 59 |
.PP |
| 60 |
The quantization method is Heckbert's "median cut". |
| 61 |
See |
| 62 |
.UR #quant |
| 63 |
QUANTIZATION METHOD |
| 64 |
.UE |
| 65 |
\&. |
| 66 |
.PP |
| 67 |
The output image is of the same format (PBM, PGM, PPM, PAM) as the |
| 68 |
input image. Note that a colormap of a PBM image is not very |
| 69 |
interesting. |
| 70 |
.PP |
| 71 |
The colormap generally has the same maxval as the input image, but |
| 72 |
\fBpnmcolormap\fP may reduce it if there are too many colors in the |
| 73 |
input, as part of its quantization algorithm. |
| 74 |
.PP |
| 75 |
\fBpnmcolormap\fP works on a multi-image input stream. In that |
| 76 |
case, it produces one colormap that applies to all of the colors in |
| 77 |
all of the input images. All the images must have the same format, |
| 78 |
depth, and maxval (but may have different height and width). This is |
| 79 |
useful if you need to quantize a bunch of images that will form a |
| 80 |
movie or otherwise be used together -- you generally want them all to |
| 81 |
draw from the same palette, whereas computing a colormap separately |
| 82 |
from each image would make the same color in two images map to |
| 83 |
different colors. Before Netpbm 10.31 (December 2005), \fBpnmcolormap\fP |
| 84 |
ignored any image after the first. |
| 85 |
.PP |
| 86 |
If you want to create a colormap without basing it on the colors in |
| 87 |
an input image, \fBpamseq\fP, \fBppmmake\fP, and \fBpamcat\fP can |
| 88 |
be useful. |
| 89 |
|
| 90 |
.UN parameters |
| 91 |
.SH PARAMETERS |
| 92 |
.PP |
| 93 |
The single parameter, which is required, is the number of colors you want |
| 94 |
in the output colormap. \fBpnmcolormap\fP may produce a color map with |
| 95 |
slightly fewer colors than that. You may specify \fBall\fP to get a colormap |
| 96 |
of every color in the input image (no quantization). When you specify |
| 97 |
\fBall\fP, the function is essentially the same as that of \fBppmhist |
| 98 |
-map\fP. \fBppmhist\fP is much older. |
| 99 |
|
| 100 |
|
| 101 |
.UN options |
| 102 |
.SH OPTIONS |
| 103 |
.PP |
| 104 |
In addition to the options common to all programs based on libnetpbm |
| 105 |
(most notably \fB-quiet\fP, see |
| 106 |
.UR index.html#commonoptions |
| 107 |
Common Options |
| 108 |
.UE |
| 109 |
\&), \fBpnmcolormap\fP recognizes the following |
| 110 |
command line options: |
| 111 |
.PP |
| 112 |
All options can be abbreviated to their shortest unique prefix. You |
| 113 |
may use two hyphens instead of one to designate an option. You may |
| 114 |
use either white space or an equals sign between an option name and |
| 115 |
its value. |
| 116 |
|
| 117 |
|
| 118 |
.TP |
| 119 |
\fB-sort\fP |
| 120 |
This option causes the output colormap to be sorted by the red |
| 121 |
component intensity, then the green, then the blue in ascending order. |
| 122 |
This is an insertion sort, so it is not very fast on large colormaps. |
| 123 |
Sorting is useful because it allows you to compare two sets of colors. |
| 124 |
|
| 125 |
.TP |
| 126 |
\fB-square\fP |
| 127 |
By default, \fBpnmcolormap\fP produces as the color map a PPM |
| 128 |
image with one row and with one column for each color in the colormap. |
| 129 |
This option causes \fBpnmcolormap\fP instead to produce a PPM image |
| 130 |
that is within one row or column of being square, with the last pixel |
| 131 |
duplicated as necessary to create a number of pixels which is such an |
| 132 |
almost-perfect square. |
| 133 |
|
| 134 |
.TP |
| 135 |
\fB-verbose\fP |
| 136 |
This option causes \fBpnmcolormap\fP to display messages to |
| 137 |
Standard Error about the quantization..TP |
| 138 |
\fB-center\fP |
| 139 |
|
| 140 |
.TP |
| 141 |
\fB-debug\fP |
| 142 |
This option causes \fBpnmcolormap\fP to display messages to |
| 143 |
Standard Error about internal workings. |
| 144 |
|
| 145 |
.TP |
| 146 |
\fB-center\fP |
| 147 |
|
| 148 |
.TP |
| 149 |
\fB-meancolor\fP |
| 150 |
|
| 151 |
.TP |
| 152 |
\fB-meanpixel\fP |
| 153 |
|
| 154 |
.TP |
| 155 |
\fB-spreadbrightness\fP |
| 156 |
|
| 157 |
.TP |
| 158 |
\fB-spreadluminosity\fP |
| 159 |
|
| 160 |
.TP |
| 161 |
\fB-splitpixelct\fP |
| 162 |
|
| 163 |
.TP |
| 164 |
\fB-splitcolorct\fP |
| 165 |
|
| 166 |
.TP |
| 167 |
\fB-splitspread\fP |
| 168 |
These options control the quantization algorithm. See |
| 169 |
.UR #quant |
| 170 |
QUANTIZATION METHOD |
| 171 |
.UE |
| 172 |
\&. |
| 173 |
|
| 174 |
|
| 175 |
|
| 176 |
|
| 177 |
.UN quant |
| 178 |
.SH QUANTIZATION METHOD |
| 179 |
.PP |
| 180 |
A quantization method is a way to choose which colors, being fewer |
| 181 |
in number than in the input, you want in the output. |
| 182 |
\fBpnmcolormap\fP uses Heckbert's "median cut" quantization |
| 183 |
method. |
| 184 |
.PP |
| 185 |
This method involves separating all the colors into |
| 186 |
"boxes," each holding colors that represent about the same |
| 187 |
number of pixels. You start with one box and split boxes in two until |
| 188 |
the number of boxes is the same as the number of colors you want in |
| 189 |
the output, and choose one color to represent each box. |
| 190 |
.PP |
| 191 |
There are three ways \fBpnmcolormap\fP can choose the box to split in |
| 192 |
each step: |
| 193 |
|
| 194 |
.IP \(bu |
| 195 |
Split the box containing the most pixels. This is the default, |
| 196 |
and you can select it explicitly with option \fB-splitpixelct\fP. |
| 197 |
.IP \(bu |
| 198 |
Split the box containing the most colors. This appears to be useful |
| 199 |
for academic purposes only. Select this with option |
| 200 |
\fB-splitcolorct\fP. |
| 201 |
.IP \(bu |
| 202 |
Split the box containing the largest color spread. Select this |
| 203 |
with option \fB-splitspread\fP. This can produce a better result for |
| 204 |
small details with colors not found elsewhere in the image. |
| 205 |
|
| 206 |
.PP |
| 207 |
\fB-splitpixelct\fP, \fBsplitcolorct\fP, and \fBsplitspread\fP were new |
| 208 |
in Netpbm 10.88 (September 2019). Before that, \fBpnmcolormap\fP always |
| 209 |
splits the box containing the most pixels. |
| 210 |
|
| 211 |
.PP |
| 212 |
When you split a box, you do it so each sub-box has the same number of |
| 213 |
pixels (except one sub-box has more if the full box has an odd number), with |
| 214 |
the 'greatest' pixels in one sub-box and the 'least' |
| 215 |
pixels in the other. "Greater," for a particular box, means it is brighter in |
| 216 |
the color component (red, green, blue) which has the largest spread in that |
| 217 |
box. \fBpnmcolormap\fP gives you two ways to define "largest spread.": 1) |
| 218 |
largest spread of brightness; 2) largest spread of contribution to the |
| 219 |
luminosity of the color. E.g. red is weighted much more than blue. Select |
| 220 |
among these with the \fB-spreadbrightness\fP and \fB-spreadluminosity\fP |
| 221 |
options. The default is \fB-spreadbrightness\fP. Where there are multiple |
| 222 |
colors of the median magnitude, they are distributed arbitrarily among between |
| 223 |
the subboxes. |
| 224 |
|
| 225 |
This arbitrary distribution is repeatable, though, for a given Netpbm version |
| 226 |
-- every invocation of \fBpnmcolormap\fP generates the same color map. |
| 227 |
Before Netpbm 11.03 (June 2023), the distribution would depend upon what the |
| 228 |
system's \fBqsort\fP function does with multiple equal values, so |
| 229 |
\fBpnmcolormap\fP may produce slightly different results on different |
| 230 |
systems. |
| 231 |
.PP |
| 232 |
\fBpnmcolormap\fP provides three ways of choosing a color to represent a |
| 233 |
box: 1) the center color - the color halfway between the greatest and least |
| 234 |
colors in the box, using the above definition of "greater"; 2) the mean of the |
| 235 |
colors (each component averaged separately by brightness) in the box; 3) the |
| 236 |
mean weighted by the number of pixels of a color in the image. |
| 237 |
.PP |
| 238 |
Select among these with the \fB-center\fP, \fB-meancolor\fP, and |
| 239 |
\fB-meanpixel\fP options. The default is \fB-center\fP. |
| 240 |
.PP |
| 241 |
Note that in all three methods, there may be colors in the output |
| 242 |
which do not appear in the input at all. |
| 243 |
.PP |
| 244 |
Also note that the color chosen to represent the colors in Box A the best |
| 245 |
may also represent a color in Box B better than the color chosen to represent |
| 246 |
the colors in Box B the best. This is true for various measures of goodness |
| 247 |
of representation of one color by another. In particular, if you |
| 248 |
use \fBpnmremap\fP to map the colors in the very image that you used to |
| 249 |
create the color map to the colors in that colormap, the colors in Box B will |
| 250 |
often map to the color \fBpnmcolormap\fP chose to represent some other box |
| 251 |
and in fact the color \fBpnmcolormap\fP chose to represent Box B may not |
| 252 |
appear in the \fBpnmremap\fP output at all. |
| 253 |
|
| 254 |
|
| 255 |
.UN references |
| 256 |
.SH REFERENCES |
| 257 |
|
| 258 |
"Color Image Quantization for Frame Buffer Display" by Paul Heckbert, |
| 259 |
SIGGRAPH '82 Proceedings, page 297. |
| 260 |
|
| 261 |
.UN seealso |
| 262 |
.SH SEE ALSO |
| 263 |
.BR "pnmremap" (1)\c |
| 264 |
\&, |
| 265 |
.BR "pnmquant" (1)\c |
| 266 |
\&, |
| 267 |
.BR "ppmquantall" (1)\c |
| 268 |
\&, |
| 269 |
.BR "pamgetcolor" (1)\c |
| 270 |
\&, |
| 271 |
.BR "pamdepth" (1)\c |
| 272 |
\&, |
| 273 |
.BR "ppmdither" (1)\c |
| 274 |
\&, |
| 275 |
.BR "pamseq" (1)\c |
| 276 |
\&, |
| 277 |
.BR "ppmmake" (1)\c |
| 278 |
\&, |
| 279 |
.BR "pamcat" (1)\c |
| 280 |
\&, |
| 281 |
.BR "ppm" (1)\c |
| 282 |
\& |
| 283 |
|
| 284 |
.UN history |
| 285 |
.SH HISTORY |
| 286 |
.PP |
| 287 |
Before Netpbm 10.15 (April 2003), \fBpnmcolormap\fP used a lot |
| 288 |
more memory for large images because it kept the entire input image in |
| 289 |
memory. Now, it processes it a row at a time, but because it |
| 290 |
sometimes must make multiple passes through the image, it first copies |
| 291 |
the input into a temporary seekable file if it is not already in a seekable |
| 292 |
file. |
| 293 |
.PP |
| 294 |
\fBpnmcolormap\fP first appeared in Netpbm 9.23 (January 2002). |
| 295 |
Before that, its function was available only as part of the function |
| 296 |
of \fBpnmquant\fP (which was derived from the much older |
| 297 |
\fBppmquant\fP). Color quantization really has two main subfunctions, so |
| 298 |
Netpbm 9.23 split it out into two separate programs: |
| 299 |
\fBpnmcolormap\fP and \fBpnmremap\fP and then Netpbm 9.24 replaced |
| 300 |
\fBpnmquant\fP with a program that simply calls \fBpnmcolormap\fP and |
| 301 |
\fBpnmremap\fP. |
| 302 |
|
| 303 |
.UN author |
| 304 |
.SH AUTHOR |
| 305 |
|
| 306 |
Copyright (C) 1989, 1991 by Jef Poskanzer. |
| 307 |
.SH DOCUMENT SOURCE |
| 308 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 309 |
source. The master documentation is at |
| 310 |
.IP |
| 311 |
.B http://netpbm.sourceforge.net/doc/pnmcolormap.html |
| 312 |
.PP |