mapmaker is a simple script to generate map images for "Slippy Tile" maps.
Map tiles are downloaded from services such as OpenStreetMap and are combined
into a single image.
Use the installation script:
$ python setup.py install
Or install using pip:
$ pip install mapmaker
Use mapmaker --help to show a detailed list of options.
This will create a file map.png in the current directory. The map will
cover the bounding box specified with two pairs of lat/lon coordinates:
$ mapmaker 47.44,10.95 47.37,11.13
One can also specify a center point and a radius:
$ mapmaker 63.0695,-151.0074 100km
If the coordinates start with a negative value, use -- to indicate the
end of command line flags:
$ mapmaker -- -32.653197,-70.0112 100km
Coordinates can also be specified in DMS format:
$ mapmaker "63°4'10.2'' N, 151°0'26.64'' W" 4km
Use a single quote for minutes (')
and two single quotes ('') for seconds.
Note the quotes around the command line argument.
You can also specify the output file (default is map.png):
$ mapmaker 63.0695,-151.0074 100km denali.png
Specify the zoom level with the --zoom flag. The default is 8.
Higher values mean more detail and result in larger map images.
$ mapmaker 63.0695,-151.0074 100km --zoom 12
Use --style to control the look of the map:
$ mapmaker 63.0695,-151.0074 100km --style human
To control the resulting image format, use --aspect:
$ mapmaker 45.83,6.88 100km --aspect 16:9
The aspect ratio is given in the format W:H (e.g. 4:3 or 19:9).
The resulting map image will contain the given bounding box (or point w/ radius)
and max be extended to North/South or East/West to match the aspect ratio.
Note that the resolution of the image depends on the --zoom factor.
Set a headline with --title, specify optional PLACEMENT, COLOR
and BORDER followed by the title string.
The title will be added to the Margin Area and will force a margin that is
large enough to accommodate the title.
| PLACEMENT: | one of the cardinal directions e.g. NW, NNW, N, NNE, NE, .... |
|---|---|
| BORDER: | a single integer value for the border width in in pixels. |
| COLOR: | RGB(A) tuple as a comma separated string, e.g. "255,0,0". |
| BACKGROUND: | RGB(A) tuple as a comma separated string, e.g. "255,0,0". |
Colors can also be specified as hex values, e.g. #ff0000
or #ff000080 (with opacity).
$ mapmaker 45.83,6.88 100km --title My Map
$ mapmaker 45.83,6.88 100km --title NNW My Map
$ mapmaker 45.83,6.88 100km --title NNW 5 My Map
$ mapmaker 45.83,6.88 100km --title NNW 5 255,0,0 My Map
$ mapmaker 45.83,6.88 100km --title NNW 5 255,0,0 0,0,255 My Map
Use --comment to add a comment in small print. Arguments are the same
as for --title:
$ mapmaker 45.83,6.88 100km --comment My Comment
$ mapmaker 45.83,6.88 100km --comment SE 200,200,200 My Comment
Use --margin and --background to apply a border around the map.
Note that some decoration arguments will automatically add a margin area.
margin is given in pixels as a single value (all sides),
a pair of two values (top/bottom and left/right)
or as four separate values for top, right, bottom, left (clockwise).
$ mapmaker 45.83,6.88 100km --margin 50
$ mapmaker 45.83,6.88 100km --margin 20 40
$ mapmaker 45.83,6.88 100km --margin 10 15 20 15
The color of the margin area can be controlled with --background.
background is given as a comma separated RGB(A) value:
$ mapmaker 45.83,6.88 100km --margin 10 --background 200,200,200
$ mapmaker 45.83,6.88 100km --margin 10 --background 200,200,200,128
The --frame argument adds a border around the map content, that is between
the map and the (optional) margin area.
frame has up to four optional parameters:
WIDTH: | The width in pixels, e.g. "8". |
|---|---|
COLOR: | The main color as an RGB(A) value, e.g. "0,0,0" (black). |
ALT_COLOR: | The secondary color as an RGB(A) value, e.g. "255,255,255" (white). |
STYLE: | The style, either "solid" or "coordinates". |
Arguments can be supplied in any order.
ALT_COLOR is only needed for styles that feature alternating colors,
if two RGB(A) values are specified, the second is considered the ALT_COLOR.
All arguments are optional and if --frame is specified without arguments,
a default frame will be drawn.
Examples:
$ mapmaker 45.83,6.88 100km --frame
$ mapmaker 45.83,6.88 100km --frame 12
$ mapmaker 45.83,6.88 100km --frame 12 255,0,0
$ mapmaker 45.83,6.88 100km --frame 12 255,0,0 0,0,255 coordinates
$ mapmaker 45.83,6.88 100km --frame coordinates
Use --scale to show a scale bar on the map.
Optional arguments for scale are:
PLACEMENT: | Where to place the scale, must be one of the map areas (e.g "SW"). |
|---|---|
WIDTH: | The width of the scale bar in pixels (e.g. "2"). |
COLOR: | The color to use for the scale bar an label, e.g. "0,0,0". |
LABEL: | The label style, either default or nolabel. |
UNDERLAY: | Draw a partly transparent box below the scale bar to improve its readability against the map content. |
The label shows the size of the scale in meters or kilometers.
Examples:
$ mapmaker 45.83,6.88 100km --scale
$ mapmaker 45.83,6.88 100km --scale SE
$ mapmaker 45.83,6.88 100km --scale 1
$ mapmaker 45.83,6.88 100km --scale 120,120,120
$ mapmaker 45.83,6.88 100km --scale nolabel
$ mapmaker 45.83,6.88 100km --scale full
$ mapmaker 45.83,6.88 100km --scale SE 1 120,120,120 nolabel full
The --geojson option can be used to draw GeoJSON
objects onto the map.
The GeoJSON can contain additional attributes to control the color, line width,
etc. The additional attributes can be part of a Geometry or part of the
properties attribute of a parent Feature.
Have a look hat the module documentation to see which special attributes are
supported.
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [12.594474, 55.691438]
},
"properties": {
"symbol": "square",
"color": [10, 147, 150],
"size": 12
}
}You can also use any Geometry object directly:
{
"type": "Polygon",
"coordinates": [
[8.612316, 47.680632],
[8.612316, 47.676327],
[8.617423, 47.676327],
[8.617423, 47.680632]
]
"color": [60, 9, 108],
"fill": [60, 9, 108, 120]
}The --geojson option supports a path to a JSON file or a JSON formatted
string.
Use the --gallery flag to render a set of maps, one for each available style.
In this case, you specify an output directory instead of a file (default is the
current directory).
This flag ignores the --style parameter.
The configuration file is located at ~/.config/mapmaker/config.ini
You can specify additional map styles like this:
# ~/.config/mapmaker/config.ini
[service.osm]
osm = https://tile.openstreetmap.org/{z}/{x}/{y}.png
[service.opentopo]
subdomains = abc
topo = https://{s}.tile.opentopomap.org/{z}/{x}/{y}.pngWhere osm or topo are the names of the style (as used in the
--style flag) and the URL is the URL pattern for downloading tiles.
Section names can be chosen freely but have to start with service..
Each section may contain the following reserved entries:
[service.example]
tile_size = 512
api_key = my-secret-api-key
subdomains = abcdefAny other entries are expected to be key/value pairs with URL patterns.
If no tile_size is configured, the default size (256px) is used.
The URL pattern must contain three variables:
| z: | zoom level |
|---|---|
| x: | X-coordinate of the tile |
| y: | Y-coordinate of the tile |
See for example https://wiki.openstreetmap.org/wiki/Tiles.
The URL may contain additional placeholders for an API Key (see below) and a subdomain:
topo = https://{s}.tile.opentopomap.org/{z}/{x}/{y}.png
^^^
atlas = https://tile.thunderforest.com/atlas/{z}/{x}/{y}.png?apikey={api}
^^^
Authorization is needed for the following services:
| Domain | Type | Homepage |
|---|---|---|
| tile.thunderforest.com | API Key | https://www.thunderforest.com/ |
| maps.geoapify.com | API Key | https://www.geoapify.com/ |
| api.mapbox.com | Token | https://mapbox.com/ |
Most services offer a free plan for limited/non-commercial use. Check out the URL from the table above.
Once you have registered, place your API Keys in a config file like this:
# ~/.config/mapmaker/config.ini
[service.thunderforest]
api_key = YOUR_API_KEY
[service.geoapify]
api_key = YOUR_API_KEY
[service.mapbox]
api_key = YOUR_API_KEYWhere [service.xxx] is the config section which defines the URLs for this
service.