summary refs log tree commit diff
path: root/pamrecolor.html
blob: 38254713b310f1073dca94ee5d40ab0234a54066 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.3//EN">
<html><head><title>Pamrecolor User Manual</title></head>
<body>
<h1>pamrecolor</h1>
Updated: 31 July 2010
<br>
<a href="#index">Table Of Contents</a>

<h2>NAME</h2>
pamrecolor - alter colors without affecting luminance

<h2 id="synopsis">SYNOPSIS</h2>

<p>
<b>pamrecolor</b>
[<b>--colorspace</b>=<i>name</i>]
[<b>--rmult</b>=<i>fraction</i>]
[<b>--gmult</b>=<i>fraction</i>]
[<b>--bmult</b>=<i>fraction</i>]
[<b>--targetcolor</b>=<i>color</i>]
[<b>--colorfile</b>=<i>file</i>]
[<b>-randomseed=</b><i>integer</i>]

[<i>infile</i>]


<p>Minimum unique abbreviation of option is acceptable.  You may use double
hyphens instead of single hyphen to denote options.  You may use white
space in place of the equals sign to separate an option name from its value.

<h2 id="description">DESCRIPTION</h2>

<p>This program is part of <a href="index.html">Netpbm</a>.

<p><b>pamrecolor</b> changes an image's colors to be as close as
possible to given target colors but with the constraint that the
luminance not be modified.  That is, the original image and the target
image will look identical if both are converted to grayscale
(e.g. with
<a href="ppmtopgm.html">ppmtopgm</a>).  You can have <b>pamrecolor</b> select
target colors randomly, specify a single hue for the entire image, or take the
target colors from a target image.

<p>In addition to real Netpbm images, <b>pamrecolor</b> works on pseudo-Netpbm
images based on arbitrary color spaces.  You can define the color space
explicitly or choose one of many that <b>pamrecolor</b> knows by name.

<p>The output is a PAM image on standard output.  Options control the
exact format of the PAM.  If you want a PNM (PBM, PGM, or PPM) image,
use <a href="pamtopnm.html">pamtopnm</a> on the output.  There is no
need to convert if you will use the image as input to a current Netpbm
program, but many other programs don't know what a PAM is.


<h2 id="options">OPTIONS</h2>

<p>In addition to the options common to all programs based on libnetpbm
(most notably <b>-quiet</b>, see <a href="index.html#commonoptions">
Common Options</a>), <b>pamrecolor</b> recognizes the following
command line options:

<dl>

<dt><b>--colorspace</b>=<i>name</i></dt>
<dd>Designate the color space to use for determining the contribution
to luminance of each of the red, green, and blue color channels.  For
example, in the SMPTE-C color space an RGB color is converted to
grayscale by multiplying the red channel by 0.2124132, the green
channel by 0.7010437, and the blue channel by 0.0865432 and summing
the resulting three products.

<p>When you use this option, the input and output images are not true Netpbm
images, because the Netpbm image format specifies a particular color space.
Instead, you are using a variation on the format in which the sample values in
the raster have different meaning.  Many programs that ostensibly use Netpbm
images actually use a variation with a different color space.  For example,
<a href="http://www.gimp.org/">GIMP</a> uses sRGB internally and if you
have GIMP generate a Netpbm image file, it really generates a variation of
the format that uses sRGB.

<p><b>pamrecolor</b> knows the following color spaces (<i>name</i> values):

  <dl>
  <dt>adobe</dt>
  <dd>Adobe RGB (1998) with a D65 reference white</dd>

  <dt>apple</dt>
  <dd>Apple  RGB with a D65 reference white</dd>

  <dt>cie</dt>
  <dd>CIE with an Illuminant E reference white</dd>

  <dt>ntsc</dt>
  <dd>NTSC RGB with an Illuminant C reference white</dd>

  <dt>pal</dt>
  <dd>PAL/SECAM with a D65 reference white</dd>

  <dt>smpte-c</dt>
  <dd>SMPTE-C with a D65 reference white</dd>

  <dt>srgb</dt>
  <dd>sRGB with a D65 reference white</dd>

  <dt>wide</dt>
  <dd>Wide-gamut RGB with a D50 reference white</dd>
  </dl>

<p>The default is "ntsc" because this is the color space that the Netpbm
formats and many graphics utilities use.  As a counterexample,
<a href="http://www.gimp.org/">GIMP</a> uses sRGB as its native color
space.

<p>The luminance values <b>pamrecolor</b> uses for each of the above come from
Bruce Lindbloom's
<a href="http://www.brucelindbloom.com/index.html?Eqn_RGB_XYZ_Matrix.html">
Computing RGB-to-XYZ and XYZ-to-RGB matrices</a> page.</dd>

<dt><b>--rmult</b>=<i>fraction</i></dt>
<dt><b>--gmult</b>=<i>fraction</i></dt>
<dt><b>--bmult</b>=<i>fraction</i></dt>

