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.
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
-help-Help-version-license-describe-insert-import-export-delete-view-server-count-stat
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'.
kahelo handles currently four tile database formats:
rmapskahelomaverickfolder
kahelo handles currently three image formats:
jpgpngserver
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:
http://[abc].tile.opencyclemap.org/cycle/{z}/{x}/{y}.png
http://otile[1234].mqcdn.com/tiles/1.0.0/osm/{z}/{x}/{y}.jpg
In the case of these two templates, it is actually simpler to use their
aliases, respectively the symbols OpenCycleMap and
MapQuest.
Tile sets are used in all commands to describe the tiles to work on. A set of tiles is specified with a source and additional parameters. The source can be:
-track,
-tracks, -contour, -contours),
-disk),
-tiles),
-project),
-records).
The following parameters complete the specification of the tiles to take into account:
-zoom),
-radius),
-inside parameter limiting the tile set to the
tiles already inside the database given as argument of the current
command.
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
The track and contour parameters specify gpx files to generate tile images. They are used as follow:
-track-tracks-contour-contours
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:
-zoom 0-12,13,14 -radius 10,5,2)
cannot be used with projects.
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.
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
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 parameter is mandatory when using
-track and -contour options.
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
The radius parameter can also specify several values, one value for each
range or value of the -zoom parameter. For instance:
-zoom 0-12,13,14 -radius 10,5,2
This uses a radius of 10 for the zoom range 0-10, a radius of 5 for the zoom value 13, and a radius of 2 for the zoom value of 14.
-describe
-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
-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
-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
-export <database name> <tile set> -destination <database name> [-force]
Export tiles to 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
-delete <database name> <tile set>
Delete the tiles from the tile set.
-view
-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
-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:
http://127.0.0.1:80/{z}/{x}/{y}.jpg
-count
-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
-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.
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.
[database]tile_validity
-insert, -import and -export
commands. Change this value to 0 or use the -force
option to always update tiles.
commit_period
[insert]request_delay
timeout
number_of_attempts
session_max
kahelo (1 000 000 by default).
[import/export]draw_tile_limits
border_valid_color and
border_expired_color in [tiles] section
for colors.
draw_tile_width
border_valid_color in [tiles] section.
[tracks]interpolate_points
[view]max_dim
-view command.
antialias
max_dim parameter. When true,
resizing is slower but achieves better quality.
draw_upper_tiles
missing_tile_color defined in next section.
draw_tile_limits
border_valid_color and
border_expired_color in [tiles] section
for colors.
draw_tile_width
border_valid_color in [tiles] section.
draw_track
draw_points
draw_circles
-radius parameter (or default value).
interpolated_points
tracks/interpolate_points.
[tiles]jpeg_quality
background_color
missing_tile_color
border_valid_color
border_expired_color
track_color
[server]port
-server command.