diff options
Diffstat (limited to 'pnmnorm.html')
| -rw-r--r-- | pnmnorm.html | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/pnmnorm.html b/pnmnorm.html new file mode 100644 index 00000000..6ade6a3f --- /dev/null +++ b/pnmnorm.html @@ -0,0 +1,241 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML><HEAD><TITLE>Pnmnorm User Manual</TITLE></HEAD> +<BODY> +<H1>pnmnorm</H1> +Updated: 6 January 2006 +<BR> +<A HREF="#index">Table Of Contents</A> + +<H2>NAME</H2> + +pnmnorm - normalize the contrast in a Netbpm image + +<H2 id="synopsis">SYNOPSIS</H2> + +<B>pnmnorm</B> + +[<B>-bpercent=</B><I>N</I> | <B>-bvalue=</B><I>N</I>] + +[<B>-wpercent=</B><I>N</I> | <B>-wvalue=</B><I>N</I>] + +[<b>-maxexpand</b> + +[<B>-keephues</B>] + +[<B>-luminosity</B> | <B>-colorvalue</B> | <B>-saturation</B>] + +[<I>ppmfile</I>] + + +<P>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. + +<H2 id="description">DESCRIPTION</H2> + +<p>This program is part of <a href="index.html">Netpbm</a>. + +<p><b>pnmnorm</b> 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 linearly rescaling the ones in between; and +produces the same kind of file as output. This is pretty useless for +a PBM image. + +<P>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. + +<P>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. + +<p>For a PPM image, you have a choice of three different ways to +define brightness: +<ol> +<li>luminosity +<li>color value +<li>saturation +</ol> + +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. + +<P>Note that all of these are different from separately normalizing +the individual color components. + +<p>An alternative way to spread out the brightnesses in an image is +<b>pnmhisteq</b>. <b>pnmhisteq</b> 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 <b>pnmnorm</b> does, but can considerably +change the picture in exchange. + + +<H2 id="options">OPTIONS</H2> + +<P>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 these percentages by using the <B>-bpercent</B> and +<B>-wpercent</B> options, or you can specify the exact pixel values to +be mapped by using the <B>-bvalue</B> and <B>-wvalue</B> options. +You can get appropriate numbers for the options from +<b>ppmhist</b>. 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 +<I>bvalue</I>. If you want to brighten the image, then set +<I>bvalue</I> to 0 and just fiddle with <I>wvalue</I>; similarly, to +darken the image, set <I>wvalue</I> to maxval and play with +<I>bvalue</I>. + +<p>If you specify both <b>-bvalue</b> and <b>-bpercent</b>, <b>pnmnorm</b> +uses the one that produces the least change. The same goes for +<b>-wvalue</b> and <b>-wpercent</b>. + +<p>If you want to maximize the change instead of minimizing it, just +cascade two runs of <b>pnmnorm</b>, specifying values for the first +and percentages for the second. + +<p>This is further constrained by the <b>-maxexpand</b> option. +Sometimes, too much contrast is a bad thing. If your intensities are +all concentrated in the middle, <b>-bpercent=2</b> and +<b>-wpercent=1</b> might mean that an intensity of 60 gets stretched +up to 100 and and intensity of 40 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. + +<p>So that you can put a limit on the amount of expansion without +having to examine the image first, there is the <b>-maxexpand</b> +option. It specifies the maximum expansion you will tolerate, as an +additional per centage. In the example above, you could say +<b>-maxexpand=50</b> to say you want the range to expand by at most +50%, regardless of your other options. <b>pnmnorm</b> 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. + +<p>When <b>pnmnorm</b> limits the expansion due to <b>-maxexpand</b>, +it tells you about it with a message like this: +<pre> +<tt> + limiting expansion of 150% to 50% +</tt> +</pre> + +<p>In any case, <b>pnmnorm</b> tells you exactly what expansion it's +doing, like this: + +<pre> +<tt> + remapping 25..75 to 0..100 +</tt> +</pre> + +<p>Before Netpbm 10.26 (December 2004), it was not valid to specify both +<b>-bvalue</b> and <b>-bpercent</b> or <b>-wvalue</b> and <b>-wpercent</b>. + +<p><b>-maxexpand</b> was new in Netpbm 10.32 (February 2006). + +<P>The <B>-keephues</B> 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. + +<p>By default, <B>pnmnorm</B> normalizes contrast in each component +independently (except that the meaning of the <B>-wpercent</B> and +<B>-bpercent</B> 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, <B>pnmnorm</B> would make the +red more intense and the green less intense, so you end up with a +different hue than you started with. + +<P>If you specify <B>-keephues</B>, <B>pnmnorm</B> would likely leave +this pixel alone, since its overall brightness is medium. + +<P><B>-keephues</B> 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, <B>pnmnorm</B> 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. + +<P>This option is meaningless on grayscale images. + +<p>When you <em>don't</em> specify <b>-keephues</b>, the +<b>-luminosity</b>, <b>-colorvalue</b>, and <b>-saturation</b> 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). + +<P>Before Netpbm 9.25 (March 2002), there was no <B>-keephues</B> option. + +<p><b>-luminosity</b>, <b>-colorvalue</b>, and <b>-saturation</b> determine +what property of the pixels <b>pnmnorm</b> normalizes. I.e., what kind of +brightness. You cannot specify more than one of these. + +<P>The <B>-luminosity</B> 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. + +<p>This option is default. + +<P>This option is meaningless on grayscale images. + +<P>Before Netpbm 10.28 (August 2005), there was no <B>-luminosity</B> option, +but its meaning was still the default. + +<P>Before Netpbm 10.28 (August 2005), there was no <B>-colorvalue</B> option. + +<P>The <B>-colorvalue</B> 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. + +<P>This option is meaningless on grayscale images. + +<P>Before Netpbm 10.28 (August 2005), there was no <B>-colorvalue</B> option. + +<p>The <b>-saturation</b> 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). + +<p>In this case, "brightness" is more of a metaphor than anything. +"bright" means saturated and "dark" means unsaturated. + +<p>This option is meaningless on grayscale images. + +<P>Before Netpbm 10.28 (August 2005), there was no <B>-colorvalue</B> option. + + + +<H2 id="seealso">SEE ALSO</H2> + +<B><A HREF="pnmhisteq.html">pnmhisteq</A></B>, +<B><A HREF="ppmhist.html">ppmhist</A></B>, +<B><A HREF="pgmhist.html">pgmhist</A></B>, +<B><A HREF="pnmgamma.html">pnmgamma</A></B>, +<B><A HREF="ppmbrighten.html">ppmbrighten</A></B>, +<B><A HREF="ppmdim.html">ppmdim</A></B>, +<B><A HREF="pnm.html">pnm</A></B> + +<HR> +<A NAME="index"> </A> +<H2>Table Of Contents</H2> +<UL> +<LI><A HREF="#lbAC">SYNOPSIS</A> +<LI><A HREF="#lbAD">DESCRIPTION</A> +<LI><A HREF="#lbAE">OPTIONS</A> +<LI><A HREF="#lbAF">SEE ALSO</A> +</UL> +</BODY> +</HTML> |