README.md

PaperMap

PaperMap is a Python package and CLI for creating ready-to-print paper maps.

Installation

From PyPI

PaperMap is available on PyPI.

As a package

For use as a package, install PaperMap with pip or your package manager of choice:

pip install papermap

As a CLI tool

For use as a CLI tool, we recommend installing PaperMap with pipx:

pipx install papermap

From source

If you'd like, you can also install PaperMap from source (with flit):

git clone https://github.com/sgraaf/papermap.git
cd papermap
python3 -m pip install flit
flit install

Documentation

Check out the PaperMap documentation for the User's Guide and API Reference.

Usage

PaperMap can be used both in your own applications as a package, as well as a CLI tool.

As a package

Using the default values, the example below will create an portrait-oriented, A4-sized map of Bangkok at scale 1:25000:

>>> from papermap import PaperMap
>>> pm = PaperMap(13.75889, 100.49722)
>>> pm.render()
>>> pm.save("Bangkok.pdf")

You can easily customize the generated map by changing the tile server, size, orientation, etc. For an exhaustive list of all available options, please see the API Reference.

For example, the example below will create a landscape-oriented, A3-sized map of Madrid using the Stamen Terrain tile server, with a UTM grid overlay, at scale 1:50000:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=40.416775,
...     lon=-3.703790,
...     tile_server="Stamen Terrain",
...     size="a3",
...     landscape=True,
...     scale=50_000,
...     add_grid=True,
>>> )
>>> pm.render()
>>> pm.save("Madrid.pdf")

As a CLI tool

Similarly, using the default values, the example below will create an portrait-oriented, A4-sized map of Bangkok at scale 1:25000:

$ papermap latlon -- 13.75889 100.49722 Bangkok.pdf

As with the package, maps generated through the CLI are also highly customizable. Please see the CLI Reference for an exhaustive list of all available options.

The example below will create a landscape-oriented, A3-sized map of Madrid using the Stamen Terrain tile server, with a UTM grid overlay, at scale 1:50000:

$ papermap latlon \
    --tile-server "Stamen Terrain" \
    --size a3 \
    --landscape \
    --scale 50000 \
    --grid \
    -- 40.416775 -3.703790 Madrid.pdf