| 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 |