Debian Codegraph @

upstream/debian-unstable/man1/pamaltsat.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 "Pamaltsat User Manual" 1 "14 September 2018" "netpbm documentation"
7
8 .SH NAME
9 pamaltsat - increase or decrease the saturation of an image using one of
10 several alternative methods.
11
12 .UN synopsis
13 .SH SYNOPSIS
14
15 \fBpamaltsat\fP
16 [\fB-method\fP \fIname\fP]
17 [\fB-strength\fP \fInumber\fP]
18 [\fB-linear\fP]
19 [\fIinfile\fP]
20
21 .UN description
22 .SH DESCRIPTION
23 .PP
24 This program is part of
25 .BR "Netpbm" (1)\c
26 \&.
27 .PP
28 \fBpamaltsat\fP decreases or increases the saturation of a Netpbm image by
29 one of various non-standard (\fIalt\fPernative) methods.
30 .PP
31 The input is a Netpbm image from Standard Input or a file named by the
32 arguments. The output is a Netpbm image in the same format written to
33 Standard Output.
34 .PP
35 The most conventional way to change the saturation of an image is what
36 \fBpambrighten\fP does.
37
38
39 .UN examples
40 .SH EXAMPLES
41 .PP
42 To increase saturation by a factor of 2.1 using the
43 logarithmic method:
44
45 .nf
46 \f(CW
47 pamaltsat -method log -strength 2.1 test.ppm
48 \fP
49
50 .fi
51 .PP
52 To convert a color image to grayscale:
53
54 .nf
55 \f(CW
56 pamaltsat -strength 0 test.ppm
57 \fP
58
59 .fi
60
61
62 .UN saturation_methods
63 .SH SATURATION METHODS
64 .PP
65 The following saturation methods are available.
66
67 .SS Logarithmic Method
68 .PP
69 This saturation model is inspired by the concept of
70 .BR "color integrity" (1)\c
71 \&,
72 which works with color in terms of intensity ratios, where intensity is a
73 value of the
74 .UR https://en.wikipedia.org/wiki/Luminosity_function
75 luminosity function
76 .UE
77 \&, rather than brightness, or the numerical value of the sample in
78 the image file. From this viewpoint, it is natural to define the saturation
79 of a color as the ratio of maximum and minimum intensities of its primary
80 components. In order, however, to make saturation an additive value and to
81 endow the \fB-strength\fP parameter with the semantics of a multiplier,
82 it is convenient to operate on the logarithm of that ratio. The addition of
83 such saturations acquires physical sense, and multiplication corresponds to
84 the raising of intensity to the power of the multiplier.
85 .PP
86 With this method, \fBpamaltsat\fP raises the intensity of each component
87 to the power of the \fBstrength\fP value. Since the total intensity of the
88 resulting color will differ from that of the original, it is necessary to
89 restore the intensity by multiplying the component intensities of the
90 saturated color by the ratio of the intensity of the original color to that of
91 the saturated color.
92 .PP
93 Although it is always possible to decrease saturation by any given factor,
94 there are two cases where it cannot be increased. When the total intensity
95 (or brightness) of a color is too high for the desired
96 saturation, \fBpamaltsat\fP applies the maximum possible saturation that
97 keeps the original intensity. For example, any color with at least one
98 component at the maxiumum is already fully saturated. When one of the primary
99 components is zero, the definition of saturation given above no longer works
100 because of a zero in the denominator. \fBpamaltsat\fP offers no special
101 treatment of this situation because it does not create discontinuities and
102 therefore produces no visible defects at reasonable strength levels. When,
103 however, strength approaches infinity, each color tends to its primary
104 component with the highest intensity.
105 .PP
106 This method was invented by Anton Shepelev.
107
108
109 .SS Spectral Method
110 .PP
111 This is the default method. It treats color as a spectrum with three
112 bands: one for the intensity of each primary component. Since neutral gray
113 has a uniform (constant) spectrum, saturation can be measured as the
114 difference of the spectrum of the given color from the uniform spectrum of the
115 same total intensity. The spectral method uses one of the simplest measures
116 of such a difference: the difference between the highest and lowest component
117 intensities, which is an additive value and therefore amenable to
118 multiplication with good physical sense. Although a complete hue-saturation
119 model can be dervied from this approach, \fBpamaltsat\fP need not concern
120 itself with it because it always preserves both hue and total intensity.
121 .PP
122 In order to change saturation, \fBpamaltsat\fP first multiplies the
123 intensity of each component by the desired strength. The saturation of the
124 result is the strength times the saturation of the original, and likewise the
125 total intensity, but it is then restored by subtraction of the neutral gray
126 with a suitable intensity.
127 .PP
128 The effect of this method on each component intensity may be expressed in
129 the following equation:
130 .nf
131
132 sat = orig * strength - Iorig * (strength - 1)
133
134
135 .fi
136 where sat is the saturated
137 sample, orig the original sample,
138 and Iorig the total intensity of
139 the original color.
140 .PP
141 The method is also related to color integrity because both its operations
142 are part of that concept: multiplication of component intensities by the same
143 quotient is an important operation because changes brightness but keeps color
144 balance, and subtraction of a constant from all component intensities is
145 described by the inventor of color integrity as 'subtraction of
146 white.'
147 .PP
148 This procedure may produce both negative and over-unity component
149 intensities. For such samples, \fBpamaltsat\fP decreases the strength to the
150 highest value that keeps the resulting color in range.
151 .PP
152 This method was invented by Anton Shepelev.
153
154
155 .UN options
156 .SH OPTIONS
157 .PP
158 In addition to the options common to all programs based on libnetpbm
159 (most notably \fB-quiet\fP, see
160 .UR index.html#commonoptions
161 Common Options
162 .UE
163 \&), \fBpamaltsat\fP recognizes the following
164 command line options:
165
166
167 .TP
168 \fB-method\fP \fImethod\fP
169 specifies the saturation method to use:
170 .TS
171 method name option value
172 Logarithmic \f(CWlog \fP
173 Spectral \f(CWspectrum\fP
174 .TE
175 .sp
176 The default is \fBspectrum\fP
177
178 .TP
179 \fB-strength\fP \fIstrength\fP
180 This specifies a real nonnegative factor whereby to modify saturation. A
181 value greater than unity will increase saturation, whereas a value less than
182 unity will decrease it. Unity will leave the image unchanged, and zero will
183 produce greyscale output according to Rec 709.
184
185 \fBpamaltsat\fP preserves the total intensity of each pixel and never
186 affects neutral gray pixels.
187 .sp
188 This option is mandatory.
189
190 .TP
191 \fB-linear\fP
192 This tells \fBpamaltsat\fP that the input is the intensity-linear
193 variation of a Netpbm image forat, in which the samples are proportional to
194 light intensity rather than to brightness, as they are in true-or
195 gamma-adjusted- Netpbm image formats.
196
197
198 .UN usage_notes
199 .SH USAGE NOTES
200 .PP
201 Since \fBpamaltsat\fP does not affect neutral colors, you should adjust
202 the color balance before saturation. You can do this with \fBpamlevels\fP.
203
204
205 .UN extensibility
206 .SH EXTENSIBILITY
207
208 \fBpamaltsat\fP is written with an eye to extending it with new saturation
209 methods, which programmers are welcome to contribute. The only requirement is
210 that every new method depend on a single strength parameter with the semantics
211 described under the \fB-strength\fP command-line option.
212
213
214 .UN seealso
215 .SH SEE ALSO
216 .PP
217 .BR "pambrighten" (1)\c
218 \&,
219 .BR "ppmflash" (1)\c
220 \&,
221
222
223 .UN author
224 .SH AUTHOR
225 .PP
226 This program was first submitted by Anton Shepelev
227 (\[email protected]\fP).
228
229 .UN history
230 .SH HISTORY
231 .PP
232 \fBpamaltsat\fP was new in Netpbm 10.84 (September 2018).
233
234
235 .UN index
236 .SH Table Of Contents
237
238 .IP \(bu
239 .UR #synopsis
240 SYNOPSIS
241 .UE
242 \&
243 .IP \(bu
244 .UR #description
245 DESCRIPTION
246 .UE
247 \&
248 .IP \(bu
249 .UR #examples
250 EXAMPLES
251 .UE
252 \&
253 .IP \(bu
254 .UR #saturation_methods
255 SATURATION METHODS
256 .UE
257 \&
258 .IP \(bu
259 .UR #options
260 OPTIONS
261 .UE
262 \&
263 .IP \(bu
264 .UR #usage_notes
265 USAGE NOTES
266 .UE
267 \&
268 .IP \(bu
269 .UR #extensibility
270 EXTENSIBILITY
271 .UE
272 \&
273 .IP \(bu
274 .UR #seealso
275 SEE ALSO
276 .UE
277 \&
278 .IP \(bu
279 .UR #author
280 AUTHOR
281 .UE
282 \&
283 .IP \(bu
284 .UR #history
285 HISTORY
286 .UE
287 \&
288 .SH DOCUMENT SOURCE
289 This manual page was generated by the Netpbm tool 'makeman' from HTML
290 source. The master documentation is at
291 .IP
292 .B http://netpbm.sourceforge.net/doc/pamaltsat.html
293 .PP