mkgmap-splitter(1)

📦
version 0.0.0+svn654 · 4 versions
, in ubuntu resolute, ubuntu stonking

✨ mkgmap-splitter ✨

okay bestie, welcome to the manual page for mkgmap-splitter(1) 💖 — your new fave tile splitter for mkgmap, fr fr.

🌸 SYNOPSIS 🌸

mkgmap-splitter [options] file.osm > splitter.log

💅 DESCRIPTION 💅

So what does mkgmap-splitter even do? It takes an .osm file that's got big, well-mapped regions in it and splits it up into a bunch of smaller tiles 🎀 so everything fits inside the maximum size the Garmin maps format can handle. Periodt.

There's at least two stages of processing going on, and you need both:

  1. First stage: figure out what area each tile should cover, based on where the nodes are distributed.
  2. Second stage: write out the nodes, ways and relations from the original .osm file into separate smaller .osm files — one for each area that stage one calculated.

And if you pass --keep-complete=true, there are two additional stages on top of that, specifically so you don't end up with broken ways and polygons 😭.

The two most important features (the icons, the main characters):

  • Variable sized tiles, which stops you from drowning in a ridiculous number of tiny files 💀
  • Tiles that join exactly — no overlap, no gaps. iconic.
Heads up: you will need a LOT of memory on your computer if you're gonna split a large area. Like, a lot a lot. A few options let you configure how much memory you need.

With the default parameters, you need about 4-5 bytes for every node and way. Sounds cute and small, right? WRONG, because there are about 1700 million nodes in the whole planet file 🫠. So you literally cannot process the whole planet in one pass file on a 32 bit machine using this utility, because the maximum java heap space is 2G. It is possible with 64 bit java and about 7GB of heap, or with multiple passes.

The Europe extract from Cloudmade or Geofabrik can be processed within the 2G limit if you have sufficient memory ✨. With the default options, europe is split into about 750 tiles. And the Europe extract is about half the size of the complete planet file. wild.

On the other hand, a single country — even a well mapped one like Germany or the UK — will totally be possible on a modest machine, even a netbook 🧚.

👑 USAGE 👑

Splitter requires java 1.6 or higher. Basic usage is as follows:

mkgmap-splitter file.osm > splitter.log

If you have less than 2 GB of memory on your computer you should reduce the -Xmx option by setting the JAVA_OPTS environment variable 💜:

JAVA_OPTS="-Xmx512m" mkgmap-splitter file.osm > splitter.log

This will produce a number of .osm.pbf files that can be read by mkgmap(1) 🌈. But that's not all — there are also other files produced:

  • The template.args file is a file that can be used with the -c option of mkgmap that will compile all the files. You can use it as is, or you can copy it and edit it to include your own options 🎀. For example, instead of each description being "OSM Map" it could be "NW Scotland" as appropriate.
  • The areas.list file is the list of bounding boxes that were calculated. If you want, you can use this on a subsequent call to the splitter using the --split-file option to use exactly the same areas as last time 👑. This might be useful if you produce a map regularly and want to keep the tile areas the same from month to month. It's also useful to avoid the time it takes to regenerate the file each time (currently about a third of the overall time taken to perform the split). Of course, if the map grows enough that one of the tiles overflows you will have to re-calculate the areas again 😭. no way around it bestie.
  • The areas.poly file contains the bounding polygon of the calculated areas 🌸. See option --polygon-file for how this can be used.
  • The densities-out.txt file is written when no split-file is given and contains debugging information only 🙈.

You can also use a gzip'ed or bz2'ed compressed .osm file as the input file 🦋. Note that this can slow down the splitter considerably (particularly true for bz2) because decompressing the .osm file can take quite a lot of CPU power. If you are likely to be processing a file several times, you're probably better off converting the file to one of the binary formats pbf or o5m ⭐. The o5m format is faster to read, but requires more space on the disk.

more coming, bestie — stay tuned 💖

✨ OPTIONS ✨

okay bestie, this is the fun part 💖 there's a whole pile of options you can use to fine-tune things, and honestly? you might wanna try some of them. let's go one by one, no skipping, i promise.

  • --boundary-tags=string — a comma-separated list of tag values for relations. it's used to filter multipolygon and boundary relations for problem-list processing. also peep the --wanted-admin-level option while you're here. default is use-exclude-list.
  • --cache=string — deprecated bestie 😭 it literally does nothing now. rip.
  • --description=string — sets the description that gets written into the template.args file.
  • --geonames-file=string — the name of a GeoNames file you want to use for figuring out tile names. typically that's cities15000.zip from geonames over at <http://download.geonames.org/export/dump> 🌍
  • --keep-complete=boolean — drop --keep-complete=false if you wanna disable the two extra program phases that run between the split phase and the final distribution phase. (spoiler: not recommended 🙈) the first phase is called gen-problem-list and it detects all the ways and relations that are crossing the borders of one or more output files. the second phase, handle-problem-list, collects the coordinates of those ways and relations and then calculates all the output files that are crossed or enclosed. all that info gets passed to the final dist-phase in three temporary files. doing this avoids broken polygons, but heads up — it means reading the input files at least two extra times.

