Debian Codegraph @

upstream/debian-unstable/man1/pnmtopalm.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 "Pnmtopalm User Manual" 1 "25 August 2017" "netpbm documentation"
7
8 .SH NAME
9 pnmtopalm - convert a PNM image to a Palm Bitmap
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpnmtopalm\fP
15
16 [\fB-verbose\fP]
17
18 [\fB-depth=\fP\fIN\fP]
19
20 [\fB-maxdepth=\fP\fIN\fP]
21
22 [\fB-colormap\fP]
23
24 [\fB-transparent=\fP\fIcolorspec\fP]
25
26 [\fB-density=\fP\fIN\fP]
27
28 [\fB-offset\fP]
29
30 [\fB-withdummy\fP]
31 [\fB-scanline_compression\fP | \fB-rle_compression\fP |
32 \fB-packbits_compression\fP]
33
34 [\fIpnmfile\fP]
35 .PP
36 Minimum unique abbreviation of option is acceptable. You may use
37 double hyphens instead of single hyphen to denote options. You may use
38 white space in place of the equals sign to separate an option name
39 from its value.
40
41 .UN description
42 .SH DESCRIPTION
43 .PP
44 This program is part of
45 .BR "Netpbm" (1)\c
46 \&.
47 .PP
48 \fBpnmtopalm\fP reads a PNM image as input, from Standard Input or
49 \fIpnmfile\fP and produces a Palm Bitmap as output.
50 .PP
51 Palm Bitmap files are either grayscale files with 1, 2, or 4 bits per
52 pixel, or mapped color files with 8 bit per pixel, or a direct color file with
53 16 bits per pixel, and \fBpnmtopalm\fP chooses this color depth based on the
54 maxval and number of colors in the input, unless you specify a depth (bits per
55 pixel) with \fB-depth\fP. You can also specify a maximum depth
56 with \fB-maxdepth\fP to partially constrain \fBpnmtopalm\fP's choice. Input
57 files must have an appropriate number and set of colors for the selected
58 output constraints.
59 .PP
60 This often means that you should run the PNM image through
61 \fBpnmquant\fP or \fBpnmremap\fP before you pass it to
62 \fBpnmtopalm\fP. Netpbm comes with several colormap files you can
63 use with \fBpnmremap\fP for this purpose. They are
64 \fIpalmgray2.map\fP (4 shades of gray for a depth of 2),
65 \fIpalmgray4.map\fP (16 shades of gray for a depth of 4), and
66 \fIpalmcolor8.map\fP (232 colors in default Palm colormap). In a
67 standard Netpbm installation, these are in the Netpbm data directory,
68 and you can find the Netpbm data directory with a \fBnetpbm-config
69 --datadir\fP shell command.
70 .PP
71 Example:
72
73 .nf
74 pnmremap myimage.ppm \e
75 -mapfile=$(netpbm-config --datadir)/palmgray2.map \e
76 | pnmtopalm -depth=2 >myimage.palm
77
78
79 .fi
80 .PP
81 Compressed Palm Bitmap files, at least the ones \fBpnmtopalm\fP knows how
82 to create, cannot have more than 8 bits per pixel. \fBpnmtopalm\fP defaults
83 to 8 bits per pixel if you specify a compressed output. You can specify the
84 number of bits per pixel explicitly with \fB-depth\fP. \fB-maxdepth\fP
85 has the same effect as \fB-depth\fP. If you specify more than 8 bits per
86 pixel with either of these, \fBpnmtopalm\fP fails.
87
88 .UN version
89 .SS Palm Bitmap Version
90 .PP
91 \fBpnmtopalm\fP generates a Version 0, 1, 2, or 3 Palm Bitmap.
92 It generates the oldest (lowest) version it can for the given image and
93 the options you specify.
94
95
96 .IP \(bu
97 If you specify a density (\fB-density\fP option) higher than
98 "low," the version is at least 3.
99
100 .IP \(bu
101 If you specify transparency (\fB-transparent\fP option) or
102 any compression, the version is at least 2.
103
104 .IP \(bu
105 If you specify a custom colormap (\fB-colormap\fP option), the
106 version is at least 1.
107
108 .IP \(bu
109 If the image has more than one bit per pixel, the version is at least
110 1. The image has more than one bit per pixel if you specify it with
111 \fB-depth\fP or if you let it default and the image has more than
112 two colors (or shades of gray).
113
114
115 .PP
116 All releases of Palm OS can read a Version 0 bitmap. Palm OS 3.0 and
117 later can read a Version 1 bitmap. Palm OS 3.5 and later can read a
118 Version 2 bitmap. To read a Version 3 bitmap, you need Palm OS Garnet
119 or a handheld running the High Density Display Feature Set.
120
121 .UN options
122 .SH OPTIONS
123 .PP
124 In addition to the options common to all programs based on libnetpbm
125 (most notably \fB-quiet\fP, see
126 .UR index.html#commonoptions
127 Common Options
128 .UE
129 \&), \fBpnmtopalm\fP recognizes the following
130 command line options:
131
132
133 .TP
134 \fB-verbose\fP
135 Display the format of the output file.
136
137 .TP
138 \fB-depth=\fP\fIN\fP
139 Produce a file of depth \fIN\fP, where \fIN\fP must be either 1, 2,
140 4, 8, or 16. Because the default Palm 8-bit colormap is not
141 grayscale, if the input is a grayscale or monochrome image, the
142 output will never be more than 4 bits deep, regardless of the
143 specified depth. Note that 8-bit color works only in PalmOS 3.5 (and
144 higher), and 16-bit direct color works only in PalmOS 4.0 (and
145 higher). However, the 16-bit direct color format is also compatible
146 with the various PalmOS 3.x versions used in the Handspring Visor, so
147 these images may also work in that device.
148
149 .TP
150 \fB-maxdepth=\fP\fIN\fP
151 Produce a file of minimal depth, but in any case less than \fIN\fP
152 bits wide. If you specify 16-bit, the output will always be 16-bit
153 direct color.
154
155 .TP
156 \fB-offset\fP
157 Set the \fBnextDepthOffset\fP field in the palm file header to indicate
158 the end of the file (and pad the end of the file to 4 bytes, since
159 \fBnextDepthOffset\fP can point only to 4 byte boundaries).
160 .sp
161 A palm image file can contain multiple renditions of the same image,
162 with different color depths, so a viewer can choose one appropriate for
163 the display. The \fBnextDepthOffset\fP field tells where in the stream
164 the next rendition begins.
165 .sp
166 \fBpnmtopalm\fP creates a file that contains only one image, but
167 you can separately concatenate multiple one-image files to create a
168 multi-image file. If you do that, you'll need to use \fB-offset\fP
169 so that the resulting concatenation is a correct stream.
170 .sp
171 By default (if you don't specify \fB-offset\fP), \fBpnmtopalm\fP
172 generates a \fBnextDepthOffset\fP field that says there is no following
173 image (and does not add any padding after the image).
174 .sp
175 Version 3 Palm Bitmaps actually have a \fBnextBitmapOffset\fP
176 field instead of the \fBnextDepthOffset\fP. The foregoing applies to
177 whichever is relevant.
178 .sp
179 The \fB-offset\fP option was new in Netpbm 10.26 (January 2005).
180 Before that, \fBpnmtopalm\fP always set the \fBnextDepthOffset\fP
181 field to "none."
182 .sp
183 Before Netpbm 10.27 (March 2005), you cannot use \fB-offset\fP if
184 you create a compressed raster (because \fBpnmtopalm\fP isn't smart
185 enough to be able to know the size of the image at the time it writes
186 the header). You also cannot use it with 16 bit color depth or with
187 the \fB-colormap\fP option, for much the same reason.
188
189 .TP
190 \fB-withdummy\fP
191 This option tells \fBpnmtopalm\fP to put in the stream, after
192 the image, a dummy image header to introduce subsequent high density
193 images.
194 .sp
195 This dummy image header is a special sequence specified in Palm Bitmap
196 specifications. It looks to an older Palm Bitmap interpreter like an invalid
197 image header, so such an interpreter will stop reading the stream
198 there. But a new Palm Bitmap interpreter recognizes it for what it is (just
199 something to choke an old interpreter) and skips over it. Presumably,
200 you will add to the stream after this high density images which would
201 confuse an older interpreter.
202 .sp
203 If you specify \fB-withdummy\fP, you must also specify \fB-offset\fP,
204 since it doesn't make any sense otherwise.
205 .sp
206 \fB-withdummy\fP was new in Netpbm 10.27 (March 2005).
207
208 .TP
209 \fB-colormap\fP
210 Build a custom colormap and include it in the output file. This is
211 not recommended by Palm, for efficiency reasons. Otherwise, \fBpnmtopalm\fP
212 uses the default Palm colormap for color output.
213
214 .TP
215 \fB-transparent=\fP\fIcolorspec\fP
216 Marks \fIone\fP particular color as fully transparent.
217 .sp
218 \fIcolorspec\fP is as described for the
219 .UR libnetpbm_image.html#colorname
220 argument of the \fBpnm_parsecolor()\fP library routine
221 .UE
222 \&.
223 .sp
224 Transparency works only on Palm OS 3.5 and higher.
225
226 .TP
227 \fB-scanline_compression\fP
228 Specifies that the output Palm bitmap will use the Palm scanline
229 compression scheme. Scanline compression works only in Palm OS 2.0
230 and higher.
231
232 .TP
233 \fB-rle_compression\fP
234 Specifies that the output Palm bitmap will use the Palm RLE
235 compression scheme. RLE compression works only with Palm OS 3.5 and
236 higher.
237
238 .TP
239 \fB-packbits_compression\fP
240 Specifies that the output Palm bitmap will use the Palm packbits
241 compression scheme. Packbits compression works only with Palm OS 4.0 and
242 higher.
243 .sp
244 This option was new in Netpbm 10.27 (March 2005).
245
246 .TP
247 \fB-density\fP=\fIN\fP
248 This specifies the Palm Bitmap density. The density is a number that
249 is proportional to the resolution the image should have when displayed.
250 The proportionality factor is up to whatever is doing the displaying,
251 but it's helpful to think of these numbers as being pixels per inch.
252 The allowable values are:
253
254
255 .IP \(bu
256 72
257 .IP \(bu
258 108
259 .IP \(bu
260 144
261 .IP \(bu
262 216
263 .IP \(bu
264 288
265
266 .sp
267 This option was new in Netpbm 10.27 (March 2005). Earlier Netpbm
268 could not generate Version 3 Palm Bitmaps, so there was no such thing
269 as density.
270
271
272
273 .UN seealso
274 .SH SEE ALSO
275 .BR "palmtopnm" (1)\c
276 \&,
277 .BR "pdbimgtopam" (1)\c
278 \&,
279 .BR "pnmquant" (1)\c
280 \&,
281 .BR "pnmremap" (1)\c
282 \&,
283 .BR "pnm" (1)\c
284 \&
285
286 .UN notes
287 .SH NOTES
288 .PP
289 Palm Bitmaps may contains multiple renditions of the same bitmap,
290 in different depths. To construct an N-multiple-rendition Palm Bitmap
291 with \fBpnmtopalm\fP, first construct renditions 1 through N-1 using
292 the \fB-offset\fP option, then construct the Nth image without the
293 \fB-offset\fP option. Then concatenate the individual renditions
294 together in a single file using \fBcat\fP.
295 .PP
296 If you will include both high density and low density renditions,
297 put the high density images last and when you create the last of the
298 low density images, use the \fB-withdummy\fP option.
299 .PP
300 If you specify the Palm packbits compression scheme for a 16-bit direct
301 color bitmap, this program generates an invalid bitmap.
302
303
304 .UN authors
305 .SH AUTHORS
306
307 This program was originally written as ppmtoTbmp.c, by Ian Goldberg
308 and George Caswell. It was completely re-written by Bill Janssen to
309 add color, compression, and transparency function.
310 Copyright 1995-2001 by Ian Goldberg, George Caswell, and Bill Janssen.
311 .SH DOCUMENT SOURCE
312 This manual page was generated by the Netpbm tool 'makeman' from HTML
313 source. The master documentation is at
314 .IP
315 .B http://netpbm.sourceforge.net/doc/pnmtopalm.html
316 .PP