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:
.. code:: shell-session
$ python setup.py install
Or install using pip:
.. code:: shell-session
$ 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:
.. code:: shell-session
$ mapmaker 47.44,10.95 47.37,11.13
One can also specify a center point and a radius:
.. code:: shell-session
$ mapmaker 63.0695,-151.0074 100km
If the coordinates start with a negative value, use ``--`` to indicate the
end of command line flags:
.. code:: shell-session
$ mapmaker -- -32.653197,-70.0112 100km
Coordinates can also be specified in DMS format:
.. code:: shell-session
$ 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*):
.. code:: shell-session
$ 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.
.. code:: shell-session
$ mapmaker --zoom 12 63.0695,-151.0074 100km
Use ``--style`` to control the **look** of the map:
.. code:: shell-session
$ 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.
.. code:: shell-session
$ mapmaker --shading 45.83,6.88 100km
Note that some map styles already come with hillshading.
To control the resulting image format, use ``--aspect``:
.. code:: shell-session
$ 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".
.. code:: shell-session
$ 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``:
.. code:: shell-session
$ 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).
.. code:: shell-session
$ 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:
.. code:: shell-session
$ 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:
.. code:: shell-session
$ 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:
.. code:: shell-session
$ 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 <https://geojson.org/>`_
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.
.. code:: json
{
"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:
.. code:: json
{
"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:
.. code:: ini
# ~/.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:
.. code:: ini
[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:
.. code:: ini
# ~/.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.
Raw data
{
"_id": null,
"home_page": "http://github.com/akeil/mapmaker",
"name": "mapmaker",
"maintainer": "Alexander Keil",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "osm,openstreetmap,tiles,map,image,cli",
"author": "Alexander Keil",
"author_email": "alex@akeil.net",
"download_url": "https://files.pythonhosted.org/packages/ee/c7/2e050c21b385c2389993297aa3c660b6a28ef9987678f7329084ff966f02/mapmaker-1.6.0.tar.gz",
"platform": null,
"description": "Map Maker\n#########\n``mapmaker`` is a simple script to generate map images for \"Slippy Tile\" maps.\nMap tiles are downloaded from services such as OpenStreetMap and are combined\ninto a single image.\n\n\nInstallation\n============\nUse the installation script:\n\n.. code:: shell-session\n\n $ python setup.py install\n\nOr install using pip:\n\n.. code:: shell-session\n\n $ pip install mapmaker\n\n\nCommand Line Usage\n==================\nUse ``mapmaker --help`` to show a detailed list of options.\n\n\nBasic Usage\n-----------\nThis will create a file ``map.png`` in the current directory. The map will\ncover the bounding box specified with two pairs of lat/lon coordinates:\n\n.. code:: shell-session\n\n $ mapmaker 47.44,10.95 47.37,11.13\n\nOne can also specify a center point and a radius:\n\n.. code:: shell-session\n\n $ mapmaker 63.0695,-151.0074 100km\n\nIf the coordinates start with a negative value, use ``--`` to indicate the\nend of command line flags:\n\n.. code:: shell-session\n\n $ mapmaker -- -32.653197,-70.0112 100km\n\nCoordinates can also be specified in DMS format:\n\n.. code:: shell-session\n\n $ mapmaker \"63\u00b04'10.2'' N, 151\u00b00'26.64'' W\" 4km\n\nUse a single quote for minutes (``'``)\nand two single quotes (``''``) for seconds.\nNote the quotes around the command line argument.\n\n\nYou can also specify the **output file** (default is *map.png*):\n\n.. code:: shell-session\n\n $ mapmaker 63.0695,-151.0074 100km denali.png\n\n\nAdditional Options\n------------------\nSpecify the **zoom level** with the ``--zoom`` flag. The default is 8.\nHigher values mean more detail and result in larger map images.\n\n.. code:: shell-session\n\n $ mapmaker --zoom 12 63.0695,-151.0074 100km\n\nUse ``--style`` to control the **look** of the map:\n\n.. code:: shell-session\n\n $ mapmaker --style human 63.0695,-151.0074 100km\n\nUse the ``--shading`` flag to overlay a hillshading layer over the map image.\nNote that hillshading is not available for all regions.\n\n.. code:: shell-session\n\n $ mapmaker --shading 45.83,6.88 100km\n\nNote that some map styles already come with hillshading.\n\nTo control the resulting image format, use ``--aspect``:\n\n.. code:: shell-session\n\n $ mapmaker --aspect 16:9 45.83,6.88 100km\n\nThe aspect ratio is given in the format ``W:H`` (e.g. 4:3 or 19:9).\nThe resulting map image will contain the given bounding box (or point w/ radius)\nand max be extended to North/South or East/West to match the aspect ratio.\nNote that the *resolution* of the image depends on the ``--zoom`` factor.\n\n\nDecorations\n-----------\nSet a headline with ``--title``, specify optional ``PLACEMENT``, ``COLOR``\nand ``BORDER`` followed by the title string.\nThe title will be added to the *Margin Area* and will force a margin that is\nlarge enough to accommodate the title.\n\n:PLACEMENT: one of the cardinal directions e.g. ``NW, NNW, N, NNE, NE, ...``.\n:BORDER: a single integer value for the border width in in pixels.\n:COLOR: RGB(A) tuple as a comma separated string, e.g. \"255,0,0\".\n:BACKGROUND: RGB(A) tuple as a comma separated string, e.g. \"255,0,0\".\n\n.. code:: shell-session\n\n $ mapmaker --title My Map -- 45.83,6.88 100km\n $ mapmaker --title NNW My Map -- 45.83,6.88 100km\n $ mapmaker --title NNW 5 My Map -- 45.83,6.88 100km\n $ mapmaker --title NNW 5 255,0,0 My Map -- 45.83,6.88 100km\n $ mapmaker --title NNW 5 255,0,0 0,0,255 My Map -- 45.83,6.88 100km\n\n*Note the ``--`` to indicate the end of non-positional arguments.*\n\nUse ``--comment`` to add a comment in small print. Arguments are the same\nas for ``--title``:\n\n.. code:: shell-session\n\n $ mapmaker --comment My Comment 45.83,6.88 100km\n $ mapmaker --comment SE 200,200,200 My Comment 45.83,6.88 100km\n\nUse ``--margin`` and ``--background`` to apply a border around the map.\nNote that some decoration arguments will automatically add a margin area.\n\n``margin`` is given in pixels as a single value (all sides),\na pair of two values (top/bottom and left/right)\nor as four separate values for top, right, bottom, left (clockwise).\n\n.. code:: shell-session\n\n $ mapmaker --margin 50 45.83,6.88 100km\n $ mapmaker --margin 20 40 45.83,6.88 100km\n $ mapmaker --margin 10 15 20 15 45.83,6.88 100km\n\n``background`` is given as a comma separated RGB(A) value:\n\n.. code:: shell-session\n\n $ mapmaker --background 200,200,200 45.83,6.88 100km\n $ mapmaker --background 200,200,200,128 45.83,6.88 100km\n\nThe ``--frame`` argument adds a border around the map content, that is between\nthe map and the (optional) margin area.\n``frame`` has up to four optional parameters:\n\n:``WIDTH``: The width in pixels, e.g. \"8\".\n:``COLOR``: The main color as an RGB(A) value, e.g. \"0,0,0\" (black).\n:``ALT_COLOR``: The secondary color as an RGB(A) value, e.g. \"255,255,255\" (white).\n:``STYLE``: The style, either \"solid\" or \"coordinates\".\n\nArguments can be supplied in any order.\n``ALT_COLOR`` is only needed for styles that feature alternating colors,\nif two RGB(A) values are specified, the second is considered the ``ALT_COLOR``.\n\nAll arguments are optional and if ``--frame`` is specified without arguments,\na default frame will be drawn.\n\nExamples:\n\n.. code:: shell-session\n\n $ mapmaker --frame 45.83,6.88 100km\n $ mapmaker --frame 12 45.83,6.88 100km\n $ mapmaker --frame 12 255,0,0 45.83,6.88 100km\n $ mapmaker --frame 12 255,0,0 0,0,255 coordinates 45.83,6.88 100km\n $ mapmaker --frame coordinates 45.83,6.88 100km\n\nUse ``--scale`` to show a scale bar on the map.\nOptional arguments for scale are:\n\n:``PLACEMENT``: Where to place the scale, must be one of the map areas\n (e.g \"SW\").\n:``WIDTH``: The width of the scale bar in pixels (e.g. \"2\").\n:``COLOR``: The color to use for the scale bar an label, e.g. \"0,0,0\".\n:``LABEL``: The label style, either ``default`` or ``nolabel``.\n\nThe label shows the size of the scale in meters or kilometers.\n\nExamples:\n\n.. code:: shell-session\n\n $ mapmaker --scale -- 45.83,6.88 100km\n $ mapmaker --scale SE -- 45.83,6.88 100km\n $ mapmaker --scale 1 -- 45.83,6.88 100km\n $ mapmaker --scale 120,120,120 -- 45.83,6.88 100km\n $ mapmaker --scale nolabel -- 45.83,6.88 100km\n $ mapmaker --scale SE 1 120,120,120 nolabel -- 45.83,6.88 100km\n\n\nGeoJSON\n-------\nThe ``--geojson`` option can be used to draw `GeoJSON <https://geojson.org/>`_\nobjects onto the map.\n\nThe GeoJSON can contain additional attributes to control the color, line width,\netc. The additional attributes can be part of a *Geometry* or part of the\n``properties`` attribute of a parent *Feature*.\nHave a look hat the module documentation to see which special attributes are\nsupported.\n\n.. code:: json\n\n {\n \"type\": \"Feature\",\n \"geometry\": {\n \"type\": \"Point\",\n \"coordinates\": [12.594474, 55.691438]\n },\n \"properties\": {\n \"symbol\": \"square\",\n \"color\": [10, 147, 150],\n \"size\": 12\n }\n }\n\nYou can also use any *Geometry* object directly:\n\n.. code:: json\n\n {\n \"type\": \"Polygon\",\n \"coordinates\": [\n [8.612316, 47.680632],\n [8.612316, 47.676327],\n [8.617423, 47.676327],\n [8.617423, 47.680632]\n ]\n \"color\": [60, 9, 108],\n \"fill\": [60, 9, 108, 120]\n }\n\nThe ``--geojson`` option supports a path to a JSON file or a JSON formatted\nstring.\n\n\nCreate a Gallery\n----------------\nUse the ``--gallery`` flag to render a set of maps, one for each available style.\nIn this case, you specify an output directory instead of a file (default is the\ncurrent directory).\nThis flag ignores the ``--style`` parameter.\n\n\nConfiguration\n#############\nThe configuration file is located at ``~/.config/mapmaker/config.ini``\n\n\nStyles (Tile Servers)\n=====================\nYou can specify additional map styles like this:\n\n.. code:: ini\n\n # ~/.config/mapmaker/config.ini\n\n [service.osm]\n osm = https://tile.openstreetmap.org/{z}/{x}/{y}.png\n\n [service.opentopo]\n subdomains = abc\n topo = https://{s}.tile.opentopomap.org/{z}/{x}/{y}.png\n\nWhere ``osm`` or ``topo`` are the names of the style (as used in the\n``--style`` flag) and the URL is the URL pattern for downloading tiles.\n\nSection names can be chosen freely but have to start with ``service.``.\nEach section may contain the following reserved entries:\n\n.. code:: ini\n\n [service.example]\n tile_size = 512\n api_key = my-secret-api-key\n subdomains = abcdef\n\nAny other entries are expected to be key/value pairs with URL patterns.\nIf no ``tile_size`` is configured, the default size (``256px``) is used.\n\nThe URL pattern **must** contain three variables:\n\n:z: zoom level\n:x: X-coordinate of the tile\n:y: Y-coordinate of the tile\n\nSee for example https://wiki.openstreetmap.org/wiki/Tiles.\n\nThe URL may contain additional placeholders for an API Key (see below)\nand a subdomain::\n\n topo = https://{s}.tile.opentopomap.org/{z}/{x}/{y}.png\n ^^^\n atlas = https://tile.thunderforest.com/atlas/{z}/{x}/{y}.png?apikey={api}\n ^^^\n\n\nAuthorization\n=============\nAuthorization is needed for the following services:\n\n======================= ======= ======================================\nDomain Type Homepage\n======================= ======= ======================================\ntile.thunderforest.com API Key https://www.thunderforest.com/\nmaps.geoapify.com API Key https://www.geoapify.com/\napi.mapbox.com Token https://mapbox.com/\n======================= ======= ======================================\n\nMost services offer a free plan for limited/non-commercial use. Check out the\nURL from the table above.\n\nOnce you have registered, place your API Keys in a config file like this:\n\n.. code:: ini\n\n # ~/.config/mapmaker/config.ini\n\n [service.thunderforest]\n api_key = YOUR_API_KEY\n\n [service.geoapify]\n api_key = YOUR_API_KEY\n\n [service.mapbox]\n api_key = YOUR_API_KEY\n\nWhere ``[service.xxx]`` is the config section which defines the URLs for this\nservice.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Create map images from slippy map tiles.",
"version": "1.6.0",
"project_urls": {
"Bug Reports": "http://github.com/akeil/mapmaker/issues",
"Homepage": "http://github.com/akeil/mapmaker",
"Source": "http://github.com/akeil/mapmaker"
},
"split_keywords": [
"osm",
"openstreetmap",
"tiles",
"map",
"image",
"cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a2669aee2dac4e0f85a57a1e3969b00344e65a96231fd8769ee7b06e90e54fb4",
"md5": "bc86a7bcdf760593ba90095773699e68",
"sha256": "89e38a28e6aa92b5bcc548bdc5e91d41b1b25d1a6e0be0bfdc3a65cabc8689b2"
},
"downloads": -1,
"filename": "mapmaker-1.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bc86a7bcdf760593ba90095773699e68",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 48167,
"upload_time": "2023-11-05T11:35:16",
"upload_time_iso_8601": "2023-11-05T11:35:16.366561Z",
"url": "https://files.pythonhosted.org/packages/a2/66/9aee2dac4e0f85a57a1e3969b00344e65a96231fd8769ee7b06e90e54fb4/mapmaker-1.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eec72e050c21b385c2389993297aa3c660b6a28ef9987678f7329084ff966f02",
"md5": "db16559e9efd3ffed68647665ef3f9ef",
"sha256": "89387cf448ffaad4784544746feb2e37c6745e184da349dba9eb24b2e21357bc"
},
"downloads": -1,
"filename": "mapmaker-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "db16559e9efd3ffed68647665ef3f9ef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 61862,
"upload_time": "2023-11-05T11:35:18",
"upload_time_iso_8601": "2023-11-05T11:35:18.316762Z",
"url": "https://files.pythonhosted.org/packages/ee/c7/2e050c21b385c2389993297aa3c660b6a28ef9987678f7329084ff966f02/mapmaker-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-05 11:35:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "akeil",
"github_project": "mapmaker",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"tox": true,
"lcname": "mapmaker"
}
JSON
