1Pnmcolormap User Manual(0)                          Pnmcolormap User Manual(0)
2
3
4

NAME

6       pnmcolormap - create quantization color map for a Netpbm image
7
8

SYNOPSIS

10       pnmcolormap
11
12       [-center|-meancolor|-meanpixel]
13
14       [-spreadbrightness|-spreadluminosity]
15
16       [-sort]
17
18       [-square]
19
20       ncolors|all
21
22       [pnmfile]
23
24

DESCRIPTION

26       This program is part of Netpbm(1).
27
28       pnmcolormap  reads  a PNM or PAM image as input, chooses ncolors colors
29       to best represent the image and writes a PNM color map defining them as
30       output.   A PAM image may actually contain tuples of any kind, but pnm‐
31       colormap's concept of the tuple values that  best  represent  the  ones
32       present  in the image may not make sense if the tuple type isn't RGB or
33       GRAYSCALE.  The design of the program, and the  rest  of  this  manual,
34       assumes the tuples represent colors.
35
36       You  can  use  this map as input to pnmremap on the same input image to
37       quantize the colors in that image, I.e. produce a  similar  image  with
38       fewer  colors.   pnmquant  does both the pnmcolormap and pnmremap steps
39       for you.
40
41       A PNM colormap is a PNM image of any dimensions that contains at  least
42       one  pixel  of each color in the set of colors it represents.  The ones
43       pnmcolormap generates have exactly one  pixel  of  each  color,  except
44       where padding is necessary with the -square option.
45
46       The  quantization  method is Heckbert's 'median cut'.  See QUANTIZATION
47       METHOD ⟨#quant⟩ .
48
49       The output image is of the same format (PBM,  PGM,  PPM,  PAM)  as  the
50       input image.  Note that a colormap of a PBM image is not very interest‐
51       ing.
52
53       The colormap generally has the same maxval as the input image, but pnm‐
54       colormap  may  reduce  it if there are too many colors in the input, as
55       part of its quantization algorithm.
56
57       pnmcolormap works on a multi-image input stream.  In that case, it pro‐
58       duces  one  colormap  that  applies  to all of the colors in all of the
59       input images.  All the images must have the  same  format,  depth,  and
60       maxval  (but  may  have different height and width).  This is useful if
61       you need to quantize a bunch of images that will form a movie or other‐
62       wise  be  used together -- you generally want them all to draw from the
63       same palette, whereas computing a colormap separately from  each  image
64       would  make  the  same  color  in  two  images map to different colors.
65       Before Netpbm 10.31 (December  2005),  pnmcolormap  ignored  any  image
66       after the first.
67
68       If  you want to create a colormap without basing it on the colors in an
69       input image, pamseq, ppmmake, and pnmcat can be useful.
70
71

PARAMETERS

73       The single parameter, which is required, is the number  of  colors  you
74       want  in the output colormap.  pnmcolormap may produce a color map with
75       slightly fewer colors than that.  You may specify all to get a colormap
76       of every color in the input image (no quantization).
77
78

OPTIONS

80       All  options  can  be abbreviated to their shortest unique prefix.  You
81       may use two hyphens instead of one to designate an option.  You may use
82       either  white  space  or  an equals sign between an option name and its
83       value.
84
85
86
87       -sort  This option causes the output colormap to be sorted by  the  red
88              component  intensity, then the green, then the blue in ascending
89              order.  This is an insertion sort, so it is  not  very  fast  on
90              large  colormaps.   Sorting  is  useful because it allows you to
91              compare two sets of colors.
92
93
94       -square
95              By default, pnmcolormap produces as the color map  a  PPM  image
96              with one row and with one column for each color in the colormap.
97              This option causes pnmcolormap instead to produce  a  PPM  image
98              that  is within one row or column of being square, with the last
99              pixel duplicated as necessary to create a number of pixels which
100              is such an almost-perfect square.
101
102
103       -verbose
104              This  option  causes pnmcolormap to display messages to Standard
105              Error about the quantization..TP -center
106
107
108       -meancolor
109
110
111       -meanpixel
112
113
114       -spreadbrightness
115
116
117       -spreadluminosity
118              These  options  control   the   quantization   algorithm.    See
119              QUANTIZATION METHOD ⟨#quant⟩ .
120
121
122
123
124

QUANTIZATION METHOD

126       A  quantization  method is a way to choose which colors, being fewer in
127       number than in the input, you want in  the  output.   pnmcolormap  uses
128       Heckbert's 'median cut' quantization method.
129
130       This method involves separating all the colors into 'boxes,' each hold‐
131       ing colors that represent about the same number of pixels.   You  start
132       with  one  box  and split boxes in two until the number of boxes is the
133       same as the number of colors you want in the  output,  and  choose  one
134       color to represent each box.
135
136       When  you  split a box, you do it so that all the colors in one sub-box
137       are 'greater' than all the colors in the other.  'Greater,' for a  par‐
138       ticular  box,  means it is brighter in the color component (red, green,
139       blue) which has the largest spread in that box.  pnmcolormap gives  you
140       two  ways to define 'largest spread.': 1) largest spread of brightness;
141       2) largest spread of contribution to the luminosity of the color.  E.g.
142       red  is  weighted  much  more  than  blue.  Select among these with the
143       -spreadbrightness  and  -spreadluminosity  options.   The  default   is
144       -spreadbrightness.
145
146       pnmcolormap provides three ways of choosing a color to represent a box:
147       1) the center color - the color halfway between the greatest and  least
148       colors in the box, using the above definition of 'greater'; 2) the mean
149       of the colors (each component averaged separately by brightness) in the
150       box;  3)  the  mean  weighted by the number of pixels of a color in the
151       image.
152
153       Note that in all three methods, there may be colors in the output which
154       do not appear in the input at all.
155
156       Select  among  these  with  the  -center,  -meancolor,  and  -meanpixel
157       options.  The default is -center.
158
159

REFERENCES

161       'Color Image Quantization for Frame Buffer Display' by  Paul  Heckbert,
162       SIGGRAPH '82 Proceedings, page 297.
163
164

SEE ALSO

166       pnmremap(1),  pnmquant(1),  ppmquantall(1),  pamdepth(1), ppmdither(1),
167       pamseq(1), ppmmake(1), pnmcat(1), ppm(1)
168
169

HISTORY

171       Before Netpbm 10.15 (April 2003), pnmcolormap used a  lot  more  memory
172       for  large  images  because  it  kept the entire input image in memory.
173       Now, it processes it a row at a time, but  because  it  sometimes  must
174       make  multiple passes through the image, it first copies the input into
175       a temporary seekable file if it is not already in a seekable file.
176
177       pnmcolormap first appeared in Netpbm 9.23 (January 2002).  Before that,
178       its  function  was  available  only as part of the function of pnmquant
179       (which was derived from the much older ppmquant).   Color  quantization
180       really  has two main subfunctions, so Netpbm 9.23 split it out into two
181       separate programs:  pnmcolormap  and  pnmremap  and  then  Netpbm  9.24
182       replaced pnmquant with a program that simply calls pnmcolormap and pnm‐
183       remap.
184
185

AUTHOR

187       Copyright (C) 1989, 1991 by Jef Poskanzer.
188
189
190
191netpbm documentation            23 October 2005     Pnmcolormap User Manual(0)
Impressum