m500 T3 (320x320 display mode) Treo 650 Tungsten E emulated Palm III, IIIx, and V
Copyright © 2005 Edwin Steiner <edwin.steiner@gmx.net>
File dialog imported from SiEd: SiEd - A text editor for PalmOS 3.5+ Copyright © 2003 Benjamin Roe
This program is free software, for license details see the file COPYING.
mapview comprises two programs:
mapc: a Perl program for building the maps on your desktop computer,
mapview.prc: the PalmOS application to view the maps.
mapview should work on any Palm OS device that has enough memory to store the maps. It has, however, only been tested on the devices listed blow.
mapview is known to work on the following devices:
m500 T3 (320x320 display mode) Treo 650 Tungsten E emulated Palm III, IIIx, and V
The only PalmOS device I own is a Treo 650, so I cannot test mapview on any other device. If you try mapview on another device, I would be happy to hear from you.
Since version 0.2.0 mapview supports putting maps on expansion cards. Note that you cannot just put a .prc map file on the expansion card. You need to build a .map file by giving the —vfs option to mapc. See the section on mapc below.
Memory card support works only in PalmOS 3.5 or higher.
You will need the following software packages in order to build maps:
Package | Debian name | Gentoo emerge |
---|---|---|
perl | perl | perl |
the GD Perl module | libgd-gd2-perl | GD |
ImageMagick or netpbm | imagemagick / netpbm | imagemagick |
pilrc | pilrc | pilrc |
If you want to build the demo map, you will need ImageMagick and a make tool.
If you know how these packages are called on other distributions, please contact me.
Unpack the distribution tarball.
install mapview.prc on your PalmOS device the usual way (eg. via pilot-link).
You will first need to build a map in order to use mapview. See the following sections to learn how to do that.
When you launch mapview, it will present a list of all maps found on the device. If your device supports expansion cards, these will be displayed and you can browse their contents. Chose a map and click the Open button to open it.
The map will open displaying the top-most layer.
Use the directional pad to scroll left/right/up/down.
Tap an off-center point on the map to center it on the display.
Press/Write c or C to move to the map center.
Tap the center of the map to cycle through the layers, downward.
Press the center button or space to go down a layer.
Press backspace to go up a layer.
Choose mapview -> Open Map… from the menu to open another map.
A map for the mapview program consists of one or more layers. Imagine the layers as opaque sheets of paper stacked on top of each other.
A map also has a defined size which is given as the width and height of the map in map coordinates. You do not have to specify the map size yourself, as mapc calculates it, so that all layers fit inside the map boundaries.
A layer is basically an image, eg. of the "City of Ankh-Morpork at 1:20000". At any time mapview displays one of the layers of the map. This is called the current layer. You can scroll around in the current layer, or switch to another layer of the map, making it the new current layer.
An important attribute of a layer is its scale. The scale is the (integer) factor used to convert layer coordinates to map coordinates.
For example, you may have images showing Ankh-Morpork at 1:100000, 1:20000 and 1:5000. You could then create a map with the following layers ("zooming in downwards"):
layer | scale | description |
---|---|---|
1 | 20 | Ankh-Morpork at 1:100000 |
2 | 4 | Ankh-Morpork at 1:20000 |
3 | 1 | Ankh-Morpork at 1:5000 |
Note: The layers do not have to be ordered by scale, nor does there have to be a layer with scale=1.
In order to deal with PalmOS memory restrictions layers are divided into tiles, ie. small squares of equal size. The mapc program does this automatically. Empty tiles, ie. tiles with no image data, do not consume memory.
Building a mapview map takes the following steps:
Get the images, eg. scan a paper map or download a map from the net.
Write the map description file which specifies the layers of the map and of which images to compose the layers.
run mapc to build a .prc file (for internal memory) or a .map file (for an expansion card) from the description and the images.
install the .rpc file on your PalmOS device, or copy the .map file to an expansion card.
The map description file is a simple text file containing one or more layer specifications.
A layer specification starts with a line of the following form:
layer scale=<scale> tilesize=<tilesize>
The word layer must start in the first column. The scale and tilesize specifications may be omitted and default to 1 and 255, respectively. No whitespace is allowed around the equal signs.
This line must be followed by one or more indented lines of the form:
<imagefilename>, <x>, <y>
where <imagefilename> is the name of an image to be placed on this layer, <x>, <y> specify where to put the top-left corner of the image relative to the layer in layer coordinates, ie. pixels when the layer is displayed.
You can put an arbitrary number of images on a layer. If there is any overlap, the images mentioned later in the list will overwrite the ones mentioned before.
For an example of a map description file see the file demomap/demo in the mapview distribution:
layer scale=5 boston_scale5.jpg, 0, 0 layer scale=1 boston_scale1.jpg, 0, 0
mapc is invoked as follows:
mapc [--vfs] <map-description-file> <output-filename> <mapname> [--density=<density>] [--bpp=<bpp>]
where —vfs specifies that a .map file should be built that can be stored on an expansion card. Without the —vfs option a .prc file for internal memory is created.
<map-description-file> is a map description file as described above,
<output-filename> is the name of the `.prc` or `.map` file to be written,
<mapname> is the name under which the map is displayed on the handheld, eg. 'Ankh-Morpork',
<density> specifies the density of the bitmaps to create. Use
--density=72 for devices with a 160x160 screen --density=144 for devices with a 320x320 screen (default)
<bpp> specifies the number of bits per pixel. Use
--bpp=1 to create a black&white map --bpp=2 to create a greyscale map with 4 shades of grey --bpp=4 to create a greyscale map with 16 shades of grey --bpp=8 to create a color map (default)
The demo map is a beautiful old map of Boston. Unfortunately it is quite large, so I could not include it in the distribution. To build it, proceed as follows:
download the original map from Wikimedia Commons:
and save it as boston.jpg in the demomap directory.
cd demomap
Depending on your device:
make for a 320x320 color screen, DENSITY=72 make for a 160x160 color screen, DENSITY=72 BPP=4 make for a 160x160 greyscale screen, DENSITY=72 BPP=1 make for a 160x160 black&white screen.
transfer the file mv_boston.prc to your PalmOS device, or alternatively copy mv_boston.map to an expansion card.
You will then have a wonderful, zoomable map of old Boston on your Palm.
Have fun!
If you want to build mapview.prc from source you will need the Palm OS development tools for Linux and a Palm OS SDK. If you have these installed, just use make to build everything.
You can contact me via <edwin.steiner@gmx.net>. I'm always happy to get feedback. Please include the word mapview in the subject line.
vim: tw=72 et sts=4 sw=4