XCSoar mapgen usage example

mapgen.md

As of 2017-10-06: If the XCSoar Map Generator site does not work or you want to use the Map Generator in your own project, you can do so as described here. You don't need to know any programming language if you only want to generate maps for XCSoar.

Windows

Disclaimer: I'm writing this up based on my assumptions, have not tried Windows, so YMMV. (!) Read the comment first!

All the required tools and dependencies are available on Windows

• Git : https://git-scm.com/download/win or https://git-for-windows.github.io/ (the same thing with explanation of the tools)
• Python : https://www.python.org/downloads/windows/ (Install the 2.7.x version and make sure the option to add the python executable to the PATH is enabled as this will make running the XCSoar mapgen scripts simpler)

Start with installing these, then use Git to clone the XCSoar mapgen repository from http://git.xcsoar.org/cgit/master/mapgen.git/

Launch the Command Prompt and then you can use Git BASH for this:

cd C:\Users\yourusername
git clone git://git.xcsoar.org/xcsoar/master/mapgen.git

If all went well, you should have a new folder C:\Users\yourusername\mapgen with files inside.

The scripts are in the mapgen\bin folder of the repository you've just cloned. They do not have the .py extension but that's not a problem (only for Windows since it cannot use the extension to automatically associate the scripts with Python)

Running Python on Windows : https://docs.python.org/2/faq/windows.html

cd C:\Users\yourusername\mapgen\bin
python mapgen

This should not yet work, because there are a few other dependencies to be installed. The script you've just run should have printed out what it is missing. I'm using Linux and I did not have these packages. Visit the URLs for each of the missing dependencies on your system and install them.

Command shptree is missing on the $PATH. Please install it from the mapserver package (http://mapserver.org/).
Command 7zr is missing on the $PATH. Please install 7-zip (http://www.7-zip.org/).
Command ogr2ogr is missing on the $PATH. Please install gdal (http://www.gdal.org/).
Command gdalwarp is missing on the $PATH. Please install gdal (http://www.gdal.org/).
Command geojasper is missing on the $PATH. Please install geojasper (http://www.dimin.net/software/geojasper/).

For 7zr, you will have to install the LZMA SDK, because only that has 7zr.exe, the normal 7-zip installation from http://www.7-zip.org/ only contains 7z.exe which mapgen does not seem to be able to fallback to on its own.

Optionally: Apparently, Windows Vista, 7, 8 and 10 supports symlinks, so you may be able to just create a link 7zr.exe -> 7z.exe and be fine without installing the SDK. You will have to figure out how to do that yourself though. This article may help.

Additionally, depending on where the additional software installs themselves, you may have to add a few new locations to the PATH. See https://www.computerhope.com/issues/ch000549.htm for example on how to do that.

Try running python mapgen -h. If it's working you should see its help:

usage: mapgen [-h] [-r resolution] [-l level_of_detail] [-c] [-w2]
              (-b left right top bottom | -w waypoint_file)
              output_file

Create a custom XCM map file for XCSoar

positional arguments:
  output_file           filename of the output file

optional arguments:
  -h, --help            show this help message and exit
  -r resolution         resolution of the terrain in arcseconds per pixel
  -l level_of_detail    1: only major topography, 2: medium level of detail,
                        3: every tiny city name and road
  -c                    compress topology data for smaller file size but lower
                        speed
  -w2                   create embedded waypoint file from welt2000 database
  -b left right top bottom
                        boundaries of the map file
  -w waypoint_file      a waypoint file that should be included in the map
                        file

Great. From here on, the only thing to figure out for generating a simple map are the boundaries. For the -b parameter of the script, the order of boundary values are as follows.

• "left" is minimum longitude
• "right" is maximum longitude
• "top" is maximum latitude
• "bottom" is minimum latitude

The values of the geographic coordinates should be in decimal degrees format. You can obtain the values by selecting a boundary on the map of the XCSoar Map Generator or its mirror site, or from https://www.latlong.net/

Below are approximate values for Budapest, HU, for example. Notice that you don't need to be specific to the minutes/seconds, but you can be.

18.98 19.17 47.56 47.41

Running the command with all parameters

cd C:\Users\yourusername
python mapgen\bin\mapgen -r 9 -l 2 -b 18.98 19.17 47.56 47.41 budapest.xcm

The result of this should be the map file C:\Users\yourusername\budapest.xcm that you can copy to and try in XCSoar.

Parameters of the command:

• -r : resolution, XCSoar site default is 9, high is 3, pick something inbetween
• -l : level of detail, highest is 3, lowest is 1
• -b : the boundaries in decimal degrees format

(!) When generating for the first time the script will download map data from map-data.sigkill.ch, which is the current backend of these command line tools. Subsequent map generation will work with that data, will be quicker and probably also works offline.

Linux (Fedora 24)

Assuming Git and Python 2.7.x are installed and the missing packages are the ones listed above:

cd
git clone git://git.xcsoar.org/xcsoar/master/mapgen.git
sudo dnf install mapserver gdal p7zip
sudo ln -s /usr/bin/7za /usr/bin/7zr
wget http://www.dimin.net/software/geojasper/geojasper_linux32.tgz
sudo tar xzvf geojasper_linux32.tgz -C /opt
sudo chmod +x /opt/geojasper/geojasper
export PATH=$PATH:/opt/geojasper

Scripts in mapgen/bin/ should run now. Additional Python libs may be required that you can install with pip.

This bit from https://github.com/XCSoar/mapgen/blob/6f9f6844820e1c9f3f019a5a7134049ea79a68d1/lib/xcsoar/mapgen/util.py makes me curious if the tools run on Windows at all.

Dependencies and their verification:

__used_commands = { 'ogr2ogr':   'Please install gdal (http://www.gdal.org/).',
                    'shptree':   'Please install it from the mapserver package (http://mapserver.org/).',
                    '7zr':       'Please install 7-zip (http://www.7-zip.org/).',
                    'wget':      'Please install it using your distribution package manager.',
                    'geojasper': 'Please install geojasper (http://www.dimin.net/software/geojasper/).',
                    'gdalwarp':  'Please install gdal (http://www.gdal.org/).' }

def check_commands():
    ret = True
    for (cmd, help) in __used_commands.items():
        try:
            subprocess.check_output(['which', cmd], stderr=subprocess.STDOUT)
        except:
            ret = False
            print('Command {} is missing on the $PATH. '.format(cmd) + help)
    if not ret:
        sys.exit(1)

The suspect is:

subprocess.check_output(['which', cmd], stderr=subprocess.STDOUT)

I am not aware of the availability of which in a Windows shell, which (no pun intended) means verifying the dependecies may always fail.

This question is related https://stackoverflow.com/questions/5226958/which-equivalent-function-in-python and the answers provide alternative approaches that would require the source be modified to make it work on Windows.