diff options
Diffstat (limited to 'upstream/opensuse-leap-15-6/man1/pnmnorm.1')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man1/pnmnorm.1 | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man1/pnmnorm.1 b/upstream/opensuse-leap-15-6/man1/pnmnorm.1 new file mode 100644 index 00000000..95f1417c --- /dev/null +++ b/upstream/opensuse-leap-15-6/man1/pnmnorm.1 @@ -0,0 +1,313 @@ +\ +.\" 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 "Pnmnorm User Manual" 0 "19 December 2014" "netpbm documentation" + +.SH NAME + +pnmnorm - normalize the contrast in a Netpbm image + +.UN synopsis +.SH SYNOPSIS + +\fBpnmnorm\fP + +[\fB-bpercent=\fP\fIpercent\fP | \fB-bvalue=\fP\fIN\fP | \fB-bsingle\fP] + +[\fB-wpercent=\fP\fIpercent\fP | \fB-wvalue=\fP\fIN\fP | \fB-wsingle\fP] + +[\fB-midvalue=\fP\fIN\fP] + +[\fB-middle=N\fP] + +[\fB-maxexpand=\fP\fIpercent\fP] + +[\fB-keephues\fP] + +[\fB-luminosity\fP | \fB-colorvalue\fP | \fB-saturation\fP] + +[\fIppmfile\fP] +.PP +All options can be abbreviated to their shortest unique prefix. +You may use two hyphens instead of one to designate an option. You +may use either white space or an equals sign between an option name +and its value. + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBpnmnorm\fP reads a PNM image (PBM, PGM, or PPM). It normalizes the +contrast by forcing the brightest pixels to white, the darkest pixels to +black, and spreading out the ones in between. It produces the same kind of +file as output. This is pretty useless for a PBM image. +.PP +The program offers two ways of spreading out the pixels in between the +darkest and brightest: linear and quadratic. In the quadratic case, you +specify some in between brightness and specify what brightness that should +become in the output. With those three constraints: the brightness that +becomes black, the brightness that becomes white, and the brightness that +becomes that middle value, \fBpnmnorm\fP computes a quadratic equation that +maps all the other brightnesses from input values to output values. +.PP +The program first determines a mapping of old brightness to new +brightness. For each possible brightness of a pixel, the program +determines a corresponding brightness for the output image. +.PP +Then for each pixel in the image, the program computes a color which has +the desired output brightness and puts that in the output. With a color +image, it is not always possible to compute such a color and retain any +semblance of the original hue, so the brightest and dimmest pixels may only +approximate the desired brightness. +.PP +For a PPM image, you have a choice of three ways to define brightness: + +.IP \(bu +luminosity +.IP \(bu +color value +.IP \(bu +saturation + + +In the case of saturation, "brightness" is pretty much a +misnomer, but you can use the brightness analogy to see what it does. +In the analogy, bright means saturated and dark means unsaturated. +.PP +Note that all of these are different from separately normalizing +the individual color components. +.PP +An alternative way to spread out the brightnesses in an image is +\fBpnmhisteq\fP. \fBpnmhisteq\fP stretches the brightest pixels to +white and the darkest pixels to black, but rather than linearly +adjusting the ones in between, it adjusts them so that there are an +equal number of pixels of each brightness throughout the range. This +gives you more contrast than \fBpnmnorm\fP does, but can considerably +change the picture in exchange. + + +.UN options +.SH OPTIONS +.PP +By default, the darkest 2 percent of all pixels are mapped to +black, and the brightest 1 percent are mapped to white. You can +override this behavior and specify either a different percentage, or +specific brightness values to map to black and to white, or just have +the single greatest brightness map to white and the least brightness map +to black. +.PP +To specify a percentage, use the \fB-bpercent\fP and +\fB-wpercent\fP options, or you can specify the exact pixel values to +be mapped by using the \fB-bvalue\fP and \fB-wvalue\fP options. +You can get appropriate numbers for the options from +\fBppmhist\fP. If you just want to enhance the contrast, then +choose values at elbows in the histogram; e.g. if value 29 represents +3% of the image but value 30 represents 20%, choose 30 for +\fIbvalue\fP. If you want to brighten the image, then set +\fIbvalue\fP to 0 and just fiddle with \fIwvalue\fP; similarly, to +darken the image, set \fIwvalue\fP to maxval and play with +\fIbvalue\fP. +.PP +If you specify both \fB-bvalue\fP and \fB-bpercent\fP, \fBpnmnorm\fP +uses the one that produces the least change. The same goes for +\fB-wvalue\fP and \fB-wpercent\fP. (In Netpbm 10.26 (January 2005), +the \fB-bvalue\fP/\fB-wvalue\fP takes precedence, and before that, +it's a syntax error to specify both). +.PP +If you want to maximize the change instead of minimizing it, just +cascade two runs of \fBpnmnorm\fP, specifying values for the first +and percentages for the second. +.PP +\fB-bpercent\fP and \fB-wpercent\fP values are floating point +decimal. Zero is valid and is the same as \fB-bvalue=0\fP or +\fB-wvalue=\fP\fImaxval\fP, respectively. +.PP +Because there are whole numbers of pixels at each brightness, +\fBpnmnorm\fP obviously can't guarantee the exact percentage, so it +arranges that \fIat least\fP the percentage of pixels you specify +get remapped as promised. +.PP +It is possible for your \fB-bpercent\fP or \fB-wpercent\fP +to overlap your \fB-wvalue\fP or \fB-bvalue\fP, respectively. For +example, you say \fB-bpercent=20\fP and \fB-wvalue=100\fP for an +image in which only 10 percent of the pixels are darker than 100. +In that case, \fBpnmnorm\fP adjusts the percentile value as +required. In the example, it uses 99 as the black value (like +\fB-bvalue=99\fP). +.PP +It is also possible for your \fB-bpercent\fP and \fB-wpercent\fP +options to select the same brightness value for the stretch-to-white +and stretch-to-black value because of the fact that \fBpnmnorm\fP +can't subdivide a histogram cell. E.g. if an image is all brightness +100, then no matter what \fB-bpercent\fP and \fB-wpercent\fP +values you choose, it's the same as saying \fB-bvalue=100 -wvalue=100\fP. +In that case, \fBpnmnorm\fP changes one of the values by 1 to make it +legal. In the example, \fBpnmnorm\fP would either make the black +value 99 or the white value 101. +.PP +Before Netpbm 10.43 (June 2008), \fBpnmnorm\fP fails if the +\fB-wpercent\fP and/or \fB-bpercent\fP values specify an overlap. +.PP +The stretch points are further constrained by the \fB-maxexpand\fP +option. Sometimes, too much contrast is a bad thing. If your +intensities are all concentrated in the middle, \fB-bpercent=2\fP and +\fB-wpercent=1\fP might mean that an intensity of 60 gets stretched +up to 100 and intensity of 20 gets stretched down to zero, for a +range expansion of 150% (from a range of 40 to a range of 100). That +much stretching means two adjacent pixels that used to differ in +intensity by 4 units now differ by 10, and that might be unsightly. +.PP +To specify that the single least brightness in the image should stretch to +black in the output, specify \fB-bsingle\fP. To specify that the single +greatest brightness in the image should stretch to white in the output, +specify \fB-wsingle\fP. \fB-bsingle\fP and \fB-wsingle\fP were new in +Netpbm 10.69 (December 2014). +.PP +So that you can put a limit on the amount of expansion without +having to examine the image first, there is the \fB-maxexpand\fP +option. It specifies the maximum expansion you will tolerate, as an +additional percentage. In the example above, you could say +\fB-maxexpand=50\fP to say you want the range to expand by at most +50%, regardless of your other options. \fBpnmnorm\fP figures out +what intensity to stretch to full intensity and what intensity to +stretch to zero intensity as described above, and then raises the +former and lowers the latter as needed to limit the expansion to the +amount you specified. +.PP +When \fBpnmnorm\fP limits the expansion because of \fB-maxexpand\fP, +it tells you about it with a message like this: +.nf +\f(CW + limiting expansion of 150% to 50% +\fP +.fi +.PP +In any case, \fBpnmnorm\fP tells you exactly what expansion it's +doing, like this: + +.nf +\f(CW + remapping 25..75 to 0..100 +\fP +.fi +.PP +Before Netpbm 10.26 (December 2004), it was not valid to specify both +\fB-bvalue\fP and \fB-bpercent\fP or \fB-wvalue\fP and \fB-wpercent\fP. +.PP +\fB-maxexpand\fP was new in Netpbm 10.32 (February 2006). +.PP +The \fB-keephues\fP option says to keep each pixel the same hue as +it is in the input; just adjust its brightness. You normally want this; +the only reason it is not the default behavior is backward compatibility +with a design mistake. +.PP +By default, \fBpnmnorm\fP normalizes contrast in each component +independently (except that the meaning of the \fB-wpercent\fP and +\fB-bpercent\fP options are based on the overall brightnesses of the +colors, not each component taken separately). So if you have a color +which is intensely red but dimly green, \fBpnmnorm\fP would make the +red more intense and the green less intense, so you end up with a +different hue than you started with. +.PP +When you specify \fB-midvalue=\fP\fIN\fP, \fBpnmnorm\fP uses a quadratic +function to map old brightnesses to new ones, making sure that an old +brightness of \fIN\fP becomes 50% bright in the output. You can override +that 50% default with \fB-middle\fP. The value of \fB-middle\fP is a +floating point number in the range 0 through 1 with 0 being full darkness and +1 full brightness. If your \fB-midvalue\fP and \fB-middle\fP indicate an +ambiguous or impossible quadratic function (e.g. \fB-midvalue\fP is the same +as \fB-bvalue\fP, so an infinite number of quadratic functions +fit), \fBpnmnorm\fP just ignores your \fB-midvalue\fP and maps linearly. + +\fB-midvalue\fP and \fB-middle\fP were new in Netpbm 10.57 (December 2011). +.PP +If you specify \fB-keephues\fP, \fBpnmnorm\fP would likely leave +this pixel alone, since its overall brightness is medium. +.PP +\fB-keephues\fP can cause clipping, because a certain color may be +below a target intensity while one of its components is saturated. +Where that's the case, \fBpnmnorm\fP uses the maximum representable +intensity for the saturated component and the pixel ends up with less +overall intensity, and a different hue, than it is supposed to have. +.PP +This option is meaningless on grayscale images. +.PP +When you \fIdon't\fP specify \fB-keephues\fP, the +\fB-luminosity\fP, \fB-colorvalue\fP, and \fB-saturation\fP options +affect the transfer function (which is the same for all three RGB +components), but are meaningless when it comes to applying the +transfer function (since it is applied to each individual RGB +component). +.PP +Before Netpbm 9.25 (March 2002), there was no \fB-keephues\fP option. +.PP +\fB-luminosity\fP, \fB-colorvalue\fP, and \fB-saturation\fP determine +what property of the pixels \fBpnmnorm\fP normalizes. I.e., what kind of +brightness. You cannot specify more than one of these. +.PP +The \fB-luminosity\fP option says to use the luminosity (i.e. the +"Y" in the YUV or YCbCr color space) as the pixel's brightness. The +luminosity is a measure of how bright a human eye would find the color, +taking into account the fact that the human eye is more sensitive to some +RGB components than others. +.PP +This option is default. +.PP +This option is meaningless on grayscale images. +.PP +Before Netpbm 10.28 (August 2005), there was no \fB-luminosity\fP option, +but its meaning was still the default. +.PP +Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option. +.PP +The \fB-colorvalue\fP option says to use the color value (i.e. the +"V" in the HSV color space) as the pixel's brightness. The +color value is the gamma-adjusted intensity of the most intense RGB +component. +.PP +This option is meaningless on grayscale images. +.PP +Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option. +.PP +The \fB-saturation\fP option says to use the saturation (i.e. the +"S" in the HSV color space) as the pixel's brightness. The +saturation is the ratio of the intensity of the most intense RGB +component to the difference between the intensities of the most and least +intense RGB component (all intensities gamma-adjusted). +.PP +In this case, "brightness" is more of a metaphor than anything. +"bright" means saturated and "dark" means unsaturated. +.PP +This option is meaningless on grayscale images. +.PP +Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option. + + + +.UN seealso +.SH SEE ALSO +.BR "pnmhisteq" (1)\c +\&, +.BR "ppmhist" (1)\c +\&, +.BR "pgmhist" (1)\c +\&, +.BR "pnmgamma" (1)\c +\&, +.BR "ppmbrighten" (1)\c +\&, +.BR "ppmdim" (1)\c +\&, +.BR "pnm" (5)\c +\& +.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/pnmnorm.html +.PP
\ No newline at end of file |