1Pnmremap User Manual(0) Pnmremap User Manual(0)
2
6 pnmremap - replace colors in a PNM image with colors from another set
7
10 pnmremap
11 -mapfile=palettefile
13 [-floyd|-fs|-nfloyd|-nofs]
15 {[-norandom]|randomseed=n}
17 [-firstisdefault]
19 [-verbose]
21 [-missingcolor=colorspec]
23 [pnmfile]
25 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
33 This program is part of Netpbm(1).
34 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 · Choose the closest color from the palette.
44 · Choose the first color from the palette.
47 · Use a color specified by a command option (-missing).
50 · 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 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 To reduce colors, you can generate the palette with pnmcolormap.
64 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 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 You can also specify that the first color in the palette image is the
76 default. Use the -firstisdefault option for this.
77 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 If you specify -missing, the color you so specify is in the palette in
85 addition to whatever is in the palette image.
86 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 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 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 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 In any other case, pnmremap issues and error message and fails.
109 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 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 In any case, the output image has the same tuple type and depth as the
120 palette image.
121 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 Before Netpbm 10.30 (October 2005), pnmremap ignored any image after
128 the first.
129 Examples
133 pnmcolormap testimg.ppm 256 >palette.ppm
134 pnmremap -map=palette.ppm testimg.ppm >reduced_testimg.ppm
136 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 pamseq 3 5 >websafe.pam
144 pnmremap -map=websafe.pam testimg.ppm >websafe_testimg.ppm
146 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 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 The output image has the same type and maxval as the palette image.
156
159 There is one parameter, which is required: The file specification of
160 the input PNM file.
161
165 In addition to the options common to all programs based on libnetpbm
166 (most notably -quiet, see
167 Common Options ⟨index.html#commonoptions⟩ ), pnmremap recognizes the
168 following command line options:
169 -mapfile=palettefilename
174 This names the file that contains the palette image.
175 This option is mandatory.
177 -floyd
180 -fs
182 -nofloyd
184 -nofs These options determine whether pnmremap does Floyd-Steinberg
186 dithering. Without Floyd-Steinberg, pnmremap selects the output
187 color of a pixel based on the color of only the corresponding
188 input pixel. With Floyd-Steinberg, pnmremap considers regions
189 of pixels such that the average color of a region is the same in
190 the output as in the input. The dithering effect appears as a
191 dot pattern up close, but from a distance, the dots blend so
192 that you see more colors than are present in the color map.
193 As an example, if your color map contains only black and white,
195 and the input image has 4 adjacent pixels of gray, pnmremap with
196 Floyd-Steinberg would generate output pixels black, white,
197 black, white, which from a distance looks gray. But without
198 Floyd-Steinberg, pnmremap would generate 4 white pixels, white
199 being the single-pixel approximation of gray.
200 Floyd-Steinberg gives vastly better results on images where
202 unmodified quantization has banding or other artifacts, espe‐
203 cially when going to a small number of colors such as the above
204 IBM set. However, it does take substantially more CPU time.
205 -fs is a synonym for -floyd. -nofs is a synonym for -nofloyd.
207 The default is -nofloyd.
209 Before Netpbm 10.46 (March 2009), dithering doesn't work quite
211 as you expect if the color map has a lower maxval than the
212 input. pnmremap reduces the color resolution to the color map's
213 maxval before doing any dithering, so the dithering does not
214 have the effect of making the image, at a distance, appear to
215 have the original maxval. In current Netpbm, it does.
216 -norandom
219 This option affects a detail of the Floyd-Steinberg dithering
220 process. It has no effect if you aren't doing Floyd-Steinberg
221 dithering.
222 By default, pnmremap initializes the error propagation accumula‐
224 tor to random values to avoid the appearance of unwanted pat‐
225 terns. This is an extension of the original Floyd-Steinberg
226 algorithm.
227 A drawback of this is that the same pnmremap on the same input
229 produces slightly different output every time, which makes com‐
230 parison difficult.
231 With -norandom, pnmremap initializes the error accumulators to
233 zero and the output is completely predictable.
234 Alternatively, you can use -randomseed to get randomization
236 across the image, but still have repeatable results.
237 You cannot specify this along with -randomseed.
239 -norandom was new in Netpbm 10.39 (June 2007).
241 -randomseed=n
245 This option affects a detail of the Floyd-Steinberg dithering
246 process. It has no effect if you aren't doing Floyd-Steinberg
247 dithering.
248 This option supplies the seed for the random number generator
250 used in the randomization process described in the explanation
251 of the -norandom option. If you run pnmremap twice with the
252 same -randomseed value, you will get identical results.
253 If you do not specify -randomseed, pnmremap chooses a seed at
255 random, adding another level of randomness to the dithering.
256 You cannot specify this along with -norandom.
258 This option was new in Netpbm 10.82 (March 2018).
260 -firstisdefault
264 This tells pnmremap to map any input color that is not in the
265 palette to the first color in the palette (the color of the
266 pixel in the top left corner of the palette image)
267 See DESCRIPTION ⟨#description⟩ .
269 If you specify -firstisdefault, the maxval of your input must
271 match the maxval of your palette image.
272 -missingcolor=colorspec
275 This specifies the default color for pnmremap to map to a color
276 in the input image that isn't in the palette. color may or may
277 not be in the palette image; it is part of the palette regard‐
278 less.
279 colorspec is as described for the argument of the
281 pnm_parsecolor() library routine
282 ⟨libnetpbm_image.html#colorname⟩ .
283 If you specify -missingcolor, the maxval of your input must
285 match the maxval of your palette image.
286 -verbose
289 Display helpful messages about the mapping process.
290
296 pnmcolormap(1), pamlookup(1), pnmquant(1), ppmquantall(1), pamdepth(1),
297 ppmdither(1), ppmquant(1), pamseq(1), ppm(1)
298
301 pnmremap first appeared in Netpbm 9.23 (January 2002). Before that,
302 its function was available only as part of the function of pnmquant
303 (which was derived from the much older ppmquant). Color quantization
304 really has two main subfunctions, so Netpbm 9.23 split it out into two
305 separate programs: pnmcolormap and pnmremap and then Netpbm 9.24
306 replaced pnmquant with a program that simply calls pnmcolormap and pnm‐
307 remap.
308
311 Copyright (C) 1989, 1991 by Jef Poskanzer.
312
314 This manual page was generated by the Netpbm tool 'makeman' from HTML
315 source. The master documentation is at
316 http://netpbm.sourceforge.net/doc/pnmremap.html
318netpbm documentation 13 November 2014 Pnmremap User Manual(0)