MAPWELT MANUAL

MapWelt was written with the intent of being used on PDA's or smartphones. But because it is written in a language (TCL) that is ported to a large number of platform, it also runs on these platforms. This is quite usefull since things like map making, calibrating, editing of waypoints etc is quite hard on PDA's because of their limited methods of input and small screens. Preparing maps and waypoints is best done on a 'normal' pc, and then transferring the data to the PDA. MapWelt stores its data in two databases:

• MapWelt_settings.db3:This is device specific and holds paths to maps, gps device etc. This should not be transferred between devices.
• MapWelt_waypoints.db3: This hold the waypoints, and can be transferred between devices.

First time startup

If the program is started for the first time, it will automatically create a number of files in the working directory. These files will hold preferences, settings, waypointdata and a demo file for translation of MapWelt. Furthermore a small demonstration map is created which is automatically loaded at startup. Initially the program is setup to read GPS data from an included file. To see the demonstration, push the sattelite dish (third button) or select File|GPS.

Normal Startup

If the program is started, it will automatically load the map of the previous session. By default the program does not start reading the GPS device, so to start this, press either the sattelite dish or, from the menu select File|GPS. But make sure that your GPS settings are correct, see gpssettings

In the topleft, the speed (km/h) and travelled distance is shown (If there is an active waypoint, the speed and distance to the selected waypoint is shown). This part is also used for showing the description of a (selected) waypoint. The two numbers right from the buttons are the number of sattelites used for the gps positioning and the corrected altitude (If the map file has a HeightCorrection entry). The second line shows the lattitude and longitude, and the travel direction. If routing is on, a fourth number will shown giving the direction of the active routing point. The last number here is the time received by the gps.

Buttons:

• + This will increase magnification of the map, unless it is at its maximum magnification.
• - This will decrease magnification of the map, unless it is at its minimum magnification.
• sattelite dish: If pushed, the program starts reading gps coordinates from either a file, or from the GPS device. This will be green if positions are received from the GPS device. If the communication with the GPS device is OK, but there is no position fix, this will be yellow. If the connection with the GPS device is lost, it is red.
• Cross. If pushed, the map will be centered at the GPS location if the gps coordinates are within the map.
• Trace: If pushed, the gps positions visited will be connected by a line. If unpushed the trace will be removed. Pushing it again will start the trace from that point onwards.
• Sun: If pushed, the position of the sun and the moon will be displayed on the map. If visible (above the horizon), the sun will be represented by a thick yellow line. If not visible, the sun will represented by a thin yellow line. Similar for the moon, which is coloured grey. The idea behind showing the sun and moon positions, is that they can be used as a kind of compass for finding directions. In the image above, the sun is visible, and the moon is invisible.
  
• Finger: If pushed, will enable the finger menu. This is primarily intended for using when walking etc, and precise pressing of buttons is not possible. The screen is divided in 9 parts. If the map is touched, the 9 parts are shown, and a text with explanation is shown. If pressed within approximately 5 seconds, the action will be taken. After approximately 5 seconds, the grid will disappear again.
• L:If pushed the program will log the gps data to a file (mapwelt_logYYYYMMDD.txt year month date) in the same directory as the program
  

• Movemap If selected, the map will not move with the GPS coordinates, you can then move the map with the stylus or with the mouse (button 1 pressed). This mode is equal to the cross button unpressed.
  
• LockToGPS. If selected the map will move the GPS coordinates. It will not move with the stylus or mouse. This mode is equal to the cross button pressed.
  
• Measure. To measure the distance between two points. At the first point, press the mouse button, or lower the stylus, and at the seond point, release it. It measure the straight line distance in meters and in pixels. The result of the measurement is also filled in to the MapDetail/MapSettings entry boxes, since you might want to use them there for calibration purposes.
  
• SetRef 1 2 and 3. Set the calibration points of the map. This will set calibration point 1 2 or 3 of the map to the selected XY position of the image, and the presently measured GPS location. This is used for calibrating the map whilst moving.
• AppendBorder, this will add the selected point to the border of the map.
• AppendWayPoint. This will append the selected GPS location to the waypoints.
  
• The remaining two items show the selected image position and selected latitude and longitude.

Your present location on the map is shown by the tip of red arrow. The direction of the arrow is the direction in which you are moving.
If you tap on a waypoint, the description of the waypoint will be shown in the speed/odometer section. Furthermore a popup menu will be displayed with more details, and the option to set the point as active point for routing.

