1Pnmtopalm User Manual(0)                              Pnmtopalm User Manual(0)
2
3
4

NAME

6       pnmtopalm - convert a PNM image to a Palm Bitmap
7
8

SYNOPSIS

10       pnmtopalm
11
12       [-verbose]
13
14       [-depth=N]
15
16       [-maxdepth=N]
17
18       [-colormap]
19
20       [-transparent=color]
21
22       [-density=N]
23
24       [-offset]
25
26       [-withdummy] [-scanline-compression | -rle-compression | -packbits-com‐
27       pression]
28
29       [pnmfile]
30
31       Minimum unique abbreviation of option is acceptable.  You may use  dou‐
32       ble  hyphens  instead  of single hyphen to denote options.  You may use
33       white space in place of the equals sign to separate an option name from
34       its value.
35
36

DESCRIPTION

38       This program is part of Netpbm(1).
39
40       pnmtopalm  reads  a  PNM image as input, from Standard Input or pnmfile
41       and produces a Palm Bitmap as output.
42
43       Palm Bitmap files are either grayscale files 1, 2, or 4 bits  wide,  or
44       color  files  8  bits wide, so pnmtopalm automatically scales colors to
45       have an appropriate maxval, unless you specify a depth  or  max  depth.
46       Input  files  must have an appropriate number and set of colors for the
47       selected output constraints.
48
49       This often means that you should run the PNM image through pnmquant  or
50       pnmremap  before  you  pass it to pnmtopalm.  Netpbm comes with several
51       colormap files you can use with pnmremap for this  purpose.   They  are
52       palmgray2.map  (4  shades  of gray for a depth of 2), palmgray4.map (16
53       shades of gray for a depth of 4), and  palmcolor8.map  (232  colors  in
54       default  Palm  colormap).  In a standard Netpbm installation, these are
55       in the Netpbm data directory, and you can find the Netpbm  data  direc‐
56       tory with a netpbm-config --datadir shell command.
57
58       Example:
59
60         pnmremap myimage.ppm \
61                  -mapfile=$(netpbm-config --datadir)/palmgray2.map \
62         | pnmtopalm -depth=2 >myimage.palm
63
64
65
66
67   Palm Bitmap Version
68       pnmtopalm  generates a Version 0, 1, 2, or 3 Palm Bitmap.  It generates
69       the oldest (lowest) version it can for the given image and the  options
70       you specify.
71
72
73
74       ·      If  you  specify  a density (-density option) higher than 'low,'
75              the version is at least 3.
76
77
78       ·      If you specify transparency (-transparent option)  or  any  com‐
79              pression, the version is at least 2.
80
81
82       ·      If you specify a custom colormap (-colormap option), the verison
83              is at least 1.
84
85
86       ·      If the image has more than one bit per pixel, the version is  at
87              least 1.  The image has more than one bit per pixel if you spec‐
88              ify it with -depth or if you let it default and  the  image  has
89              more than two colors (or shades of gray).
90
91
92
93       All  releases  of Palm OS can read a Version 0 bitmap.  Palm OS 3.0 and
94       later can read a Version 1 bitmap.  Palm OS 3.5 and later  can  read  a
95       Version  2 bitmap.  To read a Version 3 bitmap, you need Palm OS Garnet
96       or a handheld running the High Density Display Feature Set.
97
98

OPTIONS

