diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/pamaltsat.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/pamaltsat.1 | 303 |
1 files changed, 303 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/pamaltsat.1 b/upstream/mageia-cauldron/man1/pamaltsat.1 new file mode 100644 index 00000000..8f8442d3 --- /dev/null +++ b/upstream/mageia-cauldron/man1/pamaltsat.1 @@ -0,0 +1,303 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Pamaltsat User Manual" 0 "14 September 2018" "netpbm documentation" + +.SH NAME +pamaltsat - increase or decrease the saturation of an image using one of +several alternative methods. + +.UN synopsis +.SH SYNOPSIS + +\fBpamaltsat\fP +[\fB-method\fP \fIname\fP] +[\fB-strength\fP \fInumber\fP] +[\fB-linear\fP] +[\fIinfile\fP] + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBpamaltsat\fP decreases or increases the saturation of a Netpbm image by +one of various non-standard (\fIalt\fPernative) methods. +.PP +The input is a Netpbm image from Standard Input or a file named by the +arguments. The output is a Netpbm image in the same format written to +Standard Output. +.PP +The most conventional way to change the saturation of an image is what +\fBpambrighten\fP does. + + +.UN examples +.SH EXAMPLES +.PP +To increase saturation by a factor of 2.1 using the +logarithmic method: + +.nf +\f(CW + pamaltsat -method log -strength 2.1 test.ppm +\fP + +.fi +.PP +To convert a color image to grayscale: + +.nf +\f(CW + pamaltsat -strength 0 test.ppm +\fP + +.fi + + +.UN saturation_methods +.SH SATURATION METHODS +.PP +The following saturation methods are available. + +.SS Logarithmic Method +.PP +This saturation model is inspired by the concept of +.BR "color integrity" (1)\c +\&, +which works with color in terms of intensity ratios, where intensity is a +value of the +.UR https://en.wikipedia.org/wiki/Luminosity_function +luminosity function +.UE +\&, rather than brightness, or the numerical value of the sample in +the image file. From this viewpoint, it is natural to define the saturation +of a color as the ratio of maximum and minimum intensities of its primary +components. In order, however, to make saturation an additive value and to +endow the \fB-strength\fP parameter with the semantics of a multiplier, +it is convenient to operate on the logarithm of that ratio. The addition of +such saturations acquires physical sense, and multiplication corresponds to +the raising of intensity to the power of the multiplier. +.PP +With this method, \fBpamaltsat\fP raises the intensity of each component +to the power of the \fBstrength\fP value. Since the total intensity of the +resulting color will differ from that of the original, it is necessary to +restore the intensity by multiplying the component intensities of the +saturated color by the ratio of the intensity of the original color to that of +the saturated color. +.PP +Although it is always possible to decrease saturation by any given factor, +there are two cases where it cannot be increased. When the total intensity +(or brightness) of a color is too high for the desired +saturation, \fBpamaltsat\fP applies the maximum possible saturation that +keeps the original intensity. For example, any color with at least one +component at the maxiumum is already fully saturated. When one of the primary +components is zero, the definition of saturation given above no longer works +because of a zero in the denominator. \fBpamaltsat\fP offers no special +treatment of this situation because it does not create discontinuities and +therefore produces no visible defects at reasonable strength levels. When, +however, strength approaches infinity, each color tends to its primary +component with the highest intensity. +.PP +This method was invented by Anton Shepelev. + + +.SS Spectral Method +.PP +This is the default method. It treats color as a spectrum with three +bands: one for the intensity of each primary component. Since neutral gray +has a uniform (constant) spectrum, saturation can be measured as the +difference of the spectrum of the given color from the uniform spectrum of the +same total intensity. The spectral method uses one of the simplest measures +of such a difference: the difference between the highest and lowest component +intensities, which is an additive value and therefore amenable to +multiplication with good physical sense. Although a complete hue-saturation +model can be dervied from this approach, \fBpamaltsat\fP need not concern +itself with it because it always preserves both hue and total intensity. +.PP +In order to change saturation, \fBpamaltsat\fP first multiplies the +intensity of each component by the desired strength. The saturation of the +result is the strength times the saturation of the original, and likewise the +total intensity, but it is then restored by subtraction of the neutral gray +with a suitable intensity. +.PP +The effect of this method on each component intensity may be expressed in +the following equation: +.nf + + sat = orig * strength - Iorig * (strength - 1) + + +.fi +where sat is the saturated +sample, orig the original sample, +and Iorig the total intensity of +the original color. +.PP +The method is also related to color integrity because both its operations +are part of that concept: multiplication of component intensities by the same +quotient is an important operation because changes brightness but keeps color +balance, and subtraction of a constant from all component intensities is +described by the inventor of color integrity as 'subtraction of +white.' +.PP +This procedure may produce both negative and over-unity component +intensities. For such samples, \fBpamaltsat\fP decreases the strength to the +highest value that keeps the resulting color in range. +.PP +This method was invented by Anton Shepelev. + + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBpamaltsat\fP recognizes the following +command line options: + + +.TP +\fB-method\fP \fImethod\fP +specifies the saturation method to use: +.TS +method name option value +Logarithmic \f(CWlog \fP +Spectral \f(CWspectrum\fP +.TE +.sp +The default is \fBspectrum\fP + +.TP +\fB-strength\fP \fIstrength\fP +This specifies a real nonnegative factor whereby to modify saturation. A +value greater than unity will increase saturation, whereas a value less than +unity will decrease it. Unity will leave the image unchanged, and zero will +produce greyscale output according to Rec 709. + +\fBpamaltsat\fP preserves the total intensity of each pixel and never +affects neutral gray pixels. +.sp +This option is mandatory. + +.TP +\fB-linear\fP +This tells \fBpamaltsat\fP that the input is the intensity-linear +variation of a Netpbm image forat, in which the samples are proportional to +light intensity rather than to brightness, as they are in true-or +gamma-adjusted- Netpbm image formats. + + +.UN usage_notes +.SH USAGE NOTES +.PP +Since \fBpamaltsat\fP does not affect neutral colors, you should adjust +the color balance before saturation. You can do this with \fBpamlevels\fP. + + +.UN extensibility +.SH EXTENSIBILITY + +\fBpamaltsat\fP is written with an eye to extending it with new saturation +methods, which programmers are welcome to contribute. The only requirement is +that every new method depend on a single strength parameter with the semantics +described under the \fB-strength\fP command-line option. + + +.UN seealso +.SH SEE ALSO +.PP +.BR "pambrighten" (1)\c +\&, +.BR "ppmflash" (1)\c +\&, + + +.UN author +.SH AUTHOR +.PP +This program was first submitted by Anton Shepelev +(\fIanton.txt@gmail.com\fP). + +.UN history +.SH HISTORY +.PP +\fBpamaltsat\fP was new in Netpbm 10.84 (September 2018). + + +.UN index +.SH Table Of Contents + +.IP \(bu + +.UR #synopsis +SYNOPSIS +.UE +\& +.IP \(bu + +.UR #description +DESCRIPTION +.UE +\& +.IP \(bu + +.UR #examples +EXAMPLES +.UE +\& +.IP \(bu + +.UR #saturation_methods +SATURATION METHODS +.UE +\& +.IP \(bu + +.UR #options +OPTIONS +.UE +\& +.IP \(bu + +.UR #usage_notes +USAGE NOTES +.UE +\& +.IP \(bu + +.UR #extensibility +EXTENSIBILITY +.UE +\& +.IP \(bu + +.UR #seealso +SEE ALSO +.UE +\& +.IP \(bu + +.UR #author +AUTHOR +.UE +\& +.IP \(bu + +.UR #history +HISTORY +.UE +\& +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pamaltsat.html +.PP
\ No newline at end of file |