A suite of tools for creating maps in matplotlib
Project description
matplotlib-map-utils
Documentation: See docs
folder
Source Code: Find the project on GitHub
Introduction
matplotlib_map_utils
is intended to be a package that provides various functions and objects that assist with the the creation of maps using matplotlib
.
As of v1.x
(the current version), this only includes a single additional tool: north_arrow.py
, which applies a high quality, context-aware north arrow to a given plot. Future releases (if the project is continued) might provide similar tools for creating scale bars or inset maps, or functions that I have created myself that give more control in the formatting of maps.
Installation
This package is available on PyPi, and can be installed like so:
pip install matplotlib-map-utils
The requirements for this package are:
-
python >= 3.9.0 (due to the dictionary-concatenation method utilized)
-
matplotlib >= 3.9.0 (might work with lower versions but not guaranteed)
-
cartopy >= 0.23.0 (due to earlier bug with calling
copy()
onCRS
objects)
North Arrow
Quick Start
The quickest way to add a single north arrow to a single plot is to use the north_arrow
function:
# Setting up a plot
fig, ax = matplotlib.pyplot.subplots(1,1, figsize=(10,10), dpi=300)
# Adding a north arrow to the upper-right corner of the axis, without any rotation (see Rotation under Formatting Components for details)
north_arrow.north_arrow(ax=ax, location="upper right", rotation={"degrees":0})
An object-oriented approach is also supported:
# Setting up a plot
fig, ax = matplotlib.pyplot.subplots(1,1, figsize=(10,10), dpi=300)
# Creating a north arrow for the upper-right corner of the axis, without any rotation (see Rotation under Formatting Components for details)
na = north_arrow.NorthArrow(ax=ax, location="upper right", rotation={"degrees":0})
# Adding the artist to the plot
ax.add_artist(na)
Customization
Both the object-oriented and functional approaches can be customized to allow for fine-grained control over formatting:
north_arrow(
ax,
location = "upper right", # accepts a valid string from the list of locations
scale = 0.5, # accepts a valid positive float or integer
# each of the follow accepts arguments from a customized style dictionary
base = {"facecolor":"green"},
fancy = False,
label = {"text":"North"},
shadow = {"alpha":0.8},
pack = {"sep":6},
aob = {"pad":2},
rotation = {"degrees": 35}
)
Refer to docs\howto_north_arrow
for details on how to customize each facet of the north arrow.
Development Notes
Inspiration and Thanks
This project was heavily inspired by matplotlib-scalebar
, and much of the code is either directly copied or a derivative of that project, since it uses the same "artist"-based approach.
Two more projects assisted with the creation of this script:
-
EOmaps
provided code for calculating the rotation required to point to "true north" for an arbitrary point and CRS for the north arrow. -
Cartopy
fixed an issue inherent to calling.copy()
onCRS
objects.
Future Roadmap
As stated in the intro, I am hoping this project will encompass more than just the north arrow object it currently does. In particular, I want v2
to tackle making properly-formatted "map-style" scale bar objects, a la ArcGIS and QGIS.
If that goes well, v3
can either create a tool for generating inset maps (which matplotlib
has some support for), or the various functions that I have created in the past that assist with formatting a map "properly", such as centering on a given object.
I am also open to ideas for other extensions to create!
Support and Contributions
If you notice something is not working as intended or if you'd like to add a feature yourself, I welcome PRs - just be sure to be descriptive as to what you are changing and why, including code examples!
If you are having issues using this script, feel free to leave a post explaining your issue, and I will try and assist, though I have no guaranteed SLAs as this is just a hobby project.
License
I know nothing about licensing, so I went with the GPL license. If that is incompatible with any of the dependencies, please let me know.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for matplotlib_map_utils-1.0.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0b377671559ab17c562ed559fbbf71d923112ffdbebce30b68953c57890905f6 |
|
MD5 | 84496a578e32a752c2e347bb9e55da38 |
|
BLAKE2b-256 | cc64c613bee05b93e83772eed28040487499c8ba89174dcbdd50aa932f3eca35 |
Hashes for matplotlib_map_utils-1.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 071b328bd36adf06fbb570585ea04cb1e8500506ac8636e6a8c0f0399b48d7e8 |
|
MD5 | b0c128641b8ae9f5621c1f948f5eb635 |
|
BLAKE2b-256 | 2d590ce41cad58f76e706f6a29652730e5a02db315ddf80f31f340721eeeff91 |