matplotlib-map-utils 3.1.2__tar.gz → 4.1.0__tar.gz

matplotlib_map_utils-4.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: matplotlib-map-utils
+Version: 4.1.0
+Summary: A suite of tools for creating maps in matplotlib
+Author-email: David Moss <davidmoss1221@gmail.com>
+Project-URL: Homepage, https://github.com/moss-xyz/matplotlib-map-utils/
+Project-URL: Bug Tracker, https://github.com/moss-xyz/matplotlib-map-utils/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU General Public License (GPL)
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Matplotlib
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.9.0
+Requires-Dist: cartopy>=0.23.0
+Requires-Dist: great-circle-calculator>=1.3.1
+Requires-Dist: pydantic>=2.13.3
+Dynamic: license-file
+
+![matplotlib_map_utils logo](docs/assets/index/mmu_logo_w_elements.png)
+ 
+---
+
+**Documentation:** Available at [https://moss-xyz.github.io/matplotlib-map-utils/](https://moss-xyz.github.io/matplotlib-map-utils/)
+
+**Source Code:** [Available on GitHub](https://github.com/moss-xyz/matplotlib-map-utils)
+
+**Feedback:** I welcome any and all feedback! See the *Development Notes* below for more details.
+
+**Current Version:** `v4.1.0`, featuring a brand-new documentation site and improved type validation! This DID introduce some breaking changes, see the documentation site for details!
+
+---
+
+### 👋 Introduction
+
+`matplotlib_map_utils` is a package that that assists with the creation of maps using [`matplotlib`](https://matplotlib.org/stable/).
+
+As of `v4.x` (the current version), this includes the ability to easily create three common map elements: 
+
+* <span style="color: orange; font-weight: bold;">North arrows</span>, which automatically point to true north,
+
+* <span style="color: orange; font-weight: bold;">Scale bars</span>, available in different styles and automatic unit conversion, and
+
+* <span style="color: orange; font-weight: bold;">Inset maps</span>, including both detail and extent-style plots. 
+
+The three elements listed above are all intended to be high-resolution, easily modifiable, and context-aware relative to your specific plot.
+
+This package also contains a single utility object:
+
+* <span style='color: orange; font-weight: bold; font-family: var(--md-code-font-family);'>USA</span>, a class that helps filter for states and territories within the USA based on given characteristics, used primarily for building queries based on FIPS codes or names.
+
+Together, these allow for the (relatively) easy creation of a map such as the following:
+
+![Map with all common elements added](docs/assets/index/bigmap_w_elements.png)
+
+---
+
+### 💾 Installation
+
+This package is available on PyPi, and can be installed like so:
+
+```bash
+pip install matplotlib-map-utils
+# or
+uv add matplotlib-map-utils
+```
+
+The requirements for this package are:
+
+* `python >= 3.10` (due to the use of the pipe operator to concatenate dictionaries and types)
+
+* `matplotlib >= 3.9` (might work with lower versions but not guaranteed)
+
+* `cartopy >= 0.23` (due to earlier bug with calling `copy()` on `CRS` objects)
+
+* `pydantic >= 2.13.3` (for type validation; might work with older versions, open an issue if you have questions)
+
+---
+
+### Quick Start and Usage Guides
+
+For a primer on how to import the package and use the primary functions and methods to create elements, see the [Quick Start guide](https://moss_xyz.github.io/matplotlib_map_utils/quick).
+
+Each part of the package also has a dedicated page that lays out usage and customisation options in more detail:
+
+- 🧭  [__North Arrows__](https://moss_xyz.github.io/matplotlib_map_utils/north_arrows)
+- 📏  [__Scale Bars__](https://moss_xyz.github.io/matplotlib_map_utils/scale_bars)
+- 🗺️  [__Inset Maps__](https://moss_xyz.github.io/matplotlib_map_utils/inset_maps)
+- 🛠️  [__Utilities__](https://moss_xyz.github.io/matplotlib_map_utils/utilities)
+
+Finally, the [Package Information page](https://moss_xyz.github.io/matplotlib_map_utils/package) provides additional context around the development of and overall structure of the package.
+
+---
+
+### 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.
+
+I am open to contributions, especially to help tackle the roadmap above!
+
+---
+
+### ⚖️ 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.

matplotlib_map_utils-4.1.0/README.md

@@ -0,0 +1,88 @@
+![matplotlib_map_utils logo](docs/assets/index/mmu_logo_w_elements.png)
+ 
+---
+
+**Documentation:** Available at [https://moss-xyz.github.io/matplotlib-map-utils/](https://moss-xyz.github.io/matplotlib-map-utils/)
+
+**Source Code:** [Available on GitHub](https://github.com/moss-xyz/matplotlib-map-utils)
+
+**Feedback:** I welcome any and all feedback! See the *Development Notes* below for more details.
+
+**Current Version:** `v4.1.0`, featuring a brand-new documentation site and improved type validation! This DID introduce some breaking changes, see the documentation site for details!
+
+---
+
+### 👋 Introduction
+
+`matplotlib_map_utils` is a package that that assists with the creation of maps using [`matplotlib`](https://matplotlib.org/stable/).
+
+As of `v4.x` (the current version), this includes the ability to easily create three common map elements: 
+
+* <span style="color: orange; font-weight: bold;">North arrows</span>, which automatically point to true north,
+
+* <span style="color: orange; font-weight: bold;">Scale bars</span>, available in different styles and automatic unit conversion, and
+
+* <span style="color: orange; font-weight: bold;">Inset maps</span>, including both detail and extent-style plots. 
+
+The three elements listed above are all intended to be high-resolution, easily modifiable, and context-aware relative to your specific plot.
+
+This package also contains a single utility object:
+
+* <span style='color: orange; font-weight: bold; font-family: var(--md-code-font-family);'>USA</span>, a class that helps filter for states and territories within the USA based on given characteristics, used primarily for building queries based on FIPS codes or names.
+
+Together, these allow for the (relatively) easy creation of a map such as the following:
+
+![Map with all common elements added](docs/assets/index/bigmap_w_elements.png)
+
+---
+
+### 💾 Installation
+
+This package is available on PyPi, and can be installed like so:
+
+```bash
+pip install matplotlib-map-utils
+# or
+uv add matplotlib-map-utils
+```
+
+The requirements for this package are:
+
+* `python >= 3.10` (due to the use of the pipe operator to concatenate dictionaries and types)
+
+* `matplotlib >= 3.9` (might work with lower versions but not guaranteed)
+
+* `cartopy >= 0.23` (due to earlier bug with calling `copy()` on `CRS` objects)
+
+* `pydantic >= 2.13.3` (for type validation; might work with older versions, open an issue if you have questions)
+
+---
+
+### Quick Start and Usage Guides
+
+For a primer on how to import the package and use the primary functions and methods to create elements, see the [Quick Start guide](https://moss_xyz.github.io/matplotlib_map_utils/quick).
+
+Each part of the package also has a dedicated page that lays out usage and customisation options in more detail:
+
+- 🧭  [__North Arrows__](https://moss_xyz.github.io/matplotlib_map_utils/north_arrows)
+- 📏  [__Scale Bars__](https://moss_xyz.github.io/matplotlib_map_utils/scale_bars)
+- 🗺️  [__Inset Maps__](https://moss_xyz.github.io/matplotlib_map_utils/inset_maps)
+- 🛠️  [__Utilities__](https://moss_xyz.github.io/matplotlib_map_utils/utilities)
+
+Finally, the [Package Information page](https://moss_xyz.github.io/matplotlib_map_utils/package) provides additional context around the development of and overall structure of the package.
+
+---
+
+### 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.
+
+I am open to contributions, especially to help tackle the roadmap above!
+
+---
+
+### ⚖️ 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.

matplotlib_map_utils-4.1.0/docs/assets/index/generator_logo.py

@@ -0,0 +1,141 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+import matplotlib.cm as cm
+import matplotlib.font_manager
+from matplotlib.patches import PathPatch, Rectangle
+from matplotlib.text import TextPath
+import matplotlib.transforms as mtrans
+
+# This is based on the functions from the MPL documentation page here: https://matplotlib.org/stable/gallery/misc/logos2.html
+
+# NOTE: updated to a soft green
+MMU_GREEN = '#155e3c'
+
+
+def get_font_properties():
+    # NOTE: had to update
+    if matplotlib.font_manager.findfont('Calibri:bold'):
+        return matplotlib.font_manager.FontProperties(family='Calibri',
+                                                      weight='bold')
+    if matplotlib.font_manager.findfont('Carlito:bold'):
+        print('Original font not found. Falling back to Carlito. '
+              'The logo text will not be in the correct font.')
+        return matplotlib.font_manager.FontProperties(family='Carlito',
+                                                      weight='bold')
+    print('Original font not found. '
+          'The logo text will not be in the correct font.')
+    return None
+
+
+def create_icon_axes(fig, ax_position, lw_bars, lw_grid, lw_border, rgrid):
+    """
+    Create a polar Axes containing the matplotlib radar plot.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The figure to draw into.
+    ax_position : (float, float, float, float)
+        The position of the created Axes in figure coordinates as
+        (x, y, width, height).
+    lw_bars : float
+        The linewidth of the bars.
+    lw_grid : float
+        The linewidth of the grid.
+    lw_border : float
+        The linewidth of the Axes border.
+    rgrid : array-like
+        Positions of the radial grid.
+
+    Returns
+    -------
+    ax : matplotlib.axes.Axes
+        The created Axes.
+    """
+    with plt.rc_context({'axes.edgecolor': MMU_GREEN,
+                         'axes.linewidth': lw_border}):
+        ax = fig.add_axes(ax_position, projection='polar')
+        ax.set_axisbelow(True)
+
+        N = 7
+        arc = 2. * np.pi
+        theta = np.arange(0.0, arc, arc / N)
+        radii = np.array([2, 6, 8, 7, 4, 5, 8])
+        width = np.pi / 4 * np.array([0.4, 0.4, 0.6, 0.8, 0.2, 0.5, 0.3])
+        bars = ax.bar(theta, radii, width=width, bottom=0.0, align='edge',
+                      edgecolor='0.3', lw=lw_bars)
+        for r, bar in zip(radii, bars):
+            color = *cm.jet(r / 10.)[:3], 0.6  # color from jet with alpha=0.6
+            bar.set_facecolor(color)
+
+        ax.tick_params(labelbottom=False, labeltop=False,
+                       labelleft=False, labelright=False)
+
+        ax.grid(lw=lw_grid, color='0.9')
+        ax.set_rmax(9)
+        ax.set_yticks(rgrid)
+
+        # the actual visible background - extends a bit beyond the axis
+        ax.add_patch(Rectangle((0, 0), arc, 9.58,
+                               facecolor='white', zorder=0,
+                               clip_on=False, in_layout=False))
+        return ax
+
+
+def create_text_axes(fig, height_px):
+    """Create an Axes in *fig* that contains 'matplotlib' as Text."""
+    ax = fig.add_axes((0, 0, 1, 1))
+    ax.set_aspect("equal")
+    ax.set_axis_off()
+
+    path = TextPath((0, 0), "matplotlib_map_utils", size=height_px * 0.8,
+                    prop=get_font_properties())
+
+    angle = 4.25  # degrees
+    trans = mtrans.Affine2D().skew_deg(angle, 0)
+
+    patch = PathPatch(path, transform=trans + ax.transData, color=MMU_GREEN,
+                      lw=0)
+    ax.add_patch(patch)
+    ax.autoscale()
+
+
+def make_logo(height_px, lw_bars, lw_grid, lw_border, rgrid, with_text=False):
+    """
+    Create a full figure with the Matplotlib logo.
+
+    Parameters
+    ----------
+    height_px : int
+        Height of the figure in pixel.
+    lw_bars : float
+        The linewidth of the bar border.
+    lw_grid : float
+        The linewidth of the grid.
+    lw_border : float
+        The linewidth of icon border.
+    rgrid : sequence of float
+        The radial grid positions.
+    with_text : bool
+        Whether to draw only the icon or to include 'matplotlib' as text.
+    """
+    dpi = 100
+    height = height_px / dpi
+    figsize = (5 * height, height) if with_text else (height, height)
+    fig = plt.figure(figsize=figsize, dpi=dpi)
+    # NOTE: updated this
+    fig.patch.set_alpha(1)
+
+    if with_text:
+        create_text_axes(fig, height_px)
+    # NOTE updated this, manually positioned it
+    ax_pos = (0.28, 0.12, .075, 0.75) if with_text else (0.03, 0.03, .94, .94)
+    ax = create_icon_axes(fig, ax_pos, lw_bars, lw_grid, lw_border, rgrid)
+
+    return fig, ax
+
+make_logo(height_px=500, lw_bars=0.7, lw_grid=0.5, lw_border=1,
+          rgrid=[1, 3, 5, 7], with_text=True)
+# plt.show()
+plt.savefig("./mmu_logo.png", bbox_inches="tight")

matplotlib_map_utils-4.1.0/docs/assets/index/generator_map.py

@@ -0,0 +1,63 @@
+import pygris
+import geopandas
+import pyproj
+import shapely
+import contextily
+import matplotlib.pyplot
+from matplotlib_map_utils.core import north_arrow, scale_bar, ScaleBar, inset_map, indicate_detail, indicate_extent, dual_bars
+from matplotlib_map_utils.utils import USA
+
+# This is just a function to create a new, blank map with matplotlib, with our default settings
+def new_map(rows=1, cols=1, figsize=(5,5), dpi=150, ticks=False):
+    # Creating the plot(s)
+    fig, ax = matplotlib.pyplot.subplots(rows,cols, figsize=figsize, dpi=dpi)
+    # Turning off the x and y axis ticks
+    if ticks==False:
+        if rows > 1 or cols > 1:
+            for a in ax.flatten():
+                a.set_xticks([])
+                a.set_yticks([])
+        else:
+            ax.set_xticks([])
+            ax.set_yticks([])
+    # Returning the fig and ax
+    return fig, ax
+
+# states = pygris.states(cb=True, year=2022, cache=False).to_crs(3857)
+states = geopandas.read_file("../../../matplotlib_map_utils/scratch/states.gpkg").to_crs(3857)
+usa = USA()
+contiguous = states.query(f"GEOID in {usa.filter_contiguous(True)}")
+georgia = states.query(f"GEOID == '{usa.filter_abbr("GA")}'")
+
+# Making a map of Georgia
+fig, ax = new_map(figsize=(10,10))
+georgia.buffer(75000).plot(ax=ax, facecolor="none", edgecolor="none") # this helps us "zoom out" a bit
+georgia.plot(ax=ax, edgecolor="black", facecolor="none")
+
+# Creating an inset map and extent indicator for the USA
+cax = inset_map(ax, location="lower right", imsize=1.75, pad=0.1, xticks=[], yticks=[])
+contiguous.plot(ax=cax, facecolor="none", edgecolor="black", linewidth=0.5)
+indicate_extent(cax, ax, 3857, 3857)
+
+# Creating an inset map and detail indicator for Atlanta, GA
+atl_centroid = shapely.Point(pyproj.Transformer.from_crs(4326, 3857, always_xy=True).transform(-84.40123859860549, 33.75203795433787))
+atl_buffer = atl_centroid.buffer(20000)
+aax = inset_map(ax, location="upper right", imsize=1.75, pad=0.25, xticks=[], yticks=[])
+geopandas.GeoSeries(atl_buffer).plot(ax=aax, facecolor="none", edgecolor="none")
+indicate_detail(ax, aax, 3857, 3857, linecolor="cornflowerblue")
+
+# Creating a north arrow
+na = north_arrow(ax=ax, location="upper left", scale=0.5, rotation={"degrees":0})
+
+# Creating a scale bar
+# sb = scale_bar(ax=ax, style="boxes", location="lower left", bar={"length":2, "projection":3857}, text={"fontsize":8})
+db = dual_bars(ax=ax, style="boxes", location="lower left", 
+               bar={"rotation":0, "reverse":False, "projection":3857}, 
+							 text={"fontsize": 8}, units={"loc":"text"})
+
+# Adding contextily basemaps
+contextily.add_basemap(ax, attribution="", source=contextily.providers.CartoDB.Voyager)
+contextily.add_basemap(cax, attribution="", source=contextily.providers.CartoDB.VoyagerNoLabels)
+contextily.add_basemap(aax, attribution="", source=contextily.providers.CartoDB.Voyager)
+
+matplotlib.pyplot.savefig("./bigmap_w_elements.png", bbox_inches="tight")