\
.\" 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 "Ppmchange User Manual" 0 "December 2016" "netpbm documentation"

.SH NAME

ppmchange - change all pixels of one color to another in a PPM image

.UN synopsis
.SH SYNOPSIS

\fBppmchange\fP

[\fB-closeness=\fP\fIcloseness_percent\fP]
[\fB-remainder=\fP\fIremainder_color\fP]
[\fB-closeok\fP]
[\fIoldcolor newcolor\fP] ...
[\fIppmfile\fP]

.UN examples
.SH EXAMPLES

.nf
\fBppmchange red blue redimage.ppm >blueimage.ppm\fP

\fBppmchange red red -remainder=black myimage.ppm >redblack.ppm\fP

\fBppmchange -closeness=10 white white black black\fP

.fi

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBppmchange\fP reads a PPM image as input and changes all pixels of
color \fIoldcolor\fP to color \fInewcolor\fP.

You may specify up to 256 oldcolor/newcolor pairs on the command line.
\fBppmchange\fP leaves all colors not mentioned unchanged, unless you
specify the \fB-remainder\fP option, in which case they are all
changed to the single specified color.
.PP
You can specify that colors similar, but not identical, to the ones
you specify get replaced by specifying a "closeness" factor.
.PP
Specify the colors as described for the 
.UR libppm.html#colorname
argument of the \fBppm_parsecolor()\fP library routine
.UE
\&.
.PP
If a pixel matches two different \fIoldcolor\fPs, \fBppmchange\fP
replaces it with the \fInewcolor\fP of the leftmost specified one.
.PP
The maxval of the output image is the same as that of the input
image.  If a \fInewcolor\fP you specify cannot be exactly represented
in that maxval, \fBppmchange\fP assumes a color that is as close as
possible to what you specified but can be represented with your
maxval.  Unless you specify the \fB-closeok\fP option,
\fBppmchange\fP issues a warning that it is using an approximation.
.PP
A common way that you can have this maxval problem, where the color
you specify cannot be represented with your maxval, is that your input
is a PBM (black and white) image that you are colorizing.  The maxval
in this case is 1, which severely limits the colors to which you can
change.  To avoid this problem, use \fBpamdepth\fP to make the maxval
of your input something consistent with your colors.  255 is usually a
good choice.
.PP
Before Netpbm 10.22 (April 2004), \fBppmchange\fP always behaved as
if the user specified \fB-closeok\fP and there was no \fB-closeok\fP
option.


.UN options
.SH OPTIONS


.TP
\fB-closeness \fP\fIcloseness_percent\fP
\fIcloseness\fP is a percentage indicating how close to the color you
specified a pixel must be to get replaced.  By default, it is 0, which means
the pixel must be the exact color you specified.
.sp
A pixel gets replaced if the distance in color between it and the
color you specified is less than or equal to \fIcloseness\fP per cent
of the maxval.
.sp
The "distance" in color is defined as the Cartesian sum of the
individual differences in red, green, and blue intensities between the
two pixels, normalized so that the difference between black and white
is 100%.
.sp
This is probably simpler than what you want most the time.  You
probably would like to change colors that have similar chrominance,
regardless of their intensity.  So if there's a red barn that is
variously shadowed, you want the entire barn changed.  But because the
shadowing significantly changes the color according to
\fBppmchange\fP's distance formula, parts of the barn are probably
about as distant in color from other parts of the barn as they are
from green grass next to the barn.
.sp
Maybe \fBppmchange\fP will be enhanced some day to do chrominance
analysis.
.sp
This option was new in Netpbm 9.8 (September 2000).

.TP
\fB-closeok\fP
This option affects how \fBppmchange\fP interprets a color you
specify in the arguments.  When you specify this option, \fBppmchange\fP
may use a color close to, but not the same as what you specify.  See
.UR #description
the description section
.UE
\& for details.
.sp
This option was new in Netpbm 10.22 (April 2004).  Before that,
\fBppmchange\fP always behaved as if you specified this option.
     
.TP
\fB-remainder \fP\fIcolor\fP
\fBppmchange\fP changes all pixels which are not of a color for
which you specify an explicit replacement color on the command line to
color \fIcolor\fP.
.sp
An example application of this is

.nf
\fBppmchange -remainder=black red red\fP
.fi

to lift only the red portions from an image, or
.nf
\fBppmchange -remainder=black red white | ppmtopgm\fP
.fi

to create a mask file for the red portions of the image.



.UN seealso
.SH SEE ALSO
.BR "pgmtoppm" (1)\c
\&,
.BR "ppmcolormask" (1)\c
\&,
.BR "ppm" (5)\c
\&

.UN author
.SH AUTHOR

Wilson H. Bent. Jr. (\fIwhb@usc.edu\fP)
with modifications by Alberto Accomazzi (\fIalberto@cfa.harvard.edu\fP)
.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/ppmchange.html
.PP