<dd>Instead of selecting a color space by name, you can specify explicitly the
contribution of each color channel to the overall luminance as red, green, and
blue multipliers.  These three options must be used together, and the
three <i>fraction</i> values must sum to 1.0.  For example, you can specify
the ProPhoto (ROMM) RGB color space with
"<b>--rmult</b>=0.2880402 <b>--gmult</b>=0.7118741 <b>--bmult</b>=0.0000857".</dd>

<dt><b>--targetcolor</b>=<i>color</i></dt>
<dd>Designate <i>color</i> as the target color for the
image.  <b>pamrecolor</b> will make each pixel as close as possible
to <i>color</i> subject to the constraint that the luminance must stay the
same as in the original image.  Specify <i>color</i> as in
the <a href="libnetpbm_image.html#colorname">argument of the <b>pnm_parsecolor()</b>
library routine</a> (e.g.,&nbsp;"hotpink" or "#ff69b4").

<p>If you specify neither <b>--targetcolor</b> nor
<b>--colorfile</b>, <b>pamrecolor</b> will randomly select a target color for
each pixel of the input image.

<p>You may not specify both <b>-targetcolor</b> and <b>-colorfile</b>.

</dd>

<dt><b>--colorfile</b>=<i>file</i></dt>
<dd>Take per-pixel target colors from Netpbm file <i>file</i> instead
of using a single target color for the entire image.
<i>file</i> should be a PPM or color PAM image.
If the image in the file wider or taller than the input image,
<b>pamrecolor</b> uses only the left and top part of it.
If the image is narrower or shorter, <b>pamrecolor</b> considers the
image to be repeated in a tile pattern.

<p>If you specify neither <b>--targetcolor</b> nor
<b>--colorfile</b>, <b>pamrecolor</b> will randomly select a target color for
each pixel of the input image.

<p>You may not specify both <b>-targetcolor</b> and <b>-colorfile</b>.

<dt><b>-randomseed=</b><i>integer</i>

<dd>This is the seed for the random number generator that generates the
pixels.

<p>Use this to ensure you get the same image on separate invocations.

<p>By default, <b>pamrecolor</b> uses a seed derived from the time of day
and process ID, which gives you fairly uncorrelated results in multiple
invocations.

<p>This option was new in Netpbm 10.61 (December 2012).

</dl>


<h2 id="examples">EXAMPLES</h2>

<p>This command tints an image yellow:

<pre>
    pamrecolor --targetcolor=yellow colorpic.pam &gt; yellowpic.pam
</pre>

<p>This command takes the colors from <b>colorpicture.ppm</b> and applies
them to <b>graypicture.pgm</b>:

<pre>
    pamrecolor --colorfile=colorpic.ppm graypic.pgm &gt; colorizedpic.pam
</pre>

<p>The grayscale version of <b>colorizedpic.pam</b> will look just like
graypic.pgm.  Note that if you use a non-Netpbm tool to do the conversion to
grayscale, you may additionally need to specify an
appropriate <b>--colorspace</b> value for your conversion tool.


<h2 id="notes">NOTES</h2>

<p>Here are a couple of fun special effects you can produce with
<b>pamrecolor</b>:

<ul>
<li>Specify a color file that is identical to the input image but with
some large, colored text added to it.  The text will "magically"
vanish when the image is converted to grayscale.

<li>Provide a low-contrast grayscale image &mdash; perhaps a secret
message written in similar shades of gray &mdash; as the input file and
a colorful but completely different image as the color file.  If done
carefully, the grayscale image can be hidden by the colorful image.
Only people who know to convert the result to grayscale can recover
the original grayscale image.

<li>Use <b>--targetcolor</b>=tan to make an image look like an
old-timey photograph (or, more precisely, a
<a href="http://en.wikipedia.org/wiki/Photographic_print_toning">sepia-toned
photograph</a> of the late 1800s).
</ul>


<h2 id="history">HISTORY</h2>

<p>Scott Pakin wrote <b>pamrecolor</b> in July 2010.

<p><b>pamrecolor</b> was new in Netpbm 10.52 (September 2010).


<h2 id="author">AUTHOR</h2>

<p>Copyright (C) 2010 Scott
Pakin, <a href="mailto:scott+pbm@pakin.org.">scott+pbm@pakin.org.</a>


<h2 id="seealso">SEE ALSO</h2>

<ul>
<li><a href="ppmtopgm.html"><b>ppmtopgm</b></a>
<li><a href="ppmchange.html"><b>ppmchange</b></a>
<li><a href="pnmremap.html"><b>pnmremap</b></a>
</ul>


<hr>

<h2 id="index">Table Of Contents</h2>

<ul>
<li><a href="#synopsis">SYNOPSIS</a>
<li><a href="#description">DESCRIPTION</a>
<li><a href="#options">OPTIONS</a>
<li><a href="#examples">EXAMPLES</a>
<li><a href="#notes">NOTES</a>
<li><a href="#history">HISTORY</a>
<li><a href="#author">AUTHOR</a>
<li><a href="#seealso">SEE ALSO</a>
</ul>

</body>
</html>