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]|randomseed=n}
17
18       [-firstisdefault]
19
20       [-verbose]
21
22       [-missingcolor=colorspec]
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 Recommendation 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 synonym 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              Alternatively, you can  use  -randomseed  to  get  randomization
228              across the image, but still have repeatable results.
229
230              You cannot specify this along with -randomseed.
231
232              -norandom was new in Netpbm 10.39 (June 2007).
233
234
235
236       -randomseed=n
237              This  option  affects  a detail of the Floyd-Steinberg dithering
238              process.  It has no effect if you aren't  doing  Floyd-Steinberg
239              dithering.
240
241              This  option  supplies  the seed for the random number generator
242              used in the randomization process described in  the  explanation
243              of  the  -norandom  option.   If you run pnmremap twice with the
244              same -randomseed value, you will get identical results.
245
246              If you do not specify -randomseed, pnmremap chooses  a  seed  at
247              random, adding another level of randomness to the dithering.
248
249              You cannot specify this along with -norandom.
250
251              This option was new in Netpbm 10.82 (March 2018).
252
253
254
255       -firstisdefault
256              This  tells  pnmremap  to map any input color that is not in the
257              palette to the first color in the  palette  (the  color  of  the
258              pixel in the top left corner of the palette image)
259
260              See DESCRIPTION ⟨#description⟩ .
261
262              If  you  specify  -firstisdefault, the maxval of your input must
263              match the maxval of your palette image.
264
265
266       -missingcolor=colorspec
267              This specifies the default color for pnmremap to map to a  color
268              in  the input image that isn't in the palette.  color may or may
269              not be in the palette image; it is part of the  palette  regard‐
270              less.
271
272              colorspec   is   as   described   for   the   argument   of  the
273              pnm_parsecolor()                 library                 routine
274              ⟨libnetpbm_image.html#colorname⟩ .
275
276              If  you  specify  -missingcolor,  the  maxval of your input must
277              match the maxval of your palette image.
278
279
280       -verbose
281              Display helpful messages about the mapping process.
282
283
284
285
286

SEE ALSO

288       pnmcolormap(1), pamlookup(1), pnmquant(1), ppmquantall(1), pamdepth(1),
289       ppmdither(1), ppmquant(1), pamseq(1), ppm(1)
290
291

HISTORY

293       pnmremap  first  appeared  in Netpbm 9.23 (January 2002).  Before that,
294       its function was available only as part of  the  function  of  pnmquant
295       (which  was  derived from the much older ppmquant).  Color quantization
296       really has two main subfunctions, so Netpbm 9.23 split it out into  two
297       separate  programs:  pnmcolormap  and  pnmremap  and  then  Netpbm 9.24
298       replaced pnmquant with a program that simply calls pnmcolormap and pnm‐
299       remap.
300
301

AUTHOR

303       Copyright (C) 1989, 1991 by Jef Poskanzer.
304

DOCUMENT SOURCE

306       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
307       source.  The master documentation is at
308
309              http://netpbm.sourceforge.net/doc/pnmremap.html
310
311netpbm documentation           13 November 2014        Pnmremap User Manual(0)
Impressum