If the map is locked to the gps, you can also use the direction key of the pocketpc (the little joystick) to move the map. After approximately 5 seconds, the map will jump back to the gps coordinates. I use this to have a quick peek at unexposed parts of the map. Also if you press enter (the key in the middle of the direction keys, or the joystick itself), the program will jump to the active waypoint (if this is on the map). Again after 5 seconds it will jump back to the gps coordinates.
If you tap on a waypoint, a menu will appear, with data about the waypoint, and the option to use the waypoint in navigating.

Menu's

File

• GPS: Switches the GPS device on or off
• GPSSettings: Pops up a dialog where one can set the GPS device parameters, or have the program attempt to determine them. The program can take input from three different sources:
  1. It can read from a serial port, in which case the top box should hold something like "com2:" (note the colon), and the lower box something like "4800,n,8,1" (baud,parity,databits,stopbits). The actual values are dependent on your hardware. For bluetooth devices, the values in the lower box are usually not important, but they should be there.
  2. It can read from a text file. The top box should hold the filename (including the path) for instance "/mygpsdata.txt". (for directory separators one must use forward slashes, and not backslashes). The lower box then must be the literal text "FILE" without the quotes. The first time you startup MapWelt it is this mode and this play's a little demo (of me cycling through boxmeer). The format of this file is just text directly as it comes from the gps receiver. You can create such a file by checking File|SaveLog.
  3. It can read from a server. In this case the top box can be empty. The lower box the must be the literal text "http" (without quotes) followed by the servername or ip number, followed by the port number. In this case you should have a server running with a program that serves gpsdata. I've only tested this with gpsfeed+ ( http://users.hol.gr/~dzach/gpsfeed/index.html)

  Reading from file and http is mainly intended for debugging purposes.

  Buttons:

  • Save: saves the present settings.
  • Discover: if pressed, all available serial ports will be scanned at various baudrates to see if a GPS device is found. For this to work, the GPS device MUST be switched on. If you have a bluetooth GPS receiver, you must switch bluetooth on as well, the program cannot do this. A position fix is not required, but it has to send NMEA sentences to work. The textbox shows the progress of the 'discover'

  Checkboxes:

  • Start at Program startup: Once the program is started, it will automatically start reading from the GPS.Only recommended for devices with inbuilt GPS.
  • reopen if connection lost: The serial port of pocketpc's seems to be a bit buggy, which can cause problems. If selected, mapwelt will try to reconnect to the GPS. Only recommended for devices with inbuilt GPS.
• MobileSettings. (Only on windows mobile) Pops up a dialog to set mobile specific parameters.

  NoSuspendMode prevents windows mobile from shutting down

  DisplayOff, will turn off the display after 30 seconds, but all programs remain active. Since the display is off, it is not possible to tap the screen to turn on the display. If MapWelt is the active program (the one in front), pressing the joystick button will turn the display back on. If MapWelt is not the active program, press the hotkey and try again. If this doesn't work, press the on/off key of the pda. Use this option with caution, it might hang your pda requiring a soft reset.

  Bluetooth. Switch bluetooth on and off when starting/quiting MapWelt. This option doesn't work for all devices, it depends on make/model.

  Hotkey, You can assign a hotkey to MapWelt. This only works when MapWelt is running. If MapWelt is not the topmost application (so not visible), pressing this button will put it on top, and make it visible. Valid button names are:

  soft1, soft2, volumeup, volumedown, record, end, home, back, talk, app1, app2, app3, app4, app5, app6, app7, app8, app9, app10, app11, app12, app13, app14, app15, or app16.

  On my pda I use app2 which normally start Contacts.