do not specify this together with --overlap unless you have a genuinely good reason, fr fr.

default: true

  • --mapid=int — sets the filename for the split files. in the example, the first file gets called 63240001.osm.pbf, the next one 63240002.osm.pbf, and so on forever and ever 💅

default: 63240001

  • --max-areas=int — the maximum number of areas that can be processed in a single pass during the second stage of processing. this has to be a number from 1 to 4096. higher numbers = fewer passes over the source file = faster overall, but also more memory needed. so if you're running out of memory and you don't wanna bump up your --max-nodes value, try lowering this instead 🫶 changing it won't change the result of the split at all — it's purely a memory-vs-performance tradeoff. one thing though: the first stage of processing has a fixed memory overhead no matter what you set this to, so if you're already out of memory before the areas.list file gets generated, you need to either increase your -Xmx value or make the input file smaller. no other options, bestie.

default: 512

  • --max-nodes=int — the maximum number of nodes that can live in any of the resulting files. the default is pretty conservative, so you could honestly bump it up quite a lot before you start seeing any 'map too big' messages. not a ton of experimentation has been done on this ngl. also the bigger this value is, the less memory you need during the splitting stage 🌸

default: 1600000

  • --max-threads=value — the maximum number of threads that mkgmap-splitter is allowed to use 🧵

default: 4 (auto)

  • --mixed=boolean — specify this if your input osm file has nodes, ways and relations all intermingled, or if the ids aren't strictly sorted. to boost performance, use the osmosis sort function instead 💫

default: false

  • --no-trim=boolean — don't trim the empty space off the edges of tiles. note that this option gets ignored whenever --polygon-file is used 🎀

default: false

  • --num-tiles=valuestring — a target value that's used when no split-file is given. splitting is done so that you get the number of tiles you asked for. and psst — the --max-nodes value gets ignored if you give this option.
  • --output=string — the format your output files get written in. possible values are xml, pbf, o5m, and simulate. the default is pbf, which produces the smallest file sizes. o5m is faster to write but creates around 40% larger files. and simulate is just for debugging purposes 🔍
  • --output-dir=path — the directory where splitter should write its output files. if the path you gave doesn't exist, mkgmap-splitter tries to create it. defaults to the current working directory.
  • --overlap=string — deprecated since r279 👑 with --keep-complete=false, mkgmap-splitter should include nodes outside the bounding box so that mkgmap can neatly crop exactly at the border. this parameter controls the size of that overlap. it's in map units, and a default of 2000 is used, which means about 0.04 degrees of latitude or longitude. if --keep-complete=true is active and you also give --overlap, a warning gets printed, because that combo rarely makes sense 🚩
  • --polygon-desc-file=path — an osm file (.o5m, .pbf, .osm) with named ways that describe bounding polygons, where the OSM ways have the tags name and mapid.
  • --polygon-file=path — the name of a file containing a bounding polygon in the osmosis polygon file format. mkgmap-splitter uses this file when calculating the areas. here's the whole vibe: it first calculates a grid using the given --resolution. then the input file is read and for each node, a counter is increased for the related grid area. if the input file contains a bounding box, that gets applied to the grid so that nodes outside the bounding box are ignored. next, if specified, the bounding polygon is used to zero out those grid elements outside of the bounding polygon area. and finally — if the polygon area(s) describe(s) a rectilinear area with no more than 40 vertices, mkgmap-splitter will try to create output files that fit exactly into the area. otherwise it approximates the polygon area with rectangles 📐
  • --precomp-sea=path — the name of a directory containing precompiled sea tiles. if you give this, mkgmap-splitter will use the precompiled sea tiles in the same way that mkgmap does. use this if you want to use a polygon-file or --no-trim=true and mkgmap is creating empty *.img files combined with a message starting "There is not enough room in a single garmin map for all the input data" 🌊
  • --problem-file=path — the name of a file containing ways and relations that are known to cause problems in the split process. use this option if --keep-complete is taking too much time or memory and --overlap didn't solve your problem.

