PocketGPS-Map
(c) 2007 Andrej Krutak
Distributed
under GPLv2 or newer
Program is using libjpeg, libz and libpng code.
This
is my "thank you!" to their authors...
USAGE
Basics
The program can be run on win32 (WindowsXP tested)
and PocketPC platform (tested on 2003 emulator and a WM5.0 HTC Wizard device).
Of course, you have to use different binaries :-) The win32 version has exactly
the same capabilities and almost the same look as the pocketpc one (except that
you can't use too big images on PPC - unless you use tiled ones.. see below).
The main reason for it's existence is to test maps - it's simpler to prepare and
test a map on desktop than on a PDA/smartphone.
After you start the
program, the first thing you may want to do is select source of GPS "signal" -
using the Config-Set GPS Device menu item. In current version,
it can be either serial (COM) port or a file with stored "signal stream" (raw
NMEA protocol data).
Now you can switch to the GPS Info view
(Config-Show GPS info) to see informations (like your position,
satellite position info) from the GPS signal source.
Maybe you want to
use the program for navigating in maps. You can choose the atlas containing maps
by Config-Load atlas. There you have to input path to the the
atlas (use \ character to separate directories, and put a \ also on the end of
path). After that, program automagically searches available maps and starts
using them. Oh yes - you can switch to Map view by using Config-Show
Map)
Advanced usage
You may want to navigate to certain points in
the map. For that you can use Map-Waypoints menu item. There
you can add new waypoints and select the one to which you will navigate in map.
If you press the button "Clear selection", no waypoint will be selected. After
you press OK, the program will start the navigation to selected waypoints (if
any).
Note: When inputting the coordinates, the North and East
values are positive numbers (+14.2231, 55.904), West and South are negative
(-13.214). You can use the provided coordinate-helper (by pressing button ° in
the right of longitude/latitude field) - it will help you with conversion of
coordinates to required format.
By using zoom in/out,
you can select more or less precise map, if there is any in atlas, for your
current location. If follow position is checked (the checking
may not work on pocketpc 2003, but the function still works ;-), the your
position will be always in the center of view. Auto switch
ensures automatical selection of map (if there is any apropriate), if you go
outside the current one. Always best zoom item makes the
program always choose the map with best zoom. If it isn't checked/used, map
won't be changed until you go outside of it. You can choose to view any map from
the atlas by Choose map item (note that all 3 previous
functions are automatically disabled in this case... you can reenable them, but
other than selected map may be open afterwards).
GPS Info screen
This screen contains info about the data
from GPS device/data source.
First line contains count of NMEA messages
received from the source and the current time of the source.
The second
row contains list of used satellites and strengths of their signals.
Next
line contains mode of GPS (whether there is a fix, if it is 2D or 3D and what is
the accuracy).
Then there is number of satellites in view used for position
calculation.
Next lines specify current position (Latitude, Longitude,
Altitude)...
The compass on the right side of display shows where the
north is (assuming that you are moving with the pda in front of you) and where
are the satellites on the sky (blue ones are the ones used in
calculations).
Map screen
The main part of screen is the map :-) If a big
green circle is visible, that is your position. The cyan arrow shows direction
of your movement and the white (empty inside) one shows direction to the
waypoint (if any selected).
Orange circle, if shown, is the waypoint
position.
On the bottom of screen you can see:
In 1st column the
current position.
In 2nd column altitude and speed.
In 3rd column distance
to the waypoint and direction where in which you should move if you want to get
to the waypoint (assumes you are moving with the PDA in front of you).
CREATING OWN MAPS/ATLASES
Atlas
Atlas is just a directory containing other directories
:-) Each directory contained has to contain one map.
The structure of atlas
may look like this:
atlas\
map1\
map1.map
map1.png
map123\
map123.map
set\
map123_0_0.png
map123_100_0.png
Additionaly, you can use TAR files (tarballs) to 'pack' maps
into one file (might be useful if you have many maps which contain many files -
the space on storage card is better used this way). Each tar file must have the
same structure as a map directory, e.g.:
atlas\
map1.tar\
map1.map
set\
map1_0_0.png
...
Map
Each map is defined by a file with a name in form
MAPNAME.map, where MAPNAME is the name of map directory. Currently PocketGPS-Map
support (hopefully) OziExplorer (or TrekBuddy) map format and it's own simple
format (it's preferred for simple creating :-)).
OziExplorer
format
...TODO (you may find the description
elsewhere)
Own simple format
The .map file begins
with
Simple Calibration v1
string.
Then any number of lines may follow.
Each one has to begin with a tag (1 word) meaning, what does the line specify.
Here are currenly recognized tags:
SIZE x y - specifies total size
of image
DATUM datum_name - specifies datum of coordinates of
calibration points (see below)
CAL lon lat x y - specifies a
calibration point. Meaning: specifies that point [x,y] on the map is [lon,lat]
in real world.
IMG path - specifies, which image should be loaded
for this map. If nothing specified, images from set or
pictures subdirectory will be used
PART x y - specifies
size of a image tile (see next section)
Map calibration
If you want to use the map with GPS, you
have to specify calibration points. A calibration point specifies, which point
in map coresponds to which point in the real world (latitude/longitude). The
more points are specified, the more accurate the position in the map can be
calculated. However, at least 2 points have to be specified (the nearer to top
left and bootom right corners, the better).
There are many different so
called datums that can be used to specify world-coordinates (mostly
these are country/region-specific). GPS devices mostly use WGS-84 datum, and so
do e.g. Google maps. Anyway, you might get a map that is calibrated using other
datum. In this case, you can find the datums supported by pocketgps-map in
datums.csv file in it's directory. Choose the one nearest to original
map datum (most probably you will find exactly the one you are searching for...
otherwise you can add the datum to the datum.csv file by yourself - an you can
also send the new datum to the author) and specify it by DATUM tag in
calibration file. If you don't know how to work with datums, you might some
informations on google.
Image files
When you create a map, you obviously have to
give some bitmap to the program :-) It currently supports BMP, PNG and JPG
formats. If you use just one image, specify it in configuration file.
If
you want to used tiled image (really good for PDAs and other devices with
limited memory), you have to slice the images to parts and put them in
set or pictures subdirectory (in any of the 3 mentioned
formats).
If you are using OziExplorer map definition format, you have to
name images in format MAPNAME_x_y.EXT, where x and y is the position of top left
corner of tile in the whole image.
You can use the same convention in
simple format. However you can also index the images (like MAPNAME_0_0.EXT,
MAPNAME_0_1.EXT etc.), but in this case you have to manually specify tile size
by using the PART tagged line.
Explanation of tiled images
The tiled image names can be in
two formats...
* First
- more intuitive - is that you split the big image
into small pieces. Let's say the image has dimensions 3005x2005 and you want to
split it into pieces of size 100x50. In this case, images will be named
like
prefix_0_0.jpg
prefix_0_50.jpg
prefix_0_100.jpg
...
prefix_100_0.jpg
...
prefix_3000_2000.jpg
(The
pieces on the right and bottom don't have to be of full size - they can be
smaller (in a logical way :-))).
All these files have to be placed inside
of 'set' subdirectory of map. The name of map configuration file is then
'prefix.map' and the map directory has to be named 'prefix'. The corresponding
map could look like the following then:
<<<<<
Simple
Calibration v1
SIZE 3005 2005
CAL 1 2 0 0
CAL 3 4 3005
2005
<<<<<
* Second
is similar to the first - the only difference is
the naming of files and a little addition to configuration file. Some programs
can't name the tiles of original images the way mentioned, they'd do it
like:
prefix_0_0.jpg
prefix_0_1.jpg
prefix_0_2.jpg
...
prefix_1_0.jpg
...
prefix_30_40.jpg
(maybe the numbers here are wrong, I'm not in the mood to check :-))
In
this case you just have to add a line
<<<<<<
PART
100 50
<<<<<<
to the config file (in addition to
already mentioned contents) to specify size of a tile (again - the tiles on the
right and bottom can be of different sizes, of course). If you don't specify
this, program will try to guess the size of tile by loading the prefix_0_0 file.
This can slowdown the program startup - so you better specify this in
configuration file, if it's possible.
As you can see, you only specify
calibration points for the whole (virtual) image (the tiles are just an
abstraction :-)).
I don't know what do you mean by overlappting tiled
images - but the tiles of a single image have to face each other (i.e. tiles of
image can be created by simply cutting the image to pieces).
Hopefully
the following image will clarify the concept of tiled images another bit more
(thanks to axel):

FINAL NOTES
ALWAYS use lowercase filenames (esp. bitmap
extensions - program currently recognizes only bmp, png, jpg (i.e. not bMp or
whatever)). This may/will get better in future :-)