GMAP - manual

Getting started

Here is a quick start guide, I'm assuming you have some source of track data in either .gpx, .kml or a .mp file. If not, there is a simple test file here. Start GMap with that filename as its argument.

	gmap test.mp

GMap should load the file and display your data on the main window GMap will centre the display on your data (but it won't adjust the scale). If no objects are visible, zoom out by pressing the (-) button few times. Once you see the data, point at it with the mouse and click the left button. That will centre it. You can then zoom back in with the (+) button.

GMap uses the left mouse button to centre and the right button to select. When you select an object, the cursor will chamge from an arrow to a plus. Hitting the right button again will de-select the object.

The feature buttons (points,lines,areas,routing,warp) will determine what type of object you can select. When an object is selected, the left mouse button will perform the action selected by the action buttons (move/add,delete,drag).
Depending on the type of object you have selected, some of the operation buttons will be enabled.

Detail operation

This is the reference manual. It gives detail of each of the functions. It deals with the command line and each of the 4 main parts of the on screen interface seperately.

Command line

The command line lists files to bre read into the working map. The map name is taken from the first (editable) file on the command line. All files are merged on read into one (except those marked as reference).
--reference The following file will be loaded into the reference buffer instead of the edit buffer. The data will be displayed but can not be edited and will not be saved.
--gpsdev Change the device used to access the GPS directly. The defailt is "/dev/ttyUSB0".

Menu bar

File-Save/File-SaveAs Saves to first named file on command line or given file name. File type will always be .mp so if you open test.gpx, it will be saved to test.mp. Currently GMap only saves .mp files. If the file you are saving to exists, the original file is renamed to name;version (eg saving test.mp will rename it to test.mp;1 and then save to test.mp)
File-Exit Exit GMap. There are some checks that try to detect unsaved changes. If an unsaved change is detected, a warning is presented.

Edit-Undo Will attempt to undo the last operation performed. The undo stack is very deep so you can go back a long way, however there is no re-do. Undo does not undo file operations or warp operations. Be aware that one you apply a warp, the undo history is pretty useless, since it will restore individual unwarped objects.

GPS menuThe GPS menu allows direct transfer of data from some Garmin GPS receivers. I have tested it with a garmin GPSMap 60CSx and a ForeRunner301. It may work with others. If it doesn't work with your Garmin GPS, let me know. I would not expect it to work with any other brand of GPS. The GPS is assumed to be connected to "/dev/ttyUSB0". This can be over-ridden by the --gpsdev command line option.
GPS-load tracks/GPS-load waypoints Load all tracks or waypoints from the GPS into the current working map.
GPS-show position Read the current position direct from the GPS and display on the map.
GPS-make track read GPS position and create a track in real-time.

Image panel

Mouse Buttons Uses left and right buttons only (no middle yet). Initially, the left centres the image where you were pointing and the right selects something.
Once an object is selected, the left opreration is set by the 'action' buttons. Right de-selects.
Cursor keys will step the image left/right/up/down

Button bar

Move/Add: if you are near a feature (eg vertex of a line) click left and drag. If you are not near, it will probably create a new point in the feature you have selected.

warp/applywarp: This allows you to set an irregular rectangular grid over one image and to then move the points around to register one map against another. Within each 4 cornered area, positions are linearly warped to the new space. You can set up some corrections, then apply the to some map data, then further refine the corrections and re-apply. You can also hold and display a reference map that will not be warped.

Typical usage is as follows:

You have some map data (tracks and the like) from a map drawing program. You also have some tracks you made driving around the area. Problem is they don't line up quite right.

Run gmap with

	gmap imagetracks.mp --reference drivingtracks.mp

Go to the warp image section and zoom in on a point where you can cee a correlation between the images.
Create a warp point on the "imagetrack" and drag it to the corresponding point on the "drivingtracks".
Repeat as necessary depending on what sort of errors you have
Apply the warp.
Look to see if thats fixed all the data you wanted. If not, adjust the points or add new ones and repeat.
If its all OK now, save out the modified "imagetrack" data and then reload it with the "drivingtracks" data to merge them into one file.
```
	gmap drivingtracks.mp imagetracks.mp 
```
You now have one map with both sets of data, correctly registered. Awsome.

In Warp mode the 'action' options allow moving/adding new warp points or deleting existing points.

TAB panel

The TAB panel displays further details of each type of object.
general tab
lines tab
POI tab

More to come

Compatability

GMap will read and display .mp files with tracks with multiple, disjoint sections. It will also handle area features with holes fairly sensibly. It will not allow you to create either of these type of feature.

KML import

If you use certain syntax in the object names in a KML format file, GMap will mark the features with appropriate Garmin tags. Note: these are likely to change.

Line features
feature name	Garmin Type	Special processing
road:trail:
road:unpaved:
road:veryminor:
road:minor:
road:medium:
road:thintrunk:
road:trunk:
road:major:
road:ramp:
coastline:		Converted into a closed polygon (area) feature of type SEA
river:
runway:
town:		Converted into a closed polygon (area) feature
airport:		Converted into a closed polygon (area) feature
contour:thin:
contour:medium:
contour:thick:
border: