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.

ABOUT mapview

mapview comprises two programs:

COMPATIBILITY

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.

MEMORY CARDS

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.

REQUIREMENTS

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.

INSTALL

  1. Unpack the distribution tarball.

  2. install mapview.prc on your PalmOS device the usual way (eg. via pilot-link).

USING

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.

Scrolling around

Moving up/down through the layers

Changing maps

Choose mapview -> Open Map… from the menu to open another map.

MAPS

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.

LAYERS

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 MAP

Building a mapview map takes the following steps:

  1. Get the images, eg. scan a paper map or download a map from the net.

  2. Write the map description file which specifies the layers of the map and of which images to compose the layers.

  3. run mapc to build a .prc file (for internal memory) or a .map file (for an expansion card) from the description and the images.

  4. install the .rpc file on your PalmOS device, or copy the .map file to an expansion card.

THE MAP DESCRIPTION FILE

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

RUNNING mapc

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)

BUILDING THE DEMO MAP

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:

  1. download the original map from Wikimedia Commons:

    map of Boston

    and save it as boston.jpg in the demomap directory.

  2. cd demomap

  3. 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.
  4. 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!

BUILDING FROM SOURCE

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.

CONTACT DEVELOPER

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