Debian Codegraph @

upstream/debian-unstable/man1/ppmchange.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 "Ppmchange User Manual" 1 "December 2016" "netpbm documentation"
7
8 .SH NAME
9 ppmchange - change all pixels of one color to another in a PPM image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBppmchange\fP
15
16 [\fB-closeness=\fP\fIcloseness_percent\fP]
17 [\fB-remainder=\fP\fIremainder_color\fP]
18 [\fB-closeok\fP]
19 [\fIoldcolor newcolor\fP] ...
20 [\fIppmfile\fP]
21
22 .UN examples
23 .SH EXAMPLES
24
25 .nf
26 \fBppmchange red blue redimage.ppm >blueimage.ppm\fP
27
28 \fBppmchange red red -remainder=black myimage.ppm >redblack.ppm\fP
29
30 \fBppmchange -closeness=10 white white black black\fP
31
32
33 .fi
34
35 .UN description
36 .SH DESCRIPTION
37 .PP
38 This program is part of
39 .BR "Netpbm" (1)\c
40 \&.
41 .PP
42 \fBppmchange\fP reads a PPM image as input and changes all pixels of
43 color \fIoldcolor\fP to color \fInewcolor\fP.
44
45 You may specify up to 256 oldcolor/newcolor pairs on the command line.
46 \fBppmchange\fP leaves all colors not mentioned unchanged, unless you
47 specify the \fB-remainder\fP option, in which case they are all
48 changed to the single specified color.
49 .PP
50 You can specify that colors similar, but not identical, to the ones
51 you specify get replaced by specifying a "closeness" factor.
52 .PP
53 Specify the colors as described for the
54 .UR libnetpbm_image.html#colorname
55 argument of the \fBpnm_parsecolor()\fP library routine
56 .UE
57 \&.
58 .PP
59 If a pixel matches two different \fIoldcolor\fPs, \fBppmchange\fP
60 replaces it with the \fInewcolor\fP of the leftmost specified one.
61 .PP
62 The maxval of the output image is the same as that of the input
63 image. If a \fInewcolor\fP you specify cannot be exactly represented
64 in that maxval, \fBppmchange\fP assumes a color that is as close as
65 possible to what you specified but can be represented with your
66 maxval. Unless you specify the \fB-closeok\fP option,
67 \fBppmchange\fP issues a warning that it is using an approximation.
68 .PP
69 A common way that you can have this maxval problem, where the color
70 you specify cannot be represented with your maxval, is that your input
71 is a PBM (black and white) image that you are colorizing. The maxval
72 in this case is 1, which severely limits the colors to which you can
73 change. To avoid this problem, use \fBpamdepth\fP to make the maxval
74 of your input something consistent with your colors. 255 is usually a
75 good choice.
76 .PP
77 Before Netpbm 10.22 (April 2004), \fBppmchange\fP always behaved as
78 if the user specified \fB-closeok\fP, and there was no \fB-closeok\fP
79 option.
80
81
82 .UN options
83 .SH OPTIONS
84 .PP
85 In addition to the options common to all programs based on libnetpbm
86 (most notably \fB-quiet\fP, see
87 .UR index.html#commonoptions
88 Common Options
89 .UE
90 \&), \fBppmchange\fP recognizes the following
91 command line options:
92
93
94 .TP
95 \fB-closeness \fP\fIcloseness_percent\fP
96 \fIcloseness\fP is a percentage indicating how close to the color you
97 specified a pixel must be to get replaced. By default, it is 0, which means
98 the pixel must be the exact color you specified.
99 .sp
100 A pixel gets replaced if the distance in color between it and the
101 color you specified is less than or equal to \fIcloseness\fP per cent
102 of the maxval.
103 .sp
104 The "distance" in color is defined as the Cartesian sum of the
105 individual differences in red, green, and blue intensities between the
106 two pixels, normalized so that the difference between black and white
107 is 100%.
108 .sp
109 This is probably simpler than what you want most the time. You
110 probably would like to change colors that have similar chrominance,
111 regardless of their intensity. So if there's a red barn that is
112 variously shadowed, you want the entire barn changed. But because the
113 shadowing significantly changes the color according to
114 \fBppmchange\fP's distance formula, parts of the barn are probably
115 about as distant in color from other parts of the barn as they are
116 from green grass next to the barn.
117 .sp
118 Maybe \fBppmchange\fP will be enhanced some day to do chrominance
119 analysis.
120 .sp
121 This option was new in Netpbm 9.8 (September 2000).
122
123 .TP
124 \fB-closeok\fP
125 This option affects how \fBppmchange\fP interprets a color you
126 specify in the arguments. When you specify this option, \fBppmchange\fP
127 may use a color close to, but not the same as what you specify. See
128 .UR #description
129 the description section
130 .UE
131 \& for details.
132 .sp
133 This option was new in Netpbm 10.22 (April 2004). Before that,
134 \fBppmchange\fP always behaved as if you specified this option.
135
136 .TP
137 \fB-remainder \fP\fIcolor\fP
138 \fBppmchange\fP changes all pixels which are not of a color for
139 which you specify an explicit replacement color on the command line to
140 color \fIcolor\fP.
141 .sp
142 An example application of this is
143
144 .nf
145 \fBppmchange -remainder=black red red\fP
146
147 .fi
148
149 to lift only the red portions from an image, or
150 .nf
151 \fBppmchange -remainder=black red white | ppmtopgm\fP
152
153 .fi
154
155 to create a mask file for the red portions of the image.
156
157
158
159 .UN seealso
160 .SH SEE ALSO
161 .BR "pgmtoppm" (1)\c
162 \&,
163 .BR "ppmcolormask" (1)\c
164 \&,
165 .BR "ppm" (1)\c
166 \&
167
168 .UN author
169 .SH AUTHOR
170
171 Wilson H. Bent. Jr. (\[email protected]\fP)
172 with modifications by Alberto Accomazzi (\[email protected]\fP)
173 .SH DOCUMENT SOURCE
174 This manual page was generated by the Netpbm tool 'makeman' from HTML
175 source. The master documentation is at
176 .IP
177 .B http://netpbm.sourceforge.net/doc/ppmchange.html
178 .PP