1 files changed, 356 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/pnmnorm.1 b/upstream/debian-unstable/man1/pnmnorm.1
new file mode 100644
index 00000000..9d108f92
--- /dev/null
+++ b/upstream/debian-unstable/man1/pnmnorm.1
@@ -0,0 +1,356 @@
+\
+.\" 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" 1 "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
+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
+\&), \fBpnmnorm\fP recognizes the following
+command line 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.
+
+
+.TP
+\fB-bpercent\fP
+.TP
+\fB-wpercent\fP
+.TP
+\fB-bvalue\fP
+.TP
+\fB-wvalue\fP
+.sp
+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.
+.sp
+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).
+.sp
+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.
+.sp
+\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.
+.sp
+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.
+.sp
+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).
+.sp
+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.
+.sp
+Before Netpbm 10.43 (June 2008), \fBpnmnorm\fP fails if the
+\fB-wpercent\fP and/or \fB-bpercent\fP values specify an overlap.
+.sp
+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.
+
+.TP
+\fB-bsingle\fP
+.sp
+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).
+
+.TP
+\fB-maxexpand\fP
+.sp
+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.
+.sp
+When \fBpnmnorm\fP limits the expansion because of \fB-maxexpand\fP,
+it tells you about it with a message like this:
+.nf
+
+    limiting expansion of 150% to 50%
+
+
+.fi
+.sp
+In any case, \fBpnmnorm\fP tells you exactly what expansion it's
+doing, like this:
+
+.nf
+
+    remapping 25..75 to 0..100
+
+
+.fi
+.sp
+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.
+.sp
+\fB-maxexpand\fP was new in Netpbm 10.32 (February 2006).
+
+.TP
+\fB-keephues\fP
+.sp
+This 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.
+.sp
+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.
+
+.TP
+\fB-midvalue=\fP\fIN\fP
+.TP
+\fB-middle=\fP\fIN\fP
+.sp
+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).
+.sp
+If you specify \fB-keephues\fP, \fBpnmnorm\fP would likely leave
+this pixel alone, since its overall brightness is medium.
+.sp
+\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.
+.sp
+This option is meaningless on grayscale images.
+.sp
+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).
+.sp
+Before Netpbm 9.25 (March 2002), there was no \fB-keephues\fP option.
+
+.TP
+\fB-luminosity\fP
+.TP
+\fB-colorvalue\fP
+.TP
+\fB-saturation\fP
+.sp
+\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.
+.sp
+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.
+.sp
+This option is default.
+.sp
+This option is meaningless on grayscale images.
+.sp
+Before Netpbm 10.28 (August 2005), there was no \fB-luminosity\fP option,
+but its meaning was still the default.
+.sp
+Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.
+.sp
+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.
+.sp
+This option is meaningless on grayscale images.
+.sp
+Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.
+.sp
+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).
+.sp
+In this case, "brightness" is more of a metaphor than anything.
+"bright" means saturated and "dark" means unsaturated.
+.sp
+This option is meaningless on grayscale images.
+.sp
+Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmhisteq" (1)\c
+\&,
+.BR "pamlevels" (1)\c
+\&,
+.BR "ppmhist" (1)\c
+\&,
+.BR "pgmhist" (1)\c
+\&,
+.BR "pambrighten" (1)\c
+\&,
+.BR "ppmdim" (1)\c
+\&,
+.BR "pnmgamma" (1)\c
+\&,
+.BR "pnm" (1)\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