Debian Codegraph @

upstream/debian-unstable/man1/pnmremap.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pnmremap User Manual" 1 "13 November 2014" "netpbm documentation"
7
8 .SH NAME
9 pnmremap - replace colors in a PNM image with colors from another set
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpnmremap\fP
15
16 \fB-mapfile=\fP\fIpalettefile\fP
17
18 [\fB-floyd\fP|\fB-fs\fP|\fB-nfloyd\fP|\fB-nofs\fP]
19
20 {[\fB-norandom\fP]|\fBrandomseed=\fP\fIn\fP}
21
22 [\fB-firstisdefault\fP]
23
24 [\fB-verbose\fP]
25
26 [\fB-missingcolor=\fP\fIcolorspec\fP]
27
28 [\fIpnmfile\fP]
29 .PP
30 All options can be abbreviated to their shortest unique prefix.
31 You may use two hyphens instead of one to designate an option. You
32 may use either white space or an equals sign between an option name
33 and its value.
34
35 .UN description
36 .SH DESCRIPTION
37 .PP
38 This program is part of
39 .BR "Netpbm" (1)\c
40 \&.
41 .PP
42 \fBpnmremap\fP replaces the colors in an input image with those
43 from a palette you specify. Where colors in the input are present in
44 the palette, they just stay the same in the output. But where the
45 input contains a color that is not in the palette, \fBpnmremap\fP
46 gives you these choices:
47
48
49 .IP \(bu
50 Choose the closest color from the palette.
51
52 .IP \(bu
53 Choose the first color from the palette.
54
55 .IP \(bu
56 Use a color specified by a command option (\fB-missing\fP).
57
58 .IP \(bu
59 Dither. This means rather than mapping pixel by pixel,
60 \fBpnmremap\fP uses colors from the palette to try to make
61 multi-pixel regions of the output have the same average color as the
62 input (for another kind of dithering, see \fBppmdither\fP).
63
64
65 .PP
66 Two reasons to use this program are: 1) you want to reduce the
67 number of colors in the input image; and 2) you need to feed the image
68 to something that can handle only certain colors.
69 .PP
70 To reduce colors, you can generate the palette with
71 \fBpnmcolormap\fP.
72 .PP
73 By default, \fBpnmremap\fP maps an input color that is not in the
74 palette to the closest color that \fIis\fP in the palette. Closest
75 means with the smallest Cartesian distance in the red, green, blue
76 brightness space (smallest sum of the squares of the differences in
77 red, green, and blue ITU-R Recommendation BT.709 gamma-adjusted
78 intensities).
79 .PP
80 You can instead specify a single default color for \fBpnmremap\fP
81 to use for any color in the input image that is not in the palette.
82 Use the \fB-missing\fP option for this.
83 .PP
84 You can also specify that the first color in the palette image
85 is the default. Use the \fB-firstisdefault\fP option for this.
86 .PP
87 The palette is simply a PNM image. The colors of the pixels in the
88 image are the colors in the palette. Where the pixels appear in the
89 image, and the dimensions of the image, are irrelevant. Multiple
90 pixels of the same color are fine. However, a palette image is
91 typically a single row with one pixel per color.
92 .PP
93 If you specify \fB-missing\fP, the color you so specify is in
94 the palette in addition to whatever is in the palette image.
95 .PP
96 For historical reasons, Netpbm sometimes calls the palette a
97 "colormap." But it doesn't really map anything.
98 \fBpnmremap\fP creates its own map, based on the palette, to map
99 colors from the input image to output colors.
100
101 .UN mismatch
102 .SS Palette/Image Type Mismatch
103 .PP
104 In the simple case, the palette image is of the same depth (number
105 of planes, i.e. number of components in each tuple (pixel)) as the
106 input image and \fBpnmremap\fP just does a straightforward search of
107 the palette for each input tuple (pixel). In fact, \fBpnmremap\fP
108 doesn't even care if the image is a visual image.
109 .PP
110 But what about when the depths differ? In that case,
111 \fBpnmremap\fP converts the input image (in its own memory) to match
112 the palette and then proceeds as above.
113 .PP
114 There are only two such cases in which \fBpnmremap\fP knows how to
115 do the conversion: when one of them is tuple type RGB, depth 3, and the
116 other is tuple type GRAYSCALE or BLACKANDWHITE, depth 1; and vice
117 versa.
118 .PP
119 In any other case, \fBpnmremap\fP issues and error message and fails.
120 .PP
121 Note that as long as your input and palette images are PNM, they'll
122 always fall into one of the cases \fBpnmremap\fP can handle. There's an
123 issue only if you're using some exotic PAM image.
124 .PP
125 Before Netpbm 10.27 (March 2005), \fBpnmremap\fP could not handle
126 the case of a palette of greater depth than the input image. (It would
127 issue an error message and fail in that case). You can use \fBppmtoppm\fP
128 to increase the depth of the input image to work around this limitation.
129 .PP
130 In any case, the output image has the same tuple type and depth as
131 the palette image.
132
133 .UN multiple
134 .SS Multiple Image Stream
135 .PP
136 \fBpnmremap\fP handles a multiple image input stream, producing a
137 multiple image output stream. The input images need not be similar in
138 any way.
139 .PP
140 Before Netpbm 10.30 (October 2005), \fBpnmremap\fP ignored any image
141 after the first.
142
143
144 .UN example
145 .SS Examples
146
147 .nf
148 pnmcolormap testimg.ppm 256 >palette.ppm
149
150 pnmremap -map=palette.ppm testimg.ppm >reduced_testimg.ppm
151
152 .fi
153 .PP
154 To limit colors to a certain set, a typical example is to create an
155 image for posting on the World Wide Web, where different browsers know
156 different colors. But all browsers are supposed to know the 216
157 "web safe" colors which are essentially all the colors you
158 can represent in a PPM image with a maxval of 5. So you can do this:
159
160 .nf
161 pamseq 3 5 >websafe.pam
162
163 pnmremap -map=websafe.pam testimg.ppm >websafe_testimg.ppm
164
165 .fi
166 .PP
167 Another useful palette is one for the 8 color IBM TTL color set, which
168 you can create with
169 .nf
170 pamseq 3 1 >ibmttl.pam
171
172 .fi
173 .PP
174 If you want to quantize one image to use the colors in another one,
175 just use the second one as the palette. You don't have to reduce it
176 down to only one pixel of each color, just use it as is.
177 .PP
178 The output image has the same type and maxval as the palette image.
179
180 .UN parameters
181 .SH PARAMETERS
182 .PP
183 There is one parameter, which is required: The file specification of
184 the input PNM file.
185
186
187 .UN options
188 .SH OPTIONS
189 .PP
190 In addition to the options common to all programs based on libnetpbm
191 (most notably \fB-quiet\fP, see
192 .UR index.html#commonoptions
193 Common Options
194 .UE
195 \&), \fBpnmremap\fP recognizes the following
196 command line options:
197
198
199
200 .TP
201 \fB-mapfile=\fP\fIpalettefilename\fP
202 This names the file that contains the palette image.
203 .sp
204 This option is mandatory.
205
206 .TP
207 \fB-floyd\fP
208 .TP
209 \fB-fs\fP
210 .TP
211 \fB-nofloyd\fP
212 .TP
213 \fB-nofs\fP
214 These options determine whether \fBpnmremap\fP does Floyd-Steinberg
215 dithering. Without Floyd-Steinberg, \fBpnmremap\fP selects the output color
216 of a pixel based on the color of only the corresponding input pixel. With
217 Floyd-Steinberg, \fBpnmremap\fP considers regions of pixels such that the
218 average color of a region is the same in the output as in the input. The
219 dithering effect appears as a dot pattern up close, but from a distance, the
220 dots blend so that you see more colors than are present in the color map.
221 .sp
222 As an example, if your color map contains only black and white, and
223 the input image has 4 adjacent pixels of gray, \fBpnmremap\fP with
224 Floyd-Steinberg would generate output pixels black, white, black, white,
225 which from a distance looks gray. But without Floyd-Steinberg,
226 \fBpnmremap\fP would generate 4 white pixels, white being the single-pixel
227 approximation of gray.
228 .sp
229 Floyd-Steinberg gives vastly better results on images where
230 unmodified quantization has banding or other artifacts, especially
231 when going to a small number of colors such as the above IBM set.
232 However, it does take substantially more CPU time.
233 .sp
234 \fB-fs\fP is a synonym for \fB-floyd\fP. \fB-nofs\fP is a
235 synonym for \fB-nofloyd\fP.
236 .sp
237 The default is \fB-nofloyd\fP.
238 .sp
239 Before Netpbm 10.46 (March 2009), dithering doesn't work quite as you
240 expect if the color map has a lower maxval than the input. \fBpnmremap\fP
241 reduces the color resolution to the color map's maxval before doing any
242 dithering, so the dithering does not have the effect of making the image,
243 at a distance, appear to have the original maxval. In current Netpbm, it
244 does.
245
246 .TP
247 \fB-norandom\fP
248 This option affects a detail of the Floyd-Steinberg dithering process.
249 It has no effect if you aren't doing Floyd-Steinberg dithering.
250 .sp
251 By default, \fBpnmremap\fP initializes the error propagation
252 accumulator to random values to avoid the appearance of unwanted
253 patterns. This is an extension of the original Floyd-Steinberg
254 algorithm.
255 .sp
256 A drawback of this is that the same \fBpnmremap\fP on the same
257 input produces slightly different output every time, which makes
258 comparison difficult.
259 .sp
260 With \fB-norandom\fP, \fBpnmremap\fP initializes the error
261 accumulators to zero and the output is completely predictable.
262 .sp
263 Alternatively, you can use \fB-randomseed\fP to get randomization
264 across the image, but still have repeatable results.
265 .sp
266 You cannot specify this along with \fB-randomseed\fP.
267 .sp
268 \fB-norandom\fP was new in Netpbm 10.39 (June 2007).
269
270
271 .TP
272 \fB-randomseed=\fP\fIn\fP
273 This option affects a detail of the Floyd-Steinberg dithering process.
274 It has no effect if you aren't doing Floyd-Steinberg dithering.
275 .sp
276 This option supplies the seed for the random number generator used in the
277 randomization process described in the explanation of the \fB-norandom\fP
278 option. If you run \fBpnmremap\fP twice with the same \fB-randomseed\fP
279 value, you will get identical results.
280 .sp
281 If you do not specify \fB-randomseed\fP, \fBpnmremap\fP chooses a seed
282 at random, adding another level of randomness to the dithering.
283 .sp
284 You cannot specify this along with \fB-norandom\fP.
285 .sp
286 This option was new in Netpbm 10.82 (March 2018).
287
288
289 .TP
290 \fB-firstisdefault\fP
291 This tells \fBpnmremap\fP to map any input color that is not in
292 the palette to the first color in the palette (the color of the pixel
293 in the top left corner of the palette image)
294 .sp
295 See
296 .UR #description
297 DESCRIPTION
298 .UE
299 \&.
300 .sp
301 If you specify \fB-firstisdefault\fP, the maxval of your input
302 must match the maxval of your palette image.
303
304 .TP
305 \fB-missingcolor=\fP\fIcolorspec\fP
306 This specifies the default color for \fBpnmremap\fP to map to a
307 color in the input image that isn't in the palette. \fIcolor\fP may
308 or may not be in the palette image; it is part of the palette
309 regardless.
310 .sp
311 \fIcolorspec\fP is as described for
312 the
313 .UR libnetpbm_image.html#colorname
314 argument of the \fBpnm_parsecolor()\fP library routine
315 .UE
316 \&.
317 .sp
318 If you specify \fB-missingcolor\fP, the maxval of your input must
319 match the maxval of your palette image.
320
321 .TP
322 \fB-verbose\fP
323 Display helpful messages about the mapping process.
324
325
326
327
328 .UN seealso
329 .SH SEE ALSO
330 .BR "pnmcolormap" (1)\c
331 \&,
332 .BR "pamlookup" (1)\c
333 \&,
334 .BR "pnmquant" (1)\c
335 \&,
336 .BR "ppmquantall" (1)\c
337 \&,
338 .BR "pamdepth" (1)\c
339 \&,
340 .BR "ppmdither" (1)\c
341 \&,
342 .BR "ppmquant" (1)\c
343 \&,
344 .BR "pamseq" (1)\c
345 \&,
346 .BR "ppm" (1)\c
347 \&
348
349 .UN history
350 .SH HISTORY
351 .PP
352 \fBpnmremap\fP first appeared in Netpbm 9.23 (January 2002).
353 Before that, its function was available only as part of the function
354 of \fBpnmquant\fP (which was derived from the much older
355 \fBppmquant\fP). Color quantization really has two main subfunctions, so
356 Netpbm 9.23 split it out into two separate programs:
357 \fBpnmcolormap\fP and \fBpnmremap\fP and then Netpbm 9.24 replaced
358 \fBpnmquant\fP with a program that simply calls \fBpnmcolormap\fP and
359 \fBpnmremap\fP.
360
361 .UN author
362 .SH AUTHOR
363
364 Copyright (C) 1989, 1991 by Jef Poskanzer.
365 .SH DOCUMENT SOURCE
366 This manual page was generated by the Netpbm tool 'makeman' from HTML
367 source. The master documentation is at
368 .IP
369 .B http://netpbm.sourceforge.net/doc/pnmremap.html
370 .PP