• Savelog: If selected the program will log the gps data to a file (mapwelt_logYYYYMMDD.txt year month date) in the same directory as the program. Note that this can 'hang' the program when switching the pocketpc off and on, since the sd-card might not be available tries to write to the file.
• Zero Odo: Resets the odometer
• Sound: enable/disable sound
• Language: Select the language you want to use. At present only english and dutch. OS_locale will choose depending on your device settings.See below how to translate mapwelt.
• Sync Files w. Track: This calculates latitude and longitude positions for a set of files in a directory, and creates a kml for use in google earth. This is done with the aid of a selectable track. The resulting kml file will show the track, and markers for all the files in this directory. It is mainly intended to record where pictures or notes were taken. Since it relies on file dates and times, it is essential that your camera or voice recorder are set to the correct time and date. If this option is selected, a new window is opened. Select the track which covers the time period of the files in question. The timediff field can hold a time difference to correct for differences in time zones. Normally, this should be kept at 0 since MapWelt already uses the computer's timezone. The url field can hold a url which will be prepended to all file locations in the kml. If this is left blank, the kml must be in the same directory as the images. Next, select the directory containing the files, and press go. If exiftool (http://www.sno.phy.queensu.ca/~phil/exiftool/)is installed on your computer, the gpsdata will also be written in the exif part of your images. Exiftool should have the name exiftool or exiftool.exe (windows), and be in the systempath or in the mapwelt directory.
• Exit: When you exit, you get a buttonbox with 4 choices related to the track that has been recorded during the course of the program:.
  1. Cancel, the program will not exit and continue running
  2. Keep. The track information will remain in the database, program exits. At next startup the track will still be in the program, and the new trackpoints will be added to the 'old' track..
  3. Delete. The track information will be deleted, program exits
  4. Save&Quit. A file requester will be shown with the default name of MapWelt_Track_YYYYMMDD_hhmm.gpx. After pressing save, the generated track will be saved to this gpx file, the track will be deleted from the database and the program exits. The gpx file can used in other programs to see where you have been, how far you went etc. For instance you can load it in Google Earth. This option can take some time, depending on the length of the track. Although I've not seen it taking more than approximately half a minute. Normally after the autosave, there is a time of inactivity, after which the program exits.

View

• ZoomIn:Zooms the map
• ZoomOut:Zooms the map
• MaxZoom: Zooms to the most detailled level. Especially usefull for the OSM (openstreets) maps that have incomplete data which could prevent you zoomin in.
• MoveMap: Map can move by dragging with mouse or cursor keys
• LockToGPS: Keep your position centered on the map
• Measure: Measure distance by pressing left mouse key on first position, moving and releasing on second position.The calculated distance is the shortest distance between the two points.
• Trace: Switch on or off on the map.
• SunMoon: Switch on or off on the map.
• FingerMenu: Switch on or off on the map.
• Avatar: Switch on or off on the map.
• GPSData: This pops up a screen showing textual data from the gps device.
• SatData: Shows the locations of the satelites in view, and their signal strength
• TrackStats: Shows a graph of the speed and altitude of the recording track

Map

• LoadMap: Loads a different map
• SearchMap: Search the best map (with highest resolution) for current GPS position
• Maps@here: Shows a list of all maps which cover the current GPS position.
• MkIndex: Make an index of your maps. If pressed, you select a directory, and all maps in that directory will be added to the index. The index is required for the SearchMap/Maps@here/Auto and Timed functions.
• Auto: If enabled, a suitable map will be loaded if you move out of the currently loaded map
• Timed: If enabled, the program will check each minute to see if a more detailled map is available for the current GPS position.
• Stay in Map: This is for use in version 2 maps. The program will use all the submaps of the loaded map, but will not load other maps.
• Calibration: Pops up a window where the calibration for the map can be viewed/changed, see mapcalibration
• OSM_Online:
  • Newdatabase: This will create a new (empty) map for openstreetmap data (This will only make an empty database, not automatically load it)
  • Off:Only data in the map file will be used. Mapwelt will not retrieve maps over the internet.
  • Missing: The data in the map file will be used if available, if not, it will be retrieved over the internet and added to the map file
  • UpdateAll: All data will be retrieved from the internet, updating or adding to the map file

Waypoint

• Waypoints Pops up a window showing all waypoints series/routes and tracks, and the ability to edit/display etc, see waypoints
• Load Waypoints: Loads waypoints/routes/tracks from GPX files
• Start Nav:
• Stop Nav
• Sync Nav: If selected, the programs automatically adjusts the point to navigate to if you have entered two consecutive waypoints in the selected navigation direction. This makes the program 'catch up' with you without you having to go to each point precisely or manually adjust the point to navigate to. Of course, this can lead to the wrong point being selected if the route crosses itself, or goes the same path twice.
• Nav Up:Navigate from start to end
• Nav Down:Navigate from end to start
• Append: Apped the current GPS position to the waypoints.
• Autogen: Automatically produce a track of where you have been (required for the trace to be displayed).
• VacuumDB: Reclaim diskspace from the settings file.

Help

• About Mapwelt: About
• License: Shows the license
• Console: Shows a Tcl/Tk console. Commands can be entered here for debugging purposes, and some messages appear here.
• dumpStateDumps some debugging info to a file

