splitter

Basic premise

mkgmap will die/croak/crash if you feed it an OSM file that is too big. Use splitter to split the OSM into smaller chunks that mkgmap will work with.

Running splitter

Basic usage to run splitter is:

java -jar splitter.jar osmfile

Where osmfile is the original (too large) file that you want to split.

Splitter can take a number of options to modify its behaviour.

Understanding splitter's output

Splitter takes an OSM file (which is in XML) and splits it into smaller chunks (still in XML) so that they can be processed by mkgmap. Splitter will create at least two OSM files, which by default are named 63240001.osm.gz, 63240002.osm.gz etc. (NB for those that don't know, the gz suffixes just indicates that the osm file has been compressed using the gzip algorithm). You can change the output names using the mkgmap option --mapid=[differentname] if you like. See the splitter website for more info.

The second thing that splitter outputs is a file called template.args. This contains a list of each of the output tile names, a textual description, and the input filename. template.args is used as an input for mkgmap (using the -c option). Here's an anotated example:

mapname: 63240001
description: OSM File
input-file: 63240001.osm.gz

You can edit the description line to be more descriptive (assuming you know what area the tile covers, see later). The description is visible in the Garmin unit when you access the map-setup menu (at least, it is on a GPSMap76Csx). Setting a useful description can be handy because it means that if you want to de-activate tiles that you don't currently need, you can do it from inside the GPS.

The last thing splitter creates, by default, is a file called areas.list. See below for more on this.

Understanding tile size

Splitter exists because mkgmap chokes if the files you give it are too large. Splitter takes some OSM and splits it into individual tiles, designed to be small enough for mkgmap to work OK. However, this process can fail. If you set splitter to work on a UK extract, it generates tiles that are too large for mkgmap. To overcome this, you need to use the --max-nodes= option.

By default (i.e. if you don't use the --max-nodes option, splitter sets max-modes to 1600000 (1.6 million). This number is too high for the UK (and probably other well-mapped areas, like the Netherlands). If you run splitter on an UK extract and use the default, it creates a couple of tiles that are too large for mkgmap. To resolve this problem I have found that a value of 1500000 (1.5 million) creates tiles that mkgmap can process.

--max-nodes should be set as high as possible (because you normally want as few tiles as possible). Fewer tiles makes things easier when it comes to creating routeable maps because routes may cross from one tile to the next. The processing that splitter and mkgmap must do to allow multi-tile maps to be routeable is considerable, so the fewer tiles the better. In reality, you are performing a juggling act between splitter and mkgmap: you need to set --max-nodes as high as possible to reduce the number of tiles, whilst setting it low enough that even the biggest tile isn't too big for mkgmap to cope with.

Defining your own areas

By default, splitter will decide what size each tile should be and split the file accordingly. When it's finished, it generates a file called areas.list which describes each of the tiles. You can edit areas.list manually and use it as an input to splitter, thus defining exactly which area each generated tile will cover. A typical line in areas.list looks like this:

63240001: 2318336,-280576 to 2451456,-129024
# : 49.75,-6.0 to 52.602539,-2.768555

The first line gives the tile name (63240001) then the Garmin coordinates (more on this in a second) for the bottom-left and top-right corners of the tile respectively. The second line is a comment and exists for you to see the standard, decimalised latitude and longitude of the bottom-left and top-right corners respectively. Each entry therefore tells splitter the name of the output tile and the bounding box defining the area of that tile.

Garmin units can be generated from standard decimal lat and long. To get from latitude and longitude in degrees to Garmin units multiply by 46603 (which is (2^24)/360). If you do the conversion carelessly, it will appear to work but the tiles may overlap at low zoom levels which may cause problems for inter-tile routing. To avoid overlap you have to make sure that the number is exactly divisable by 2048.

So if you want to define your own areas, here's the procedure.

(Optional) run splitter once so that it generates an areas.list file for you to edit.
Tweak the bounding box for each tile - I use Google Earth to find the lat and long coordinates I need, then convert them to Garmin units making sure the result is divisable by 2048.
Re-run splitter using the --split-file=areas.list argument. Splitter will now re-split the OSM according to the bounding boxes you defined in the edited areas.list file.

Splitting contour data

You can (indeed, you probably will have to) use splitter to split OSM contour data generated using srtm2OSM. The output from srtm2OSM is in a mixed format which intersperses nodes and ways, whereas "pure" OSM data starts with all the nodes, then lists all the ways. To handle this mixed format, you should invoke splitter with the --mixed option, otherwise it will fail (usually by not splitting anything at all).

Using the --geonames option

Splitter generates a series of tiles for mkgmap to process. mkgmap, in turn, can give each of these tiles its own name, if you use the --description command line switch (see here too). It can be a bit fiddly to figure out what the right description for any given tile should be (as you may have no idea what geographical area it covers until mkgmap renders it, which is a bit of a chicken and egg situation). However, you can use the splitter --geonames-file=filename switch to have splitter automatically assign a name to the tile based on the country being split, and the name of the largest city in that tile.

To use this option, first visit http://download.geonames.org/export/dump/ and download the cities1500.zip file. Now invoke splitter with:
java -jar splitter.jar --geonames-file=path_to_where_you_saved_cities1500.zip osmfile
Once it has completed, you will see that underneath each tile defined in the template.args file, a sensible description has been added, e.g.:
mapname: 63242011
description: IT-Venezia
input-file: 63242011.osm.gz

Defining what the tile filenames are

The --mapid=8_digit_number switch defines what the actual filename for each tile will be. By default the first tile is called 63240001.osm.gz and subsequent tiles have filenames that increment by 1 each time. You may want to use different filenames for different countries (e.g. I use 63240001 for UK, 63241001 for France, 63242001 for Italy etc) to help quickly differentiate tiles. Even if you keep them in separate folders, where the need to differentiate is less, it still helps to use unique filenames for each country because later, when you come to generating the Garmin tiles using mkgmap, you will need to ensure that each tile has a unique mapname and it gets confusing when the filename and the mapname are different.