mapmaker 1.6.0

Create map images from slippy map tiles.

Map Maker

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.

Installation

Use the installation script:

$ python setup.py install

Or install using pip:

$ pip install mapmaker

Command Line Usage

Use mapmaker --help to show a detailed list of options.

Basic Usage

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

Additional Options

Specify the zoom level with the --zoom flag. The default is 8. Higher values mean more detail and result in larger map images.

$ mapmaker --zoom 12 63.0695,-151.0074 100km

Use --style to control the look of the map:

$ mapmaker --style human 63.0695,-151.0074 100km

Use the --shading flag to overlay a hillshading layer over the map image. Note that hillshading is not available for all regions.

$ mapmaker --shading 45.83,6.88 100km

Note that some map styles already come with hillshading.

To control the resulting image format, use --aspect:

$ mapmaker --aspect 16:9 45.83,6.88 100km

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.

Decorations

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”.

$ mapmaker --title My Map -- 45.83,6.88 100km
$ mapmaker --title NNW My Map -- 45.83,6.88 100km
$ mapmaker --title NNW 5 My Map -- 45.83,6.88 100km
$ mapmaker --title NNW 5 255,0,0 My Map -- 45.83,6.88 100km
$ mapmaker --title NNW 5 255,0,0 0,0,255 My Map -- 45.83,6.88 100km

Note the ``–`` to indicate the end of non-positional arguments.

Use --comment to add a comment in small print. Arguments are the same as for --title:

$ mapmaker --comment My Comment 45.83,6.88 100km
$ mapmaker --comment SE 200,200,200 My Comment 45.83,6.88 100km

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 --margin 50 45.83,6.88 100km
$ mapmaker --margin 20 40 45.83,6.88 100km
$ mapmaker --margin 10 15 20 15 45.83,6.88 100km

background is given as a comma separated RGB(A) value:

$ mapmaker --background 200,200,200 45.83,6.88 100km
$ mapmaker --background 200,200,200,128 45.83,6.88 100km

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 --frame 45.83,6.88 100km
$ mapmaker --frame 12 45.83,6.88 100km
$ mapmaker --frame 12 255,0,0 45.83,6.88 100km
$ mapmaker --frame 12 255,0,0 0,0,255 coordinates 45.83,6.88 100km
$ mapmaker --frame coordinates 45.83,6.88 100km

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.

The label shows the size of the scale in meters or kilometers.

Examples:

$ mapmaker --scale -- 45.83,6.88 100km
$ mapmaker --scale SE -- 45.83,6.88 100km
$ mapmaker --scale 1 -- 45.83,6.88 100km
$ mapmaker --scale 120,120,120 -- 45.83,6.88 100km
$ mapmaker --scale nolabel -- 45.83,6.88 100km
$ mapmaker --scale SE 1 120,120,120 nolabel -- 45.83,6.88 100km

GeoJSON

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.

Create a Gallery

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.

Configuration

The configuration file is located at ~/.config/mapmaker/config.ini

Styles (Tile Servers)

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}.png

Where 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 = abcdef

Any 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

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_KEY

Where [service.xxx] is the config section which defines the URLs for this service.