100       -verbose
101              Display the format of the output file.
102
103
104       -depth=N
105              Produce a file of depth N, where N must be either 1, 2, 4, 8, or
106              16.   Because  the default Palm 8-bit colormap is not grayscale,
107              if the input is a grayscale or monochrome image, the output will
108              never  be  more  than  4  bits deep, regardless of the specified
109              depth.  Note that 8-bit color works  only  in  PalmOS  3.5  (and
110              higher),  and  16-bit direct color works only in PalmOS 4.0 (and
111              higher).  However, the 16-bit direct color format is  also  com‐
112              patible  with  the various PalmOS 3.x versions used in the Hand‐
113              spring Visor, so these images may also work in that device.
114
115
116       -maxdepth=N
117              Produce a file of minimal depth, but in any  case  less  than  N
118              bits  wide.   If  you  specify 16-bit, the output will always be
119              16-bit direct color.
120
121
122       -offset
123              Set the nextDepthOffset field in the palm file header  to  indi‐
124              cate  the  end  of  the  file  (and pad the end of the file to 4
125              bytes, since nextDepthOffset can point only  to  4  byte  bound‐
126              aries).
127
128              A  palm  image  file can contain multiple renditions of the same
129              image, with different color depths, so a viewer can  choose  one
130              appropriate  for  the  display.  The nextDepthOffset field tells
131              where in the stream the next rendition begins.
132
133              pnmtopalm creates a file that contains only one image,  but  you
134              can  separately concatenate multiple one-image files to create a
135              multi-image file.  If you do that, you'll need to use -offset so
136              that the resulting concatenation is a correct stream.
137
138              By default (if you don't specify -offset), pnmtopalm generates a
139              nextDepthOffset field that says there is no following image (and
140              does not add any padding after the image).
141
142              Version  3  Palm  Bitmaps actually have a nextBitmapOffset field
143              instead of the nextDepthOffset.  The foregoing applies to which‐
144              ever is relevant.
145
146              The  -offset  option  was  new  in  Netpbm 10.26 (January 2005).
147              Before that, pnmtopalm always set the nextDepthOffset  field  to
148              'none.'
149
150              Before  Netpbm 10.27 (March 2005), you cannot use -offset if you
151              create a compressed raster (because pnmtopalm isn't smart enough
152              to  be  able to know the size of the image at the time it writes
153              the header).  You also cannot use it with 16 bit color depth  or
154              with the -colormap option, for much the same reason.
155
156
157       -withdummy
158              This  option  tells  pnmtopalm to put in the stream, after after
159              the image, a dummy image header  to  introduce  subsequent  high
160              density images.
161
162              This  dummy image header is a special sequence specified in Palm
163              Bitmap specifications.  It looks to an older Palm Bitmap  inter‐
164              preter  like an invalid image header, so such an intepreter will
165              stop reading the stream there.  But a  new  Palm  Bitmap  inter‐
166              preter  recognizes it for what it is (just something to choke an
167              old interpreter) and skips over it.  Presumably, you will add to
168              the stream after this high density images which would confuse an
169              older interpreter.
170
171              If you specify -withdummy, you must also specify -offset,  since
172              it doesn't make any sense otherwise.
173
174              -withdummy was new in Netpbm 10.27 (March 2005).
175
176
177       -colormap
178              Build a custom colormap and include it in the output file.  This
179              is not recommended by Palm, for efficiency reasons.   Otherwise,
180              pnmtopalm uses the default Palm colormap for color output.
181
182
183       -transparent=color
184              Marks  one particular color as fully transparent.  The format to
185              specify  the  color  is  either  (when   for   example   orange)
186              '1.0,0.5,0.0', where the values are floats between zero and one,
187              or with the syntax '#RGB', '#RRGGBB' or '#RRRRGGGGBBBB' where R,
188              G  and  B  are  hexadecimal numbers.  Transparency works only on
189              Palm OS 3.5 and higher.
190
191
192       -scanline-compression
193              Specifies that the output Palm bitmap will use the Palm scanline
194              compression  scheme.  Scanline compression works only in Palm OS
195              2.0 and higher.
196
197
198       -rle-compression
199              Specifies that the output Palm bitmap will use the Palm RLE com‐
200              pression  scheme.   RLE  compression works only with Palm OS 3.5
201              and higher.
202
203
204       -packbits-compression
205              Specifies that the output Palm bitmap will use the Palm packbits
206              compression  scheme.   Packbits compression works only with Palm
207              OS 4.0 and higher.
208
209              This option was new in Netpbm 10.27 (March 2005).
210
211
212       -density=N
213              This specifies the Palm Bitmap density.  The density is a number
214              that  is  proportional  to  the resolution the image should have
215              when displayed.  The proportionality factor is up to whatever is
216              doing the displaying, but it's helpful to think of these numbers
217              as being pixels per inch.  The allowable values are:
218
219
220
221       ·      72
222
223       ·      108
224
225       ·      144
226
227       ·      216
228
229       ·      288
230
231
232              This option was new  in  Netpbm  10.27  (March  2005).   Earlier
233              Netpbm  could  not generate Version 3 Palm Bitmaps, so there was
234              no such thing as density.
235
236
237
238
239

SEE ALSO

241       palmtopnm(1), pdbimgtopam(1), pnmquant(1), pnmremap(1), pnm(1)
242
243
244

NOTES

246       Palm Bitmaps may contains multiple renditions of the  same  bitmap,  in
247       different  depths.   To  construct  an N-multiple-rendition Palm Bitmap
248       with pnmtopalm, first construct renditions  1  through  N-1  using  the
249       -offset  option,  then  construct  the  Nth  image  without the -offset
250       option.  Then concatenate the individual renditions together in a  sin‐
251       gle file using cat.
252
253       If  you  will include both high density and low density renditions, put
254       the high density images last and when you create the last  of  the  low
255       density images, use the -withdummy option.
256
257       If you specify the Palm packbits compression scheme for a 16-bit direct
258       color bitmap, this program generates an invalid bitmap.
259
260
261

AUTHORS

263       This program was originally written as ppmtoTbmp.c, by Ian Goldberg and
264       George  Caswell.   It  was completely re-written by Bill Janssen to add
265       color, compression, and transparency function.  Copyright 1995-2001  by
266       Ian Goldberg, George Caswell, and Bill Janssen.
267
268
269
270netpbm documentation            05 October 2003       Pnmtopalm User Manual(0)
Impressum