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).  When you specify
77       all, the function is essentially the same  as  that  of  ppmhist  -map.
78       ppmhist is much older.
79
80
81

OPTIONS

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

QUANTIZATION METHOD

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

REFERENCES

164       "Color Image Quantization for Frame Buffer Display" by  Paul  Heckbert,
165       SIGGRAPH '82 Proceedings, page 297.
166
167

SEE ALSO

169       pnmremap(1),  pnmquant(1),  ppmquantall(1),  pamdepth(1), ppmdither(1),
170       pamseq(1), ppmmake(1), pnmcat(1), ppm(1)
171
172

HISTORY

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

AUTHOR

190       Copyright (C) 1989, 1991 by Jef Poskanzer.
191

DOCUMENT SOURCE

193       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
194       source.  The master documentation is at
195
196              http://netpbm.sourceforge.net/doc/pnmcolormap.html
197
198netpbm documentation            15 August 2015      Pnmcolormap User Manual(0)
Impressum