syntax of the problem file:

way:<id> # comment...
rel:<id> # comment...

example:

way:2784765 # Ferry Guernsey - Jersey
  • --problem-report=path — the name of a file to write the generated problem list into, created with --keep-complete. this parameter is ignored if --keep-complete=false. you can reuse this file with the --problem-file parameter, but only do that if you're using the same values for --max-nodes and --resolution ⚠️
  • --resolution=int — the resolution of the density map produced during the first phase. a value between 1 and 24. default is 13. lowkey important: bumping the value to 14 requires four times more memory in the split phase 😭 the value gets ignored if a --split-file is given.
  • --search-limit=int — search limit in the split algo. higher values may find better splits, but they'll take longer 🐢

default: 200000

  • --split-file=path — use the previously calculated tile areas instead of calculating them from scratch. the file can be in .list or .kml format.
  • --status-freq=int — displays the amount of memory used by the JVM every --status-freq seconds. set it to 0 to disable.

default: 120

  • --stop-after=string — debugging: stop after a given program phase. can be split, gen-problem-list, or handle-problem-list. default is dist, which means execute all phases 🏁
  • --wanted-admin-level=string — specifies the lowest admin_level value of boundary relations that should be kept complete. it's used to filter boundary relations for problem-list processing. the default value 5 means that boundary relations are kept complete when the admin_level is 5 or higher (5..11). this parameter is ignored if --keep-complete=false.

default: 5

  • --write-kml=path — the name of a kml file to write the areas out to. this is in addition to areas.list, which always gets written out anyway 💖

🎀 Special options 🎀

these two are the little icons of the option world, periodt:

  • --version — if the parameter --version is found somewhere in the options, mkgmap-splitter will just print the version info and exit. the version info looks like this:
splitter 279 compiled 2013-01-12T01:45:02+0000
  • --help — if the parameter --help is found somewhere in the options, mkgmap-splitter will print a list of all known normal options together with a short help and then exit 🌈

🎀 TUNING 🎀

✨ Tuning for best performance ✨

okay so listen, bestie 💖 if you're out here using mkgmap-splitter to split large files, here's some hints that are literally gonna save your life (or at least your CPU cycles):

  • for faster processing with --keep-complete=true, convert your input file to o5m format using:
osmconvert --drop-version file.osm -o=file.o5m
  • the --drop-version option is optional, but it slims the file down to only the data that mkgmap-splitter and mkgmap actually need. it's giving "declutter" 💅
  • if you're still getting poor performance (😭), go look into splitter.log. search for the word Distributing. you might find something like this on the next line:
Processing 1502 areas in 3 passes, 501 areas at a time

which means splitter has to read the input file input three times because the --max-areas parameter was wayyyyy smaller than the number of areas. if you have enough heap, set --max-areas to a value that's higher than the number of areas, e.g. --max-areas=2048. run mkgmap-splitter again and you should find:

Processing 1502 areas in a single pass
  • more areas require more memory, no cap. so make sure mkgmap-splitter has enough heap (bump up that -Xmx parameter) so it doesn't waste a bunch of time in the garbage collector (GC) — but also keep as much memory as possible for the system's I/O caches. balance, queen 👑
  • if you have them available, use two different disks for the input file and the output directory, esp. when you use o5m format for input and output 🔥
  • if you're on mkgmap r2415 or later and disk space is not a concern, consider using --output=o5m to speed up processing. iconic behavior honestly ✨

🌸 Tuning for low memory requirements 🌸

if your machine has less than 1 GB free memory (eg. a netbook, we've all been there 🫶), you can still use mkgmap-splitter, but ngl you might have to be patient if you use the --keep-complete parameter and want to split a file like germany.osm.pbf or a larger one. if needed, reduce the number of parallel processed areas to 50 with the --max-areas parameter. and you have to use --keep-complete=false when splitting an area like Europe. periodt.

💀 NOTES 💀

  • there is no longer an upper limit on the number of areas that can be output (previously it was 255). more areas just mean potentially more passes being required over the .osm file, and hence the splitter will take longer to run. that's the tradeoff bestie 😌
  • there is no longer a limit on how many areas a way or relation can belong to (previously it was 4).

👑 SEE ALSO 👑

mkgmap(1), osmconvert(1)

and that's a wrap on the whole page, bestie!! 🌈⭐ this was part 3 of 3, footer energy: it's from mkgmap-splitter(1) and it's dated 26 January 2026 💖 go forth and split, you absolute main character 🦋💅✨

📦 where this page comes from