Tile management for GPS maps



General Information


Command summary


Tile sets


Configuration file


General Information


kahelo is a command line application dedicated to create and manage tile databases. Tiles are the pieces of image used by slippy maps as Google Maps, Map Quest or OpenStreetMap. GPS applications as RMaps, Maverick, etc. may work off-line provided maps have been downloaded.

Some utilities already exist to define areas of interest and download tiles. kahelo is an alternative emphasizing on database management and tile set definition. It handles currently RMaps/Locus and Maverick database format.



kahelo is a Python program. As such, it can run on any platform supporting Python. Note that PIL (the Python Imaging Library) must be installed.

For MS Windows, it is additionally available as an executable file packaged in a zip file.

For Android, it can run with some limitations (no sqlite databases) under QPython.



kahelo is licensed under the MIT licence.


Links and contact




kahelo is a console program that receives information from the command line. The format of the command line is:

kahelo.py <command> <database name> [options]

Example to insert into a database the tiles from some track file:

kahelo.py -insert somedatabase -zoom 12 -track \somepath\somefile.gpx

Exporting all tiles from some database into a second one:

kahelo.py -export some_database -records -destination some_other_database

Options may be shortened if there is no ambiguities. The previous command line may be abbreviated as:

kahelo.py -exp some_database -rec -dest some_other_database

Summary of commands


All these commands may be abbreviated as long as there is no conflict with other commands or options. By default, the trace level is moderate but it can be reduced of extended by using the options -quiet or -verbose.




To be handled by kahelo, a database is described with three attributes:

These attributes are set with the -describe command, only the first one being mandatory. All the commands described bellow assume that the databases given as argument have a description file. In the contrary, an error is launched and a message reminds to describe the database.

Note that the attributes are stored in a text file which name is the one of the database with added extension '.properties'.


Database formats

kahelo handles currently four tile database formats:


Tile image formats

kahelo handles currently three image formats:


URL templates

URL templates are used to construct the URL of tile images. In this template, the {x}, {y} and {z} placeholders are replaced respectively with the x,y coordinates of the tiles to download and the desired zoom level. A tile server may be accessed through various urls differing from one character. This can be specified with a set of characters inside brackets. When downloading a tile, one of these characters are selected at random.

Some examples of url templates:


In the case of these two templates, it is actually simpler to use their aliases, respectively the symbols OpenCycleMap and MapQuest.


Tile sets


Tile sets are used in all commands to describe the tiles to work on. A set of tiles may be specified with:

Some examples of tile sets:

-track mytrack.gpx -zoom 10,12-14 -radius 1.5
-contour mycontour.gpx -zoom 18 -inside
-contours mytrack.gpx -zoom 15-18/16
-project myproject.project
-records -zoom 16 


Tracks and contours

The track and contour parameters specify gpx files to generate tile images. They are used as follow:



A project is a text file containing a list of tile set specifiers, -track(s), -contour(s), -records, -tiles, and even -project. Each one of the specifiers may have its own zoom and radius specification, or -inside parameter.

Project example:

; eurovelo6 Bratislava to Budapest
-track bratislava-budapest.gpx -zoom 10-14 -radius 2
-contour bratislava.gpx -zoom 14
-contour budapest.gpx -zoom 14

Projects are convenient to handle various gpx files in a single command. To help use them from any folder, the files appearing in the project are searched for either as absolute path, relatively to the current path, or relatively to the path of the project file.

Note that:


Database tile set

It is possible to refer to the tiles already inserted into the database by using the argument -records. The -zoom argument may be used to limit the zoom levels to work on. When it is absent, all tiles in the database are considered. Note that if a database tile set is described with a radius, this is considered as an error.

Counting all tiles in database:

kahelo -count mydatabase.db -records

Exporting tiles from zoom level 10 to level 12 to a second database:

kahelo -export mydatabase.db -records -zoom 10-12 -dest anotherdatabase.db

Note that -records refers always to the database given after the command parameter.


Tile rectangle

It is possible to define a rectangle area by using the -tiles specifier followed by the rectangle coordinates expressed in tile units ("xmin,ymin,xmax,ymax" comma separated without any space) .

For instance, the whole earth map is defined as follow at zoom level 8:

-tiles 0,0,255,255 -zoom 8


Intersection with database

In some cases, it is convenient or necessary to consider the intersection of the tile set with the tiles already in the database. This is done by using the -inside parameter.



A single zoom level, or a set of zoom levels may be given with the -zoom parameter. A set of zoom levels may be a range as in 12-15, or a list of single values or ranges separated by commas.

-zoom 12
-zoom 12,14,16
-zoom 10-14,16

