Ppmtoxpm User Manual(1) General Commands Manual Ppmtoxpm User Manual(1)
NAME
ppmtoxpm - convert a PPM image to an X11 pixmap
SYNOPSIS
ppmtoxpm [-name=xpmname] [-hexonly] [-rgb=rgb-textfile] [-alphamask=pgm-
file] [ppmfile]
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.
DESCRIPTION
This program is part of Netpbm(1).
ppmtoxpm reads a PPM image as input and produces X11 pixmap (version 3)
as output. This format can be loaded by the XPM library.
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.
By default, ppmtoxpbm tries to find a name for each color in the image
in the ]8;;libppm.html#dictionary\system color dictionary]8;;\ , and if it finds one, uses it. If it
doesn't it uses hexadecimal. You can force ppmtoxpbm to use hexadecimal
only with the -hexonly option. You can specify a different color dic-
tionary with the -rgb option.
When ppmtoxpm 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, ppmtoxpm uses 2 digits per component, as in
"#FF0000".
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 pamdepth 255.
Color Code Lengths - Image Size
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 af-
fects the size of the image stream.
All color codes in an image are the same length, and ppmtoxpm tries to
make it as short as possible. That length is, of course, determined by
the number of colors in the image. ppmtoxpm 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.
There's one exception to the above: If you specify a transparency mask
(the -alpha 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 -alpha.
OPTIONS
In addition to the options common to all programs based on libnetpbm
(most notably -quiet, see ]8;;index.html#commonoptions\ Common Options]8;;\ ), ppmtoxpm recognizes the
following command line options:
-name=xpmname
This option specifies the prefix string which is specified in the
resulting XPM output. If you don't use the -name otpion, ppm-
toxpm defaults to the filename (without extension) of the ppmfile
parameter. If you do not specify -name or ppmfile (i.e. your in-
put is from Standard Input), the prefix string defaults to the
string noname.
-hexonly
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 in-
terpret it.
This option was introduced in Netpbm 10.15 (April 2003). Before
that, it was the default, overridden by specifying -rgb.
-rgb=rgb-textfile
This option names the file in which the color dictionary you want
to use resides. By default, ppmtoxpm uses the ]8;;libppm.html#dictionary\system color dic-
tionary]8;;\ , and if it cannot open that file, uses hexadecimal color
specifiers.
This option in meaningless when you specify -hexonly.
Before Netpbm 10.15 (April 2003), ppmtoxpm did not default to the
system color dictionary. If you didn't specify -rgb, ppmtoxpbm
would use only hexadecimal color specifiers.
-alphamask=pgmfile
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. ppmtoxpm marks as transparent any pixel whose posi-
tion in the transparency mask image is at most half white.
If you don't specify -alphamask, ppmtoxpm makes all pixels in the
output opaque.
ppmcolormask is one way to generate a transparency mask file.
You might also generate it by extracting transparency information
from an XPM file with the -alphaout option to xpmtoppm.
There are similar options on other Netpbm converters that convert
from formats that include transparency information too.
SEE ALSO
ppmcolormask(1), xpmtoppm(1), pamdepth(1), ppm(1) XPM Manual by Arnaud
Le Hors lehors@mirsa.inria.fr
AUTHOR
Copyright (C) 1990 by Mark W. Snitily.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, pro-
vided 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 im-
plied warranty.
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.
Upgraded to XPM2 by Paul Breslaw, Mecasoft SA, Zurich, Switzerland
(paul@mecazh.uu.ch), November 8, 1990.
Upgraded to XPM version 3 by Arnaud Le Hors(lehors@mirsa.inria.fr),
April 9, 1991.
DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source. The master documentation is at
http://netpbm.sourceforge.net/doc/ppmtoxpm.html
netpbm documentation 22 February 2003 Ppmtoxpm User Manual(1)
Generated by dwww version 1.16 on Tue Dec 16 06:31:21 CET 2025.