Debian Codegraph @

upstream/debian-unstable/man1/ppmtoxpm.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Ppmtoxpm User Manual" 1 "22 February 2003" "netpbm documentation"
7
8 .SH NAME
9 ppmtoxpm - convert a PPM image to an X11 pixmap
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBppmtoxpm \fP
15 [\fB-name=\fP\fIxpmname\fP]
16 [\fB-hexonly\fP]
17 [\fB-rgb=\fP\fIrgb-textfile\fP]
18 [\fB-alphamask=\fP\fIpgmfile\fP]
19 [\fIppmfile\fP]
20 .PP
21 Minimum unique abbreviation of option is acceptable. You may use double
22 hyphens instead of single hyphen to denote options. You may use white
23 space in place of the equals sign to separate an option name from its value.
24
25 .UN description
26 .SH DESCRIPTION
27 .PP
28 This program is part of
29 .BR "Netpbm" (1)\c
30 \&.
31 .PP
32 \fBppmtoxpm\fP reads a PPM image as input and produces X11 pixmap
33 (version 3) as output. This format can be loaded by the XPM library.
34 .PP
35 In the XPM output, colors may be identified by name, such as "Red", or
36 in hexadecimal, for example "#FF0000". In the hexadecimal format, there
37 may be from 1 through 4 hexadecimal digits per RGB component.
38 .PP
39 By default, \fBppmtoxpbm\fP tries to find a name for each color in
40 the image in the
41 .UR libppm.html#dictionary
42 system color dictionary
43 .UE
44 \&, and if it finds one, uses it. If it doesn't it uses
45 hexadecimal. You can force \fBppmtoxpbm\fP to use hexadecimal only
46 with the \fB-hexonly\fP option. You can specify a different color
47 dictionary with the \fB-rgb\fP option.
48 .PP
49 When \fBppmtoxpm\fP uses the hexadecimal format for identifying a color,
50 it uses the one that uses the least number of hexadecimal digits that it
51 takes to represent the maxval of the input PPM. E.g. if the maxval of the
52 input PPM is 100, \fBppmtoxpm\fP uses 2 digits per component, as in
53 "#FF0000".
54 .PP
55 Some programs do not properly handle one-digit-per-component
56 hexadecimal color specifiers. They see the wrong colors. To produce
57 an XPM that such a program can handle, make sure the maxval of the input PPM
58 is greater than 15, such as by running it through \fBpamdepth 255\fP.
59
60 .SS Color Code Lengths - Image Size
61 .PP
62 In the XPM format, there is a palette ("color map") that
63 assigns each color in the image to a unique sequence of printable
64 characters called a color code, and a raster that identifies the color
65 of each pixel of the image with one of those color codes. The length
66 of the color code affects the size of the image stream.
67 .PP
68 All color codes in an image are the same length, and
69 \fBppmtoxpm\fP tries to make it as short as possible. That length
70 is, of course, determined by the number of colors in the image.
71 \fBppmtoxpm\fP counts the colors in the image, excluding those that will be
72 transparent in the output because of your transparency mask, and chooses a
73 color code length accordingly. There are 92 printable characters that can be
74 used in a color code. Therefore, if you have 92 or fewer colors, your color
75 codes will be one character. If you have more than 92 but not more than 92 *
76 92, your color codes will be two characters. And so on.
77 .PP
78 There's one exception to the above: If you specify a transparency mask
79 (the \fB-alpha\fP option, one unique color code represents
80 "transparent." This is true even if the transparency mask doesn't
81 actually produce any transparent pixels. So subtract one from the number
82 of possible colors if you use \fB-alpha\fP.
83
84
85 .UN options
86 .SH OPTIONS
87 .PP
88 In addition to the options common to all programs based on libnetpbm
89 (most notably \fB-quiet\fP, see
90 .UR index.html#commonoptions
91 Common Options
92 .UE
93 \&), \fBppmtoxpm\fP recognizes the following
94 command line options:
95
96
97 .TP
98 \fB-name=\fP\fIxpmname\fP
99 This option specifies the prefix string which is specified in the
100 resulting XPM output. If you don't use the \fB-name\fP otpion,
101 \fBppmtoxpm\fP defaults to the filename (without extension) of the
102 \fIppmfile\fP parameter. If you do not specify \fB-name\fP or
103 \fIppmfile\fP (i.e. your input is from Standard Input), the prefix
104 string defaults to the string \fBnoname\fP.
105
106 .TP
107 \fB-hexonly\fP
108 This option says never to put color names in the XPM file, but rather
109 to identify names by hexadecimal strings that explicitly identify RGB
110 component intensities. This means the reader of the file need not have
111 access to a suitable color dictionary to interpret it.
112 .sp
113 This option was introduced in Netpbm 10.15 (April 2003). Before that,
114 it was the default, overridden by specifying \fB-rgb\fP.
115
116 .TP
117 \fB-rgb=\fP\fIrgb-textfile\fP
118 This option names the file in which the color dictionary you want
119 to use resides. By default, \fBppmtoxpm\fP uses the
120 .UR libppm.html#dictionary
121 system color dictionary
122 .UE
123 \&, and if it cannot
124 open that file, uses hexadecimal color specifiers.
125 .sp
126 This option in meaningless when you specify \fB-hexonly\fP.
127 .sp
128 Before Netpbm 10.15 (April 2003), \fBppmtoxpm\fP did not default
129 to the system color dictionary. If you didn't specify \fB-rgb\fP,
130 \fBppmtoxpbm\fP would use only hexadecimal color specifiers.
131
132 .TP
133 \fB-alphamask=\fP\fIpgmfile\fP
134 This option names a PGM file to use as a transparency (alpha)
135 mask. The file must contain an image the same dimensions as the input
136 image. \fBppmtoxpm\fP marks as transparent any pixel whose position
137 in the transparency mask image is at most half white.
138 .sp
139 If you don't specify \fB-alphamask\fP, \fBppmtoxpm\fP makes all
140 pixels in the output opaque.
141 .sp
142 \fBppmcolormask\fP is one way to generate a transparency mask file. You
143 might also generate it by extracting transparency information from an
144 XPM file with the \fB-alphaout\fP option to \fBxpmtoppm\fP.
145 .sp
146 There are similar options on other Netpbm converters that convert from
147 formats that include transparency information too.
148
149
150 .UN seealso
151 .SH SEE ALSO
152 .BR "ppmcolormask" (1)\c
153 \&,
154 .BR "xpmtoppm" (1)\c
155 \&,
156 .BR "pamdepth" (1)\c
157 \&,
158 .BR "ppm" (1)\c
159 \&
160 XPM Manual by Arnaud Le Hors \[email protected]\fP
161
162 .UN author
163 .SH AUTHOR
164 .PP
165 Copyright (C) 1990 by Mark W. Snitily.
166 .PP
167 Permission to use, copy, modify, and distribute this software and its
168 documentation for any purpose and without fee is hereby granted, provided
169 that the above copyright notice appear in all copies and that both that
170 copyright notice and this permission notice appear in supporting
171 documentation. This software is provided "as is" without express or
172 implied warranty.
173 .PP
174 This tool was developed for Schlumberger Technologies, ATE Division, and
175 with their permission is being made available to the public with the above
176 copyright notice and permission notice.
177 .PP
178 Upgraded to XPM2 by Paul Breslaw, Mecasoft SA, Zurich, Switzerland (\[email protected]\fP), November 8,
179 1990.
180 .PP
181 Upgraded to XPM version 3 by Arnaud Le Hors(\[email protected]\fP), April
182 9, 1991.
183 .SH DOCUMENT SOURCE
184 This manual page was generated by the Netpbm tool 'makeman' from HTML
185 source. The master documentation is at
186 .IP
187 .B http://netpbm.sourceforge.net/doc/ppmtoxpm.html
188 .PP