Usage¶

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

As a Library¶

Basic Usage¶

Create a simple portrait-oriented, A4-sized map at scale 1:25000:

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

Custom Size and Orientation¶

Create a landscape-oriented, A3-sized map with grid overlay:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=40.416775,
...     lon=-3.703790,  # Madrid, Spain
...     tile_provider_key="stadia-stamenterrain",
...     size="a3",
...     landscape=True,
...     scale=50_000,
...     add_grid=True,
... )
>>> pm.render()
>>> pm.save("Madrid.pdf")

Satellite Imagery¶

Create a map using satellite imagery:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=51.5074,
...     lon=-0.1278,  # London, UK
...     tile_provider_key="esri-worldimagery",
...     size="a4",
...     scale=10_000,
... )
>>> pm.render()
>>> pm.save("London_Satellite.pdf")

Topographic Maps¶

Create a topographic map for hiking:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=46.5197,
...     lon=7.9577,  # Mürren, Switzerland
...     tile_provider_key="opentopomap",
...     size="a3",
...     landscape=True,
...     scale=25_000,
...     add_grid=True,
...     grid_size=500,  # 500m grid for easier navigation
... )
>>> pm.render()
>>> pm.save("Murren_Topo.pdf")

High-Resolution Printing¶

Create a high-resolution map for professional printing:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=35.6762,
...     lon=139.6503,  # Tokyo, Japan
...     tile_provider_key="openstreetmap",
...     size="a0",  # Large format
...     landscape=True,
...     scale=15_000,
...     dpi=600,  # High resolution
...     add_grid=True,
... )
>>> pm.render()
>>> pm.save("Tokyo_HighRes.pdf")

Using UTM Coordinates¶

Create a map using UTM coordinates instead of latitude/longitude:

>>> from papermap import PaperMap
>>> pm = PaperMap.from_utm(
...     easting=500000,
...     northing=4649776,
...     zone=30,
...     hemisphere="N",  # Northern hemisphere
...     tile_provider_key="openstreetmap",
...     size="a4",
...     scale=25_000,
...     add_grid=True,
... )
>>> pm.render()
>>> pm.save("UTM_Map.pdf")

Custom Margins¶

Create a map with custom margins for binding:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=-33.8688,
...     lon=151.2093,  # Sydney, Australia
...     tile_provider_key="openstreetmap",
...     size="letter",
...     margin_left=20,  # Extra margin for binding
...     margin_top=10,
...     margin_right=10,
...     margin_bottom=10,
...     scale=20_000,
... )
>>> pm.render()
>>> pm.save("Sydney_Binding.pdf")

Using API Keys¶

Some tile providers require API keys. Here’s how to use them:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=37.7749,
...     lon=-122.4194,  # San Francisco, USA
...     tile_provider_key="thunderforest-outdoors",
...     api_key="your_api_key_here",  # Get from thunderforest.com
...     size="a4",
...     landscape=True,
...     scale=25_000,
...     add_grid=True,
... )
>>> pm.render()
>>> pm.save("SF_Outdoors.pdf")

Adding Features (i.e., Markers, Lines and Polygons)¶

Overlay GeoJSON-style geometries (points, lines, polygons) on top of the base map. Features are styled per call, rendered above the base map but below the grid, and clipped to the map area. You can also add a raw GeoJSON dict (or any object implementing the __geo_interface__ protocol) via add_geojson().

>>> from papermap import PaperMap
>>> pm = PaperMap(lat=40.7128, lon=-74.0060, scale=25_000)
>>> # A red dot at the map centre.
>>> pm.add_circle_marker(40.7128, -74.0060, radius=3, fill_color="#f00")
>>> # A blue route.
>>> pm.add_line(
...     [(40.7100, -74.0100), (40.7150, -74.0050), (40.7200, -74.0000)],
...     stroke_color="#00f",
...     stroke_width=1.0
... )
>>> # A semi-transparent green region from a GeoJSON Polygon.
>>> pm.add_geojson(
...     {
...         "type": "Polygon",
...         "coordinates": [
...             [
...                 [-74.020, 40.710],
...                 [-74.000, 40.710],
...                 [-74.000, 40.720],
...                 [-74.020, 40.720],
...                 [-74.020, 40.710]
...             ]
...         ]
...     },
...     style={"fill_color": "#0f0", "opacity": 0.3}
... )
>>> pm.render()
>>> pm.save("NYC_Annotated.pdf")

Creating a Map From Features¶

To fit the map around features you already have, use PaperMap.from_features(). It centres the map on the features’ bounding box and pre-populates them so they will be drawn on render(). PaperMap.from_geojson() and PaperMap.from_gpx() do the same for a GeoJSON file/dict or a GPX file (or any object exposing __geo_interface__, such as a gpx.GPX instance). GeoJSON Point/MultiPoint become CircleMarker, LineString/MultiLineString become Line, and Polygon/MultiPolygon become Polygon; GPX waypoints become circle markers, routes become lines, and each segment of each track becomes its own line. An optional style dict provides default styling for every parsed feature, overridden by per-feature simplestyle-spec properties.

Reading GPX files from disk requires the optional gpx package; install it via pip install papermap[gpx].

>>> from papermap import PaperMap
>>> from papermap.features import CircleMarker, Line
>>> pm = PaperMap.from_features(
...     CircleMarker(40.7484, -73.9857, fill_color="#f00"),  # Empire State Building
...     CircleMarker(40.7128, -74.0060, fill_color="#f00"),  # NYC City Hall
...     Line(
...         [(40.7484, -73.9857), (40.7128, -74.0060)],
...         stroke_color="#00f",
...         stroke_width=1.0,
...     ),
...     scale=25_000,
... )
>>> pm.render()
>>> pm.save("NYC_Landmarks.pdf")

Auto-scaling to Features¶

Pass auto_scale=True to from_features(), from_geojson(), or from_gpx() to skip picking a scale by hand: the scale is computed so the features fit within the printable area, then snapped up to the nearest common cartographic scale (1:1 000, 1:2 500, 1:5 000, 1:10 000, 1:25 000, 1:50 000, …). Use padding (mm per side, default 5.0) to control how much breathing room is left around the features:

>>> from papermap import PaperMap
>>> pm = PaperMap.from_gpx("hike.gpx", auto_scale=True, padding=10)
>>> pm.render()
>>> pm.save("Hike.pdf")

For more options and details, see the API Reference.

As a CLI Tool¶

Basic Usage¶

Create a simple portrait-oriented, A4-sized map:

$ papermap latlon -- 13.75889 100.49722 Bangkok.pdf