API Reference#
papermap.papermap Module#
- class papermap.papermap.PaperMap(lat, lon, tile_server='OpenStreetMap', api_key=None, size='a4', use_landscape=False, margin_top=10, margin_right=10, margin_bottom=10, margin_left=10, scale=25000, dpi=300, background_color='#fff', add_grid=False, grid_size=1000)#
A paper map.
>>> from papermap import PaperMap >>> pm = PaperMap(13.75889, 100.49722) >>> pm.render() >>> pm.save("Bangkok.pdf")
- Parameters:
lat (float) – Latitude of the center of the map.
lon (float) – Longitude of the center of the map
tile_server (str) – Tile server to serve as the base of the paper map. Defaults to OpenStreetMap.
api_key (str | None) – API key for the chosen tile server (if applicable). Defaults to None.
size (str) – Size of the paper map. Defaults to a4.
landscape – Use landscape orientation. Defaults to False.
margin_top (int) – Top margin (in mm). Defaults to 10.
margin_right (int) – Right margin (in mm). Defaults to 10.
margin_bottom (int) – Bottom margin (in mm). Defaults to 10.
margin_left (int) – Left margin (in mm). Defaults to 10.
scale (int) – Scale of the paper map. Defaults to 25000.
dpi (int) – Dots per inch. Defaults to 300.
background_color (str) – Background color of the paper map. Defaults to #fff.
add_grid (bool) – Add a coordinate grid overlay to the paper map. Defaults to False.
grid_size (int) – Size of the grid squares (if applicable, in meters). Defaults to 1000.
- Raises:
ValueError – If the tile server is invalid.
ValueError – If no API key is specified (when applicable).
ValueError – If the paper size is invalid.
ValueError – If the scale is “out of bounds”.
- render()#
Render the paper map, consisting of the map image, grid (if applicable), attribution and scale.
papermap.utils Module#
- papermap.utils.cartesian_to_spherical(x, y, z)#
Convert cartesian coordinates (i.e. x, y, z) to spherical coordinates (i.e. lat, lon).
Adapted from: https://github.com/chrisveness/geodesy
- papermap.utils.clip(val, lower, upper)#
Clips a value to [lower, upper] range.
- papermap.utils.compute_central_lon(zone)#
Compute the central longitude of a given UTM zone number.
- papermap.utils.dd_to_dms(dd)#
Convert Decimal Degrees (DD) to Degrees, Minutes, and Seconds (DMS).
- papermap.utils.dms_to_dd(dms)#
Convert Degrees, Minutes, and Seconds (DMS) to Decimal Degrees (DD).
- papermap.utils.lat_to_y(lat, zoom)#
Converts latitude to y (tile coordinate), given a zoom level.
- papermap.utils.lon_to_x(lon, zoom)#
Converts longitude to x (tile coordinate), given a zoom level.
- papermap.utils.mm_to_pt(mm)#
Convert millimeters to points.
- papermap.utils.mm_to_px(mm, dpi=300)#
Convert millimeters to pixels, given the dpi.
- papermap.utils.pt_to_mm(pt)#
Convert points to millimeters.
- papermap.utils.px_to_mm(px, dpi=300)#
Convert pixels to millimeters, given the dpi.
- papermap.utils.scale_to_zoom(scale, lat, dpi=300)#
Compute the zoom level, given the latitude, scale and dpi.
- papermap.utils.spherical_to_cartesian(lat, lon, r=6378137)#
Convert spherical coordinates (i.e. lat, lon) to cartesian coordinates (i.e. x, y, z).
Adapted from: https://github.com/chrisveness/geodesy
- papermap.utils.spherical_to_utm(lat, lon)#
Convert a spherical coordinate (i.e. lat, lon) to a UTM coordinate.
Based on formulas from (Karney, 2011).
Adapted from: https://github.com/chrisveness/geodesy/blob/master/utm.js
References
- papermap.utils.spherical_to_zone(lat, lon)#
Compute the UTM zone number of a given spherical coordinate (i.e. lat, lon).
- papermap.utils.utm_to_spherical(x, y, zone, hemisphere)#
Convert a UTM coordinate to a spherical coordinate (i.e. lat, lon).
Based on formulas from (Karney, 2011).
Adapted from: https://github.com/chrisveness/geodesy/blob/master/utm.js
- Parameters:
References
- papermap.utils.wrap(angle, limit)#
Wraps an angle to [-limit, limit] range.
- papermap.utils.wrap180(angle)#
Wraps an angle to [-180, 180] range
- papermap.utils.wrap360(angle)#
Wraps an angle to [0, 360) range
- papermap.utils.wrap90(angle)#
Wraps an angle to [-90, 90] range.
- papermap.utils.x_to_lon(x, zoom)#
Converts x (tile coordinate) to longitude, given a zoom level.
- papermap.utils.x_to_px(x, x_center, width, tile_size=256)#
Convert x (tile coordinate) to pixels.
- papermap.utils.y_to_lat(y, zoom)#
Converts y (tile coordinate) to latitude, given a zoom level.
- papermap.utils.y_to_px(y, y_center, height, tile_size=256)#
Convert y (tile coordinate) to pixel
papermap.tile Module#
papermap.tile_server Module#
- class papermap.tile_server.TileServer(attribution, url_template, zoom_min, zoom_max, mirrors=None)#
A tile server.
- Parameters:
attribution (str) – The attribution of the tile server.
url_template (str) – The URL template of the tile server. Allowed placeholders are {x}, {y}, {zoom}, {mirror} and {api_key}, where {x} refers to the x coordinate of the tile, {y} refers to the y coordinate of the tile, {zoom} to the zoom level, {mirror} to the mirror (optional) and {api_key} to the API key (optional). See https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Tile_servers for more information.
zoom_min (int) – The minimum zoom level of the tile server.
zoom_max (int) – The maximum zoom level of the tile server.
mirrors (List[str | int | None] | None) – The mirrors of the tile server. Defaults to None.
papermap.typing Module#
Type information used throughout papermap.
- papermap.typing.Angle#
Angle in either degrees or radians.
- papermap.typing.Cartesian_2D#
Two-dimensional Cartesian (x, y) coordinates.
- papermap.typing.Cartesian_3D#
Thee-dimensional Cartesian (x, y, z) coordinates.
- papermap.typing.Degree#
Angle in degrees.
- papermap.typing.Pixel#
Number of pixels.
- papermap.typing.Radian#
Angle in radians.
- papermap.typing.Spherical_2D#
Two-dimensional Spherical (lat, lon) coordinates.
- papermap.typing.Spherical_3D#
Thee-dimensional Spherical (lat, lon, height) coordinates.