Note that:


Zoom subdivision

Using contours for large zoom levels may generate too many tiles to be handled. The workaround proposed by kahelo is to generate the tiles at a lower zoom level and to subdivise these tiles at the target zoom level. This is specified as follow:

-zoom 18/16

This means that the tiles of the contour will be generated only to level 16. When processing the command, the tiles from level 16 will be subdivided up to level 18.



The radius enables to include in the tile set all tiles intersecting the circles with the given radius and centered on each point of the track or contour. It is given with the option -radius but may be omitted.

When the radius is omitted, the default value is half the width of a tile.

Note that:

-radius 1.5
-radius 0




-describe <database name> -db_format <database format> -tile_format <tile format> -url_template <url template>

This command connects kahelo to a database. It enables to give the three parameters describing a database: its format, the format of the tile images and the url template of the tile server associated with the database.

Any number of parameters may be given with this command. In any case, including when no parameters are given, the current set of parameters associated with the database is displayed.


-insert <database name> <tile set> [-force]

Download tiles from the server associated to the database and inserts them in the database. If the -force option is present, all tiles from the set are downloaded and inserted, otherwise only the tiles older than the expiry date are considered.

The expiry date is stored in the configuration file.


-import <database name> <tile set> -source <database name> [-force]

Import tiles from another database. See the -insert command for the description of the -force option.


-export <database name> <tile set> -destination <database name> [-force]

Export tiles from another database. See the -insert command for the description of the -force option. Note that -export is equivalent to -import with database arguments swapped except when using -records. In that case, the tile set is always constructed from the first database argument.


-delete <database name> <tile set>

Delete the tiles from the tile set.


-view <database name> <tile set> [-image <image name>]

Make an image with tiles from the tile set. If the output image is not given, the image is displayed in the default viewer.


-server <database name>

Starts a tile server with the tiles from the database given as argument. The default port is 80 and is defined in the configuration file. With this port number, the url template for the server is:{z}/{x}/{y}.jpg


-count <database name> <tile set>

Count the number of tiles in the database for the tile set specified in the command line. The following information is delivered:


-stat <database name> <tile set>

Return statistics about size of tiles in the database, as well as the coordinates of the rectangle bounding the area covered by the tiles for each zoom level. These coordonates are given in tile coordinates and degrees.


Configuration file


Some parameters are not accessible on the command line but by editing a configuration file, named kahelo.config and created at the first utilisation. They concern more advanced settings.


The number of days tiles are considered valid (10 years as a default). While valid, tiles are not replaced by the -insert, -import and -export commands. Change this value to 0 or use the -force option to always update tiles.
Number of tiles inserted before the database is actually updated (sqlite databases).


Minimum delay in seconds between two requests to the tile server (0.1 second by default).
Time after which a request to server without a response is abandoned (3 seconds by default).
Total number of attempts to get a tile from server (3 by default).
Maximum number of tiles inserted during one run of kahelo (1 000 000 by default).


Enables to draw the contour of the tiles. See border_valid_color and border_expired_color in [tiles] section for colors.
Enables to draw the width of the tiles in kilometer. Same color as border_valid_color in [tiles] section.


Maximum size of the image created by the -view command.
This parameter applies only when tiles have to be resized according to the value of the max_dim parameter. When true, resizing is slower but achieves better quality.
This parameter controls the way missing tiles are displayed. If true, the missing tiles are drawn using the tiles at lower zoom levels. Otherwise, the mising tiles are filled with the missing_tile_color defined in next section.
Enables to draw the contour of the tiles. See border_valid_color and border_expired_color in [tiles] section for colors.
Enables to draw the width of the tiles in kilometer. Same color as border_valid_color in [tiles] section.
Draw the gpx track.
Draw the points of the gpx track.
Draw a circle centered at each point of the gpx track with radius given by the -radius parameter (or default value).


JPEG quality factor used when converting tile images to JPEG format. 1 is very poor, 100 is lossless. 85 is a good trade-off between quality and compression.
Specifies the color of the background of the image (part of the image without any tile from the tile set). Given as red, green, blue values in the range 0 to 255.
Specifies the color replacing missing tiles. Given as red, green, blue values in the range 0 to 255.
Specifies the color for drawing the border of valid tiles. Given as red, green, blue, alpha values in the range 0 to 255.
Specifies the color for drawing the border of expired tiles. Given as red, green, blue, alpha values in the range 0 to 255.
Specifies the color for drawing the track. Given as red, green, blue values in the range 0 to 255 followed by the width of the line in pixels.


Specifies the port to access to the tile server started with the -server command.