\
.\" 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 "Ppmtoxpm User Manual" 0 "Feb 22 2003" "netpbm documentation"

.SH NAME
ppmtoxpm - convert a PPM image to an X11 pixmap

.UN synopsis
.SH SYNOPSIS

\fBppmtoxpm \fP
[\fB-name=\fP\fIxpmname\fP]
[\fB-hexonly\fP]
[\fB-rgb=\fP\fIrgb-textfile\fP]
[\fB-alphamask=\fP\fIpgmfile\fP]
[\fIppmfile\fP]
.PP
Minimum unique abbreviation of option is acceptable.  You may use double
hyphens instead of single hyphen to denote options.  You may use white
space in place of the equals sign to separate an option name from its value.

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBppmtoxpm\fP reads a PPM image as input and produces X11 pixmap
(version 3) as output.  This format can be loaded by the XPM library.
.PP
In the XPM output, colors may be identified by name, such as "Red", or
in hexadecimal, for example "#FF0000".  In the hexadecimal format, there
may be from 1 through 4 hexadecimal digits per RGB component.
.PP
By default, \fBppmtoxpbm\fP tries to find a name for each color in
the image in the 
.UR libppm.html#rgb.txt
system color dictionary
.UE
\&, and if it finds one, uses it.  If it doesn't it uses
hexadecimal.  You can force \fBppmtoxpbm\fP to use hexadecimal only
with the \fB-hexonly\fP option.  You can specify a different color
dictionary with the \fB-rgb\fP option.
.PP
When \fBppmtoxpm\fP uses the hexadecimal format for identifying a color,
it uses the one that uses the least number of hexadecimal digits that it
takes to represent the maxval of the input PPM.  E.g. if the maxval of the
input PPM is 100, \fBppmtoxpm\fP uses 2 digits per component, as in
"#FF0000".
.PP
Some programs do not properly handle one-digit-per-component
hexadecimal color specifiers.  They see the wrong colors.  To produce
an XPM that such a program can handle, make sure the maxval of the input PPM
is greater than 15, such as by running it through \fBpamdepth 255\fP.

.SS Color Code Lengths - Image Size
.PP
In the XPM format, there is a palette ("color map") that
assigns each color in the image to a unique sequence of printable
characters called a color code, and a raster that identifies the color
of each pixel of the image with one of those color codes.  The length
of the color code affects the size of the image stream.  
.PP
All color codes in an image are the same length, and
\fBppmtoxpm\fP tries to make it as short as possible.  That length
is, of course, determined by the number of colors in the image.
\fBppmtoxpm\fP counts the colors in the image, excluding those that will be
transparent in the output because of your transparency mask, and chooses a
color code length accordingly.  There are 92 printable characters that can be
used in a color code.  Therefore, if you have 92 or fewer colors, your color
codes will be one character.  If you have more than 92 but not more than 92 *
92, your color codes will be two characters.  And so on.
.PP
There's one exception to the above: If you specify a transparency mask
(the \fB-alpha\fP option, one unique color code represents
"transparent."  This is true even if the transparency mask doesn't 
actually produce any transparent pixels.  So subtract one from the number
of possible colors if you use \fB-alpha\fP.


.UN options
.SH OPTIONS


.TP
\fB-name=\fP\fIxpmname\fP
This option specifies the prefix string which is specified in the
resulting XPM output.  If you don't use the \fB-name\fP otpion,
\fBppmtoxpm\fP defaults to the filename (without extension) of the
\fIppmfile\fP parameter.  If you do not specify \fB-name\fP or
\fIppmfile\fP (i.e. your input is from Standard Input), the prefix
string defaults to the string \fBnoname\fP.

.TP
\fB-hexonly\fP
This option says never to put color names in the XPM file, but rather
to identify names by hexadecimal strings that explicitly identify RGB
component intensities.  This means the reader of the file need not have
access to a suitable color dictionary to interpret it.
.sp
This option was introduced in Netpbm 10.15 (April 2003).  Before that,
it was the default, overridden by specifying \fB-rgb\fP.

.TP
\fB-rgb=\fP\fIrgb-textfile\fP
This option names the file in which the color dictionary you want
to use resides.  By default, \fBppmtoxpm\fP uses the 
.UR libppm.html#rgb.txt
system color dictionary
.UE
\&, and if it cannot
open that file, uses hexadecimal color specifiers.
.sp
This option in meaningless when you specify \fB-hexonly\fP.
.sp
Before Netpbm 10.15 (April 2003), \fBppmtoxpm\fP did not default
to the system color dictionary.  If you didn't specify \fB-rgb\fP,
\fBppmtoxpbm\fP would use only hexadecimal color specifiers.

.TP
\fB-alphamask=\fP\fIpgmfile\fP
 This option names a PGM file to use as a transparency (alpha)
mask.  The file must contain an image the same dimensions as the input
image.  \fBppmtoxpm\fP marks as transparent any pixel whose position
in the transparency mask image is at most half white.
.sp
If you don't specify \fB-alphamask\fP, \fBppmtoxpm\fP makes all
pixels in the output opaque.
.sp
\fBppmcolormask\fP is one way to generate a transparency mask file.  You
might also generate it by extracting transparency information from an
XPM file with the \fB-alphaout\fP option to \fBxpmtoppm\fP.
.sp
There are similar options on other Netpbm converters that convert from
formats that include transparency information too.


.UN seealso
.SH SEE ALSO
.BR "ppmcolormask" (1)\c
\&,
.BR "xpmtoppm" (1)\c
\&,
.BR "pamdepth" (1)\c
\&,
.BR "ppm" (5)\c
\&
XPM Manual by Arnaud Le Hors \fIlehors@mirsa.inria.fr\fP

.UN author
.SH AUTHOR
.PP
Copyright (C) 1990 by Mark W. Snitily.
.PP
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.
.PP
This tool was developed for Schlumberger Technologies, ATE Division, and
with their permission is being made available to the public with the above
copyright notice and permission notice.
.PP
Upgraded to XPM2 by Paul Breslaw, Mecasoft SA, Zurich, Switzerland (\fIpaul@mecazh.uu.ch\fP), November 8,
1990.
.PP
Upgraded to XPM version 3 by Arnaud Le Hors(\fIlehors@mirsa.inria.fr\fP), April
9, 1991.
.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/ppmtoxpm.html
.PP