Debian Codegraph @

upstream/debian-unstable/man1/pamrecolor.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 "Pamrecolor User Manual" 1 "31 July 2010" "netpbm documentation"
7
8 .SH NAME
9 pamrecolor - alter colors without affecting luminance
10
11 .UN synopsis
12 .SH SYNOPSIS
13 .PP
14 \fBpamrecolor\fP
15 [\fB--colorspace\fP=\fIname\fP]
16 [\fB--rmult\fP=\fIfraction\fP]
17 [\fB--gmult\fP=\fIfraction\fP]
18 [\fB--bmult\fP=\fIfraction\fP]
19 [\fB--targetcolor\fP=\fIcolor\fP]
20 [\fB--colorfile\fP=\fIfile\fP]
21 [\fB-randomseed=\fP\fIinteger\fP]
22
23 [\fIinfile\fP]
24 .PP
25 Minimum unique abbreviation of option is acceptable. You may use double
26 hyphens instead of single hyphen to denote options. You may use white
27 space in place of the equals sign to separate an option name from its value.
28
29 .UN description
30 .SH DESCRIPTION
31 .PP
32 This program is part of
33 .BR "Netpbm" (1)\c
34 \&.
35 .PP
36 \fBpamrecolor\fP changes an image's colors to be as close as
37 possible to given target colors but with the constraint that the
38 luminance not be modified. That is, the original image and the target
39 image will look identical if both are converted to grayscale
40 (e.g. with
41 .BR "ppmtopgm" (1)\c
42 \&). You can have \fBpamrecolor\fP select
43 target colors randomly, specify a single hue for the entire image, or take the
44 target colors from a target image.
45 .PP
46 In addition to real Netpbm images, \fBpamrecolor\fP works on pseudo-Netpbm
47 images based on arbitrary color spaces. You can define the color space
48 explicitly or choose one of many that \fBpamrecolor\fP knows by name.
49 .PP
50 The output is a PAM image on standard output. Options control the
51 exact format of the PAM. If you want a PNM (PBM, PGM, or PPM) image,
52 use
53 .BR "pamtopnm" (1)\c
54 \& on the output. There is no
55 need to convert if you will use the image as input to a current Netpbm
56 program, but many other programs don't know what a PAM is.
57
58
59 .UN options
60 .SH OPTIONS
61 .PP
62 In addition to the options common to all programs based on libnetpbm
63 (most notably \fB-quiet\fP, see
64 .UR index.html#commonoptions
65 Common Options
66 .UE
67 \&), \fBpamrecolor\fP recognizes the following
68 command line options:
69
70
71
72 .TP
73 \fB--colorspace\fP=\fIname\fP
74 Designate the color space to use for determining the contribution
75 to luminance of each of the red, green, and blue color channels. For
76 example, in the SMPTE-C color space an RGB color is converted to
77 grayscale by multiplying the red channel by 0.2124132, the green
78 channel by 0.7010437, and the blue channel by 0.0865432 and summing
79 the resulting three products.
80 .sp
81 When you use this option, the input and output images are not true Netpbm
82 images, because the Netpbm image format specifies a particular color space.
83 Instead, you are using a variation on the format in which the sample values in
84 the raster have different meaning. Many programs that ostensibly use Netpbm
85 images actually use a variation with a different color space. For example,
86 .UR http://www.gimp.org/
87 GIMP
88 .UE
89 \& uses sRGB internally and if you
90 have GIMP generate a Netpbm image file, it really generates a variation of
91 the format that uses sRGB.
92 .sp
93 \fBpamrecolor\fP knows the following color spaces (\fIname\fP values):
94
95
96 .TP
97 adobe
98
99 Adobe RGB (1998) with a D65 reference white
100
101 .TP
102 apple
103
104 Apple RGB with a D65 reference white
105
106 .TP
107 cie
108
109 CIE with an Illuminant E reference white
110
111 .TP
112 ntsc
113
114 NTSC RGB with an Illuminant C reference white
115
116 .TP
117 pal
118
119 PAL/SECAM with a D65 reference white
120
121 .TP
122 smpte-c
123
124 SMPTE-C with a D65 reference white
125
126 .TP
127 srgb
128
129 sRGB with a D65 reference white
130
131 .TP
132 wide
133
134 Wide-gamut RGB with a D50 reference white
135
136 .sp
137 The default is "ntsc" because this is the color space that the Netpbm
138 formats and many graphics utilities use. As a counterexample,
139 .UR http://www.gimp.org/
140 GIMP
141 .UE
142 \& uses sRGB as its native color
143 space.
144 .sp
145 The luminance values \fBpamrecolor\fP uses for each of the above come from
146 Bruce Lindbloom's
147 .BR "
148 Computing RGB-to-XYZ and XYZ-to-RGB matrices" (1)\c
149 \& page.
150
151 .TP
152 \fB--rmult\fP=\fIfraction\fP
153 .TP
154 \fB--gmult\fP=\fIfraction\fP
155 .TP
156 \fB--bmult\fP=\fIfraction\fP
157 Instead of selecting a color space by name, you can specify explicitly the
158 contribution of each color channel to the overall luminance as red, green, and
159 blue multipliers. These three options must be used together, and the
160 three \fIfraction\fP values must sum to 1.0. For example, you can specify
161 the ProPhoto (ROMM) RGB color space with
162 "\fB--rmult\fP=0.2880402 \fB--gmult\fP=0.7118741 \fB--bmult\fP=0.0000857".
163
164 .TP
165 \fB--targetcolor\fP=\fIcolor\fP
166 Designate \fIcolor\fP as the target color for the
167 image. \fBpamrecolor\fP will make each pixel as close as possible
168 to \fIcolor\fP subject to the constraint that the luminance must stay the
169 same as in the original image. Specify \fIcolor\fP as in
170 the
171 .UR libnetpbm_image.html#colorname
172 argument of the \fBpnm_parsecolor()\fP library routine
173 .UE
174 \& (e.g.,\ "hotpink" or "#ff69b4").
175 .sp
176 If you specify neither \fB--targetcolor\fP nor
177 \fB--colorfile\fP, \fBpamrecolor\fP will randomly select a target color for
178 each pixel of the input image.
179 .sp
180 You may not specify both \fB-targetcolor\fP and \fB-colorfile\fP.
181
182
183
184 .TP
185 \fB--colorfile\fP=\fIfile\fP
186 Take per-pixel target colors from Netpbm file \fIfile\fP instead
187 of using a single target color for the entire image.
188 \fIfile\fP should be a PPM or color PAM image.
189 If the image in the file wider or taller than the input image,
190 \fBpamrecolor\fP uses only the left and top part of it.
191 If the image is narrower or shorter, \fBpamrecolor\fP considers the
192 image to be repeated in a tile pattern.
193 .sp
194 If you specify neither \fB--targetcolor\fP nor
195 \fB--colorfile\fP, \fBpamrecolor\fP will randomly select a target color for
196 each pixel of the input image.
197 .sp
198 You may not specify both \fB-targetcolor\fP and \fB-colorfile\fP.
199
200 .TP
201 \fB-randomseed=\fP\fIinteger\fP
202 This is the seed for the random number generator that generates the
203 pixels.
204 .sp
205 Use this to ensure you get the same image on separate invocations.
206 .sp
207 By default, \fBpamrecolor\fP uses a seed derived from the time of day
208 and process ID, which gives you fairly uncorrelated results in multiple
209 invocations.
210 .sp
211 This option was new in Netpbm 10.61 (December 2012).
212
213
214
215
216 .UN examples
217 .SH EXAMPLES
218 .PP
219 This command tints an image yellow:
220
221 .nf
222 pamrecolor --targetcolor=yellow colorpic.pam > yellowpic.pam
223
224 .fi
225 .PP
226 This command takes the colors from \fBcolorpicture.ppm\fP and applies
227 them to \fBgraypicture.pgm\fP:
228
229 .nf
230 pamrecolor --colorfile=colorpic.ppm graypic.pgm > colorizedpic.pam
231
232 .fi
233 .PP
234 The grayscale version of \fBcolorizedpic.pam\fP will look just like
235 graypic.pgm. Note that if you use a non-Netpbm tool to do the conversion to
236 grayscale, you may additionally need to specify an
237 appropriate \fB--colorspace\fP value for your conversion tool.
238
239
240 .UN notes
241 .SH NOTES
242 .PP
243 Here are a couple of fun special effects you can produce with
244 \fBpamrecolor\fP:
245
246
247 .IP \(bu
248 Specify a color file that is identical to the input image but with
249 some large, colored text added to it. The text will "magically"
250 vanish when the image is converted to grayscale.
251
252 .IP \(bu
253 Provide a low-contrast grayscale image - perhaps a secret
254 message written in similar shades of gray - as the input file and
255 a colorful but completely different image as the color file. If done
256 carefully, the grayscale image can be hidden by the colorful image.
257 Only people who know to convert the result to grayscale can recover
258 the original grayscale image.
259
260 .IP \(bu
261 Use \fB--targetcolor\fP=tan to make an image look like an
262 old-timey photograph (or, more precisely, a
263 .UR http://en.wikipedia.org/wiki/Photographic_print_toning
264 sepia-toned photograph
265 .UE
266 \& of the late 1800s).
267
268
269
270 .UN history
271 .SH HISTORY
272 .PP
273 Scott Pakin wrote \fBpamrecolor\fP in July 2010.
274 .PP
275 \fBpamrecolor\fP was new in Netpbm 10.52 (September 2010).
276
277
278 .UN author
279 .SH AUTHOR
280 .PP
281 Copyright (C) 2010 Scott
282 Pakin, \[email protected]\fP
283
284
285 .UN seealso
286 .SH SEE ALSO
287
288
289 .IP \(bu
290 .BR "\fBppmtopgm\fP" (1)\c
291 \&
292 .IP \(bu
293 .BR "\fBppmchange\fP" (1)\c
294 \&
295 .IP \(bu
296 .BR "\fBpnmremap\fP" (1)\c
297 \&
298 .SH DOCUMENT SOURCE
299 This manual page was generated by the Netpbm tool 'makeman' from HTML
300 source. The master documentation is at
301 .IP
302 .B http://netpbm.sourceforge.net/doc/pamrecolor.html
303 .PP