Map Calibration:

The first line shows the currently loaded map, and just below is its scale (meters/pixel).

Here one can make a new map, or edit an existing map. A map consists of an image, its projection settings (that is how the image is distorted), and its calibration (giving the gps coordinates for several image positions).
With the LoadImg button a new image can be loaded. Using this will NOT result in a tiled map, but will load the image completely in memory, and if this map is saved will result in a .map file describing the mapcalibration. This should not be used on pocket pc's, since loading the image completely will use too much memory. The preferred method is to first create a tiled map with the image2maps program, and calibrate this map in MapWelt (first load the tiled map, and then go to this screen).
The projection and its parameters is usually the most tricky part. Sometimes it is given on the map.
The calibration of the map can be done with 1 to 3 points. If you manually edit MapX, MapY, Lat or Lon positions, you should press one of the Ref1&Dist, Ref1&2 or Ref1&2&3 buttons after the edit. For the first point you should press Ref1&Dist etc. The edit will only be effective after pressing one of the Ref... buttons. Note that Map X and Y coordinates should be entered in the 'computer standard' form where the top left pixel is 0,0.

The calibration points are used to determine the scale of the map, its rotation, and with three points also the difference between the X and Y scale. If only 1 calibration point is available, the rotation is assumed so that North is Up on the map, and the scale will be calculated from the fields in DistPixels and meters. Maps often have a scale printed besides them where one can read this information.

The last entry in this window is the Border. Here one can define the border of the map. This is a list of X Y coordinates (minimum 3 X and Y's) which define a border. If the GPS signal moves out of this border, a different map will be loaded. This can be used with for example scanned maps that have a white unprinted border around the image. Note that Map X and Y coordinates should be entered in the 'computer standard' form where the top left pixel is 0,0 and right is +X and down is +Y.

The calibration can also partly be done on the Map Tab, see Map.
You can also make a map without an image by pressing NoImg. The program will then use the present GPS location as a starting point of your map. If you move out the initial map, it will automatically be expanded. The scale of the map will be calculated from the DistPixels and meters fields. If the trace is switched on, you will at least see a map of where you have been.

Some more information about the calibrating of maps is give in Maps

WayPointSeries

After selecting form the menu Waypoints|Waypoints, a table is shown which displays all the tables in the waypoints database, and each table in the database is a route or track or set of waypoints. Here one can select whether a set should be displayed, used for routing, whether it should be included in the actions, and set the maximum scale at which this set should be displayed, and how many points of this series should maximally be displayed. The last two options can be used to prevent drawing of very many points on for instance a world map. Here one can also import or export waypoints in GPX-format or show the statistics of a track.

Waypoints

Shows a table giving the information for each waypoint/routepoint/trackpoint.Lattitude and longitude are in decimal degrees, and north and east are positive values, south and west are negative values. Lattitude and longitude values are required, the other values are optional.The value for sym will be used for display. If there is a GIF file in your wptimg directory with the same name as in the sym column, than that image will be shown at the waypoint location. If no waypoint image is available, the program will show the waypoint as WNNN (where NNN is the waypoint number). The action column can be used to assign an action to a waypoint. If this waypoint is approached, the action will be performed. At present the only action is "playsound wavname" where wavname can be any wav in the sound directory. Wavname in "playsound wavname" should not have a wav extension. If the action is defined, then the dist field should also hold the distance (in meters) at which the action should be done.

The easiest method to edit large numbers of waypoints, is to select the points from the table, and copy&paste them to a spreadsheet, edit them in the spreadsheet, and paste them back in the table.

All waypoint data is stored in the mapwelt_settings.db3 file in the same directory as the program. This (sqlite database) file has only information about waypoints, and can be transferred between different devices. It is more convenient to import/export/edit on a regular pc, and to transfer the mapwelt_settings.db3 file to the mobile device then to do this on the mobile device itself.

mapwelt_prefs

Translating

MapWelt be translated to virtually any language. This is done via *.msg files. The US english file (en_US.msg) is automatically placed in the mapwelt directory as an example and starting point.To create for instance a german translation, copy en_US.msg file to de.msg, and change all lines beginning with mcset en_US to mcset de, and translate the second string. So

mcset en_US "Color" "Color"

should become

mcset de "Color" "Farbe"

Most languages also use non-ASCII symbols, these should be represented as Unicode

mcset de "About" "\u00dcber"

will show the text Über

Lacking