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