Configuring map download

The mapping websites that are accessible from nhGPS are user configurable. nhGPS reads the mapping website configuration from the file c:\documents\nhgps\nhmapwebsites.xml, which is installed with nhGPS. Edit this file to customize the list of websites that is shown, or to add your own. Please note that the file will be overwritten when you reinstall or upgrade nhGPS. Also, the file format may change in the future.

To be able to download a map from a website, the site should offer some means of generating a map based on latitude/longitude. The coordinate should be passed in the form of a query string in an url (GET method). For example:

http://www.mymapsite.com/mapdownload.cgi?lat=12.123&lon=15.123&zoom=1

Map images can be downloaded directly or indirectly. Direct download means that nhGPS knows the URL of the map image itself. With indirect download, nhGPS knows the URL of a webpage containing the map image. It downloads the webpage and searches it for the file name of the map image. Then nhGPS downloads the image itself.

The configuration file also contains information about the map scale, projection and the size of the map images.

Configuration file syntax

The configuration file is in XML format, with the following structure:

<mapsites version="1">
  <mapsite ... />
  <mapsite ... />
  ...
</mapsites>

Each website has its own <mapsite ... /> tag. For example, the above mentioned example might look like this:

<mapsite name="My Map Site (1.4km)"
    type="1" 
    urltemplate="http://www.mymapsite.com/mapdownload.cgi
?lat={latdeg}&amp;lon={londeg}&amp;zoom=1"
    imgprefix="&lt;td align=center &gt;&lt;img src=&quot;"
    imgpostfix="&quot;"
    horzscale="1421.1"
    vertscale="1421.1"
    imgwidth="1000"
    imgheight="1000"
    projection="0"
    />

This example is an indirect map download (type=1, see below). Please note the proper quotation of certain characters according to the XML standard: < is encoded as &lt;, & becomes &amp; etc. So the actual value of imgprefix is

<td align=center ><img src="

Most XML tutorials will explain character encoding in detail.

For indirect downloads, the urltemplate gives the url of the web page containing the map image. nhGPS replaces {latdeg} and {londeg} by the actual GPS coordinates. The resulting URL is downloaded. Next, the downloaded webpage is searched for the imgprefix text. If found, the characters following the imgprefix string are assumed to be the url of the map image. From there, the webpage is searched for the imgpostfix string, which terminates the image url. For example, if the downloaded web page would contain:

<table><tr><td align=center ><img src="/images/map12345.gif"></td></tr></table>

then the extracted image url would be /images/map12345.gif. This URL is expanded to an absolute URL (http://www.mymapsite.com/images/map12345.gif) and downloaded.

The possible attributes for the <mapsite> tag are:

• type: 0=direct (urltemplate is the url of the map image itself) 1=indirect (urltemplate is the url of an html page containing the map image)
• name: The name as displayed in the Map Download dialog
• urltemplate: The url to be downloaded. {latdeg} and {londeg} are replaced by the actual coordinates, in decimal degrees
• imgprefix: For indirect download, prefix of the image url (see example above)
• imgpostfix: Postfix of the image url
• imgwidth: Width of the downloaded image in pixels
• imgheight: Height of the downloaded image in pixels
• horzscale: Width of the downloaded image in meters
• vertscale: Height of the downloaded image in meters
• projection: 0=orthogonal (default, most mapsites use this format) 1=y-axis is compressed near the poles
• xoffset: X coordinate (in pixels) of the target point (defaults to imgwidth/2)
• xoffsetprefix: Additional horizontal offset (in pixels) can be determined from the html source, using prefix/postfix strings. For example, the html source may contain the coordinates of a marker pointing to the target point.
• xoffsetpostfix
• yoffset
• yoffsetprefix
• yoffsetpostfix
• decimalpoint: Decimal separator (default is point)

For direct downloads (type=0), the attributes imgprefix, imgpostfix, xoffsetprefix, xoffsetpostfix, yoffsetprefix and yoffsetpostfix are ignored. In the above list, attributes projection and below are optional.