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

NAME

6       pnmremap - replace colors in a PNM image with colors from another set
7
8

SYNOPSIS

10       pnmremap
11
12       -mapfile=palettefile
13
14       [-floyd|-fs|-nfloyd|-nofs]
15
16       [-norandom]
17
18       [-firstisdefault]
19
20       [-verbose]
21
22       [-missingcolor=color]
23
24       [pnmfile]
25
26       All  options  can  be abbreviated to their shortest unique prefix.  You
27       may use two hyphens instead of one to designate an option.  You may use
28       either  white  space  or  an equals sign between an option name and its
29       value.
30
31

DESCRIPTION

33       This program is part of Netpbm(1).
34
35       pnmremap replaces the colors in an input image with those from  a  pal‐
36       ette  you  specify.   Where colors in the input are present in the pal‐
37       ette, they just stay the same in the output.  But where the input  con‐
38       tains  a  color  that  is  not in the palette, pnmremap gives you these
39       choices:
40
41
42
43       ·      Choose the closest color from the palette.
44
45
46       ·      Choose the first color from the palette.
47
48
49       ·      Use a color specified by a command option (-missing).
50
51
52       ·      Dither.  This means rather than mapping pixel by pixel, pnmremap
53              uses  colors from the palette to try to make multi-pixel regions
54              of the output have the same average  color  as  the  input  (for
55              another kind of dithering, see ppmdither).
56
57
58
59       Two  reasons  to use this program are: 1) you want to reduce the number
60       of colors in the input image; and 2) you need  to  feed  the  image  to
61       something that can handle only certain colors.
62
63       To reduce colors, you can generate the palette with pnmcolormap.
64
65       By  default, pnmremap maps an input color that is not in the palette to
66       the closest color that is in  the  palette.   Closest  means  with  the
67       smallest  cartesian  distance  in the red, green, blue brightness space
68       (smallest sum of the squares of the differences in red, green, and blue
69       ITU-R Recommedation BT.709 gamma-adjusted intensities).
70
71       You  can instead specify a single default color for pnmremap to use for
72       any color in the input image that is  not  in  the  palette.   Use  the
73       -missing option for this.
74
75       You  can  also specify that the first color in the palette image is the
76       default.  Use the -firstisdefault option for this.
77
78       The palette is simply a PNM image.  The colors of  the  pixels  in  the
79       image  are  the  colors in the palette.  Where the pixels appear in the
80       image, and the dimensions of the image, are irrelevant.  Multiple  pix‐
81       els  of the same color are fine.  However, a palette image is typically
82       a single row with one pixel per color.
83
84       If you specify -missing, the color you so specify is in the palette  in
85       addition to whatever is in the palette image.
86
87       For  historical  reasons,  Netpbm  sometimes  calls the palette a 'col‐
88       ormap.' But it doesn't really map anything.  pnmremap creates  its  own
89       map, based on the palette, to map colors from the input image to output
90       colors.
91
92
93   Palette/Image Type Mismatch
94       In the simple case, the palette image is of the same depth  (number  of
95       planes,  i.e.  number of components in each tuple (pixel)) as the input
96       image and pnmremap just does a straightforward search  of  the  palette
97       for  each  input tuple (pixel).  In fact, pnmremap doesn't even care if
98       the image is a visual image.
99
100       But what about when the depths differ?  In that case, pnmremap converts
101       the  input image (in its own memory) to match the palette and then pro‐
102       ceeds as above.
103
104       There are only two such cases in which pnmremap knows  how  to  do  the
105       conversion:  when one of them is tuple type RGB, depth 3, and the other
106       is tuple type GRAYSCALE or BLACKANDWHITE, depth 1; and vice versa.
107
108       In any other case, pnmremap issues and error message and fails.
109
110       Note that as long as your input and palette  images  are  PNM,  they'll
111       always  fall  into  one  of  the cases pnmremap can handle.  There's an
112       issue only if you're using some exotic PAM image.
113
114       Before Netpbm 10.27 (March 2005), pnmremap could not handle the case of
115       a  palette  of  greater depth than the input image.  (It would issue an
116       error message and fail in that case).  You can use ppmtoppm to increase
117       the depth of the input image to work around this limitation.
118
119       In  any case, the output image has the same tuple type and depth as the
120       palette image.
121
122
123   Multiple Image Stream
124       pnmremap handles a multiple image input stream,  producing  a  multiple
125       image output stream.  The input images need not be similar in any way.
126
127       Before  Netpbm  10.30  (October 2005), pnmremap ignored any image after
128       the first.
129
130
131
132   Examples
133       pnmcolormap testimg.ppm 256 >palette.ppm
134
135       pnmremap -map=palette.ppm testimg.ppm >reduced_testimg.ppm
136
137       To limit colors to a certain set, a typical example  is  to  create  an
138       image  for posting on the World Wide Web, where different browsers know
139       different colors.  But all browsers are supposed to know the  216  'web
140       safe'  colors which are essentially all the colors you can represent in
141       a PPM image with a maxval of 5.  So you can do this:
142
143       pamseq 3 5 >websafe.pam
144
145       pnmremap -map=websafe.pam testimg.ppm >websafe_testimg.ppm
146
147       Another useful palette is one for the 8 color IBM TTL color set,  which
148       you can create with
149       pamseq 3 1 >ibmttl.pam
150
151       If  you  want  to  quantize one image to use the colors in another one,
152       just use the second one as the palette.  You don't have  to  reduce  it
153       down to only one pixel of each color, just use it as is.
154
155       The output image has the same type and maxval as the palette image.
156
157

PARAMETERS

159       There  is  one  parameter, which is required: The file specification of
160       the input PNM file.
161
162
163

OPTIONS

165       -mapfile=palettefilename
166              This names the file that contains the palette image.
167
168              This option is mandatory.
169
170
171       -floyd
172
173       -fs
174
175       -nofloyd
176
177       -nofs  These options determine whether  pnmremap  does  Floyd-Steinberg
178              dithering.  Without Floyd-Steinberg, pnmremap selects the output
179              color of a pixel based on the color of  only  the  corresponding
180              input  pixel.   With Floyd-Steinberg, pnmremap considers regions
181              of pixels such that the average color of a region is the same in
182              the  output  as in the input.  The dithering effect appears as a
183              dot pattern up close, but from a distance,  the  dots  blend  so
184              that you see more colors than are present in the color map.
185
186              As  an example, if your color map contains only black and white,
187              and the input image has 4 adjacent pixels of gray, pnmremap with
188              Floyd-Steinberg  would  generate  output  pixels  black,  white,
189              black, white, which from a distance  looks  gray.   But  without
190              Floyd-Steinberg,  pnmremap  would generate 4 white pixels, white
191              being the single-pixel approximation of gray.
192
193              Floyd-Steinberg gives vastly  better  results  on  images  where
194              unmodified  quantization  has  banding or other artifacts, espe‐
195              cially when going to a small number of colors such as the  above
196              IBM set.  However, it does take substantially more CPU time.
197
198              -fs is a synomym for -floyd.  -nofs is a synonym for -nofloyd.
199
200              The default is -nofloyd.
201
202              Before  Netpbm  10.46 (March 2009), dithering doesn't work quite
203              as you expect if the color map  has  a  lower  maxval  than  the
204              input.  pnmremap reduces the color resolution to the color map's
205              maxval before doing any dithering, so  the  dithering  does  not
206              have  the  effect  of making the image, at a distance, appear to
207              have the original maxval.  In current Netpbm, it does.
208
209
210       -norandom
211              This option affects a detail of  the  Floyd-Steinberg  dithering
212              process.   It  has no effect if you aren't doing Floyd-Steinberg
213              dithering.
214
215              By default, pnmremap initializes the error propagation accumula‐
216              tor  to  random  values to avoid the appearance of unwanted pat‐
217              terns.  This is an extension  of  the  original  Floyd-Steinberg
218              algorithm.
219
220              A  drawback  of this is that the same pnmremap on the same input
221              produces slightly different output every time, which makes  com‐
222              parison difficult.
223
224              With  -norandom,  pnmremap initializes the error accumulators to
225              zero and the output is completely predictable.
226
227              -norandom was new in Netpbm 10.39 (June 2007).
228
229
230
231       -firstisdefault
232              This tells pnmremap to map any input color that is  not  in  the
233              palette  to  the  first  color  in the palette (the color of the
234              pixel in the top left corner of the palette image)
235
236              See DESCRIPTION ⟨#description⟩ .
237
238              If you specify -firstisdefault, the maxval of  your  input  must
239              match the maxval of your palette image.
240
241
242       -missingcolor=color
243              This  specifies the default color for pnmremap to map to a color
244              in the input image that isn't in the palette.  color may or  may
245              not  be  in the palette image; it is part of the palette regard‐
246              less.
247
248              If you specify -missingcolor, the  maxval  of  your  input  must
249              match the maxval of your palette image.
250
251
252       -verbose
253              Display helpful messages about the mapping process.
254
255
256
257
258

SEE ALSO

260       pnmcolormap(1),  pamseq(1),  pnmquant(1),  ppmquantall(1), pamdepth(1),
261       ppmdither(1), ppmquant(1), ppm(1)
262
263

HISTORY

265       pnmremap first appeared in Netpbm 9.23 (January  2002).   Before  that,
266       its  function  was  available  only as part of the function of pnmquant
267       (which was derived from the much older ppmquant).   Color  quantization
268       really  has two main subfunctions, so Netpbm 9.23 split it out into two
269       separate programs:  pnmcolormap  and  pnmremap  and  then  Netpbm  9.24
270       replaced pnmquant with a program that simply calls pnmcolormap and pnm‐
271       remap.
272
273

AUTHOR

275       Copyright (C) 1989, 1991 by Jef Poskanzer.
276
277
278
279netpbm documentation             03 June 2009          Pnmremap User Manual(0)
Impressum