.TL
Ppmbrighten User Manual
.SH 1
ppmbrighten
.LP
Updated: 09 January 2003
.br
Table Of Contents
.SH 2
NAME
.LP
ppmbrighten - change a PPM image's Saturation and Value
.SH 2
SYNOPSIS
.LP
\fBppmbrighten\fR
[\fB-normalize\fR]
[\fB-saturation \fR[\fB+\fR|\fB-\fR\fIsaturation_percent\fR]]
[\fB-value \fR[\fB+\fR|\fB-\fR\fIvalue_percent\fR]]
\fIppmfile\fR
<?makeman .SH OPTION USAGE ?>
.LP
All options can be abbreviated to their shortest unique prefix.
.SH 2
DESCRIPTION
.LP
.LP
This program is part of Netpbm.
.LP
\fBppmbrighten\fR increases or decreases the Saturation and Value
(from the HSV color space) of each pixel of a PPM image.  You specify
the per centage change for each of those parameters.
.LP
You can also remap the colors of the pixels so their Values cover
the full range of possible Values.
.LP
Hue-Saturation-Value, or HSV, is one way to represent a color, like
the more well-known RGB.  Hue, Saturation, and Value are numbers in
the range from 0 to 1.  We always capitalize them in this document
when we mean the number from the HSV color space, especially since
"value" as a conventional English word has a much more abstract
meaning.
.LP
Value is a measure of how much total light intensity is in the
color, relative to some specified maximum (the PPM format is also
defined in terms of a specified maximum intensity -- For the purposes
of this program, they are the same).  In particular, it is the
intensity of the most intense primary color component of the color
divided by the maximum intensity possible for a component.  Zero Value
means black.  White has full Value.
.LP
Hue is an indication of the secondary color with the same intensity
that most closely approximates the color.  A secondary color is made
of a combination of at most two of the primary colors.
.LP
Saturation is a measure of how close the color is to the color
indicated by the Hue and Value.  A lower number means more light of
the third primary color must be added to get the exact color.  Full
Saturation means the color is a secondary color.  Zero Saturation
means the color is gray (or black or white).  Decreasing the
saturation of a color tends to make it washed out.
.LP
If it is impossible to increase the Value of a pixel by the amount you
specify (e.g. the Value is .5 and you specify +200%), \fBppmbrighten\fR
increases it to full Value instead.
.LP
If it is impossible to increase the Saturation of a pixel by the amount
you specify (e.g. it is already half saturated and you specify +200%),
\fBppmbrighten\fR increases it to full Saturation instead.
.LP
For a simpler kind of brightening, you can use \fBpamfunc
-multiplier\fR simply to increase the intensity of each pixel by a
specified per centage, clipping each RGB component where the
calculated intensity would exceed full intensity.  Thus, the brightest
colors in the image would change chromaticity in addition to not
getting the specified intensity boost.  For decreasing
brightness, \fBpamfunc\fR should do the same thing as
\fBppmbrighten\fR.
.LP
\fBppmflash\fR does another kind of brightening.  It changes the
color of each pixel to bring it a specified per centage closer to white.
This increases the value and saturation.
.SH 2
EXAMPLES
.LP
.LP
To double the Value of each pixel:
.DS L
ppmbrighten -v 100
.DE
.LP
To double the Saturation and halve the value of each pixel:
.DS L
ppmbrighten -s 100 -v -50
.DE
.SH 2
OPTIONS
.LP
.RS
.IP "\fB-value \fR\fIvalue_percent\fR"
This option specifies the amount, as a per centage, by which you want
to change the Value of each pixel.  It may be negative.
.IP "\fB-saturation \fR\fIvalue_percent\fR"
This option specifies the amount, as a per centage, by which you want
to change the Saturation of each pixel.  It may be negative.
.IP "\fB-normalize\fR"
This option causes \fBppmbrighten\fR to linearly remap the Values
of the pixels to cover the range 0 to 1.  The option name is wrong --
this operation is not normalization (it was named in error and the
name has been kept for backward compatibility).
.LP
\fBppmbrighten\fR applies the brightening that you specify with 
the \fB-value\fR option after the remapping.
.LP
Before Netpbm 10.14 (March 2003), your input must be from a seekable
file (not a pipe) to use \fB-normalize\fR.  If it isn't, the program fails
with a bogus error message.
.RE
  
.SH 2
SEE ALSO
.LP
pgmnorm, 
ppmdim, 
pamfunc, 
ppmflash, 
pamdepth, 
pnmgamma, 
ppmhist, 
ppm
.SH 2
AUTHOR
.LP
.LP
Copyright (C) 1990 by Brian Moffet.
Copyright (C) 1989 by Jef Poskanzer.
.LP
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation.  This software is provided "as is" without express or
implied warranty.
.br
\l'5i'
.SH 2
Table Of Contents
.LP
.IP \(bu
NAME
.IP \(bu
SYNOPSIS
.IP \(bu
DESCRIPTION
.IP \(bu
EXAMPLES
.IP \(bu
OPTIONS
.IP \(bu
SEE ALSO
.IP \(bu
AUTHOR
.LP