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 an‐
55 other 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 im‐
79 age are the colors in the palette. Where the pixels appear in the im‐
80 age, and the dimensions of the image, are irrelevant. Multiple pixels
81 of the same color are fine. However, a palette image is typically a
82 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 al‐
111 ways fall into one of the cases pnmremap can handle. There's an issue
112 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 im‐
139 age for posting on the World Wide Web, where different browsers know
140 different colors. But all browsers are supposed to know the 216 "web
141 safe" colors which are essentially all the colors you can represent in
142 a PPM image with a maxval of 5. So you can do this:
143 pamseq 3 5 >websafe.pam
145 pnmremap -map=websafe.pam testimg.ppm >websafe_testimg.ppm
147 Another useful palette is one for the 8 color IBM TTL color set, which
150 you can create with
151 pamseq 3 1 >ibmttl.pam
152 If you want to quantize one image to use the colors in another one,
155 just use the second one as the palette. You don't have to reduce it
156 down to only one pixel of each color, just use it as is.
157 The output image has the same type and maxval as the palette image.
159
162 There is one parameter, which is required: The file specification of
163 the input PNM file.
164
168 In addition to the options common to all programs based on libnetpbm
169 (most notably -quiet, see
170 Common Options ⟨index.html#commonoptions⟩ ), pnmremap recognizes the
171 following command line options:
172 -mapfile=palettefilename
177 This names the file that contains the palette image.
178 This option is mandatory.
180 -floyd
183 -fs
185 -nofloyd
187 -nofs These options determine whether pnmremap does Floyd-Steinberg
189 dithering. Without Floyd-Steinberg, pnmremap selects the output
190 color of a pixel based on the color of only the corresponding
191 input pixel. With Floyd-Steinberg, pnmremap considers regions
192 of pixels such that the average color of a region is the same in
193 the output as in the input. The dithering effect appears as a
194 dot pattern up close, but from a distance, the dots blend so
195 that you see more colors than are present in the color map.
196 As an example, if your color map contains only black and white,
198 and the input image has 4 adjacent pixels of gray, pnmremap with
199 Floyd-Steinberg would generate output pixels black, white,
200 black, white, which from a distance looks gray. But without
201 Floyd-Steinberg, pnmremap would generate 4 white pixels, white
202 being the single-pixel approximation of gray.
203 Floyd-Steinberg gives vastly better results on images where un‐
205 modified quantization has banding or other artifacts, especially
206 when going to a small number of colors such as the above IBM
207 set. However, it does take substantially more CPU time.
208 -fs is a synonym for -floyd. -nofs is a synonym for -nofloyd.
210 The default is -nofloyd.
212 Before Netpbm 10.46 (March 2009), dithering doesn't work quite
214 as you expect if the color map has a lower maxval than the in‐
215 put. pnmremap reduces the color resolution to the color map's
216 maxval before doing any dithering, so the dithering does not
217 have the effect of making the image, at a distance, appear to
218 have the original maxval. In current Netpbm, it does.
219 -norandom
222 This option affects a detail of the Floyd-Steinberg dithering
223 process. It has no effect if you aren't doing Floyd-Steinberg
224 dithering.
225 By default, pnmremap initializes the error propagation accumula‐
227 tor to random values to avoid the appearance of unwanted pat‐
228 terns. This is an extension of the original Floyd-Steinberg al‐
229 gorithm.
230 A drawback of this is that the same pnmremap on the same input
232 produces slightly different output every time, which makes com‐
233 parison difficult.
234 With -norandom, pnmremap initializes the error accumulators to
236 zero and the output is completely predictable.
237 Alternatively, you can use -randomseed to get randomization
239 across the image, but still have repeatable results.
240 You cannot specify this along with -randomseed.
242 -norandom was new in Netpbm 10.39 (June 2007).
244 -randomseed=n
248 This option affects a detail of the Floyd-Steinberg dithering
249 process. It has no effect if you aren't doing Floyd-Steinberg
250 dithering.
251 This option supplies the seed for the random number generator
253 used in the randomization process described in the explanation
254 of the -norandom option. If you run pnmremap twice with the
255 same -randomseed value, you will get identical results.
256 If you do not specify -randomseed, pnmremap chooses a seed at
258 random, adding another level of randomness to the dithering.
259 You cannot specify this along with -norandom.
261 This option was new in Netpbm 10.82 (March 2018).
263 -firstisdefault
267 This tells pnmremap to map any input color that is not in the
268 palette to the first color in the palette (the color of the
269 pixel in the top left corner of the palette image)
270 See DESCRIPTION ⟨#description⟩ .
272 If you specify -firstisdefault, the maxval of your input must
274 match the maxval of your palette image.
275 -missingcolor=colorspec
278 This specifies the default color for pnmremap to map to a color
279 in the input image that isn't in the palette. color may or may
280 not be in the palette image; it is part of the palette regard‐
281 less.
282 colorspec is as described for the argument of the
284 pnm_parsecolor() library routine
285 ⟨libnetpbm_image.html#colorname⟩ .
286 If you specify -missingcolor, the maxval of your input must
288 match the maxval of your palette image.
289 -verbose
292 Display helpful messages about the mapping process.
293
299 pnmcolormap(1), pamlookup(1), pnmquant(1), ppmquantall(1), pamdepth(1),
300 ppmdither(1), ppmquant(1), pamseq(1), ppm(1)
301
304 pnmremap first appeared in Netpbm 9.23 (January 2002). Before that,
305 its function was available only as part of the function of pnmquant
306 (which was derived from the much older ppmquant). Color quantization
307 really has two main subfunctions, so Netpbm 9.23 split it out into two
308 separate programs: pnmcolormap and pnmremap and then Netpbm 9.24 re‐
309 placed pnmquant with a program that simply calls pnmcolormap and pnm‐
310 remap.
311
314 Copyright (C) 1989, 1991 by Jef Poskanzer.
315
317 This manual page was generated by the Netpbm tool 'makeman' from HTML
318 source. The master documentation is at
319 http://netpbm.sourceforge.net/doc/pnmremap.html
321netpbm documentation 13 November 2014 Pnmremap User Manual(0)