matplotlib-map-utils 3.1.1__py3-none-any.whl → 4.0.0__py3-none-any.whl

matplotlib_map_utils/core/scale_bar.py

@@ -35,6 +35,7 @@ from ..validation import functions as sbf
 
 _DEFAULT_BAR, _DEFAULT_LABELS, _DEFAULT_UNITS, _DEFAULT_TEXT, _DEFAULT_AOB = sbd._DEFAULTS_SB["md"]
 
+
 ### CLASSES ###
 
 class ScaleBar(matplotlib.artist.Artist):
@@ -205,9 +206,17 @@ class ScaleBar(matplotlib.artist.Artist):
     # THANK YOU to matplotlib-scalebar for figuring this out
     # Note that we never specify the renderer - the axis takes care of it!
     def draw(self, renderer, *args, **kwargs):
+        # Prefer renderer dpi for class-based artists so exports stay sharp
+        # when savefig(dpi=...) differs from the figure construction dpi.
+        _bar = copy.deepcopy(self._bar)
+        if _bar.get("raster_dpi", None) is None:
+            _raster_dpi, _ = _resolve_raster_dpi(
+                _bar, self.axes.get_figure(), renderer=renderer
+            )
+            _bar["raster_dpi"] = _raster_dpi
         # Can re-use the drawing function we already established, but return the object instead
         sb_artist = scale_bar(ax=self.axes, style=self._style, location=self._location, draw=False,
-                                    bar=self._bar, units=self._units, 
+                                    bar=_bar, units=self._units,
                                     labels=self._labels, text=self._text, aob=self._aob,
                                     zorder=self._zorder)
         # This handles the actual drawing
@@ -251,6 +260,22 @@ def scale_bar(ax, draw=True, style: Literal["ticks","boxes"]="boxes",
                   aob: None | bool | sbt._TYPE_AOB=None,
                   zorder: int=99,
                   return_aob: bool=True,):
+    # For the default function mode, dispatch to the Artist class so final
+    # rasterization happens at draw-time with the active renderer dpi.
+    if draw == True and return_aob == True:
+        _ = ax.add_artist(
+            ScaleBar(
+                style=style,
+                location=location,
+                bar=bar,
+                units=units,
+                labels=labels,
+                text=text,
+                aob=aob,
+                zorder=zorder,
+            )
+        )
+        return
 
     ##### VALIDATION #####
     _style = sbf._validate(sbt._VALIDATE_PRIMARY, "style", style)
@@ -272,6 +297,12 @@ def scale_bar(ax, draw=True, style: Literal["ticks","boxes"]="boxes",
     _text = sbf._validate_dict(text, copy.deepcopy(_DEFAULT_TEXT), sbt._VALIDATE_TEXT, return_clean=True) # this one has to be a deepcopy due to dictionary immutability
     _aob = sbf._validate_dict(aob, _DEFAULT_AOB, sbt._VALIDATE_AOB, return_clean=True)
 
+    # Raster controls for the temporary rendered image.
+    # These are kept explicit so output quality is not coupled to external rc state.
+    _fig = ax.get_figure()
+    _raster_dpi, _raster_dpi_scale = _resolve_raster_dpi(_bar, _fig)
+    _raster_dpi = _raster_dpi * _raster_dpi_scale
+
     ##### CONFIGURING TEXT #####
     # First need to convert each string font size (if any) to a point size
     for d in [_text, _labels, _units]:
@@ -290,7 +321,7 @@ def scale_bar(ax, draw=True, style: Literal["ticks","boxes"]="boxes",
     # First, ensuring matplotlib knows the correct dimensions for everything
     # as we need it to be accurate to calculate out the plots!
     if draw:
-        ax.get_figure().draw_without_rendering()
+        _fig.draw_without_rendering()
 
     # Getting the config for the bar (length, text, divs, etc.)
     bar_max, bar_length, units_label, major_div, minor_div = _config_bar(ax, _bar)
@@ -308,7 +339,7 @@ def scale_bar(ax, draw=True, style: Literal["ticks","boxes"]="boxes",
         units_label = _units["label"]
 
     # Creating a temporary figure and axis for rendering later
-    fig_temp, ax_temp = _temp_figure(ax)
+    fig_temp, ax_temp = _temp_figure(ax, dpi=_raster_dpi)
 
     ##### BAR CONSTRUCTION #####
 
@@ -472,7 +503,14 @@ def scale_bar(ax, draw=True, style: Literal["ticks","boxes"]="boxes",
 
     # Placing the image in an OffsetBox, while rotating if desired
     # We have to set the zoom level to be relative to the DPI as well (image is in pixels)
-    offset_img = matplotlib.offsetbox.OffsetImage(img_scale_bar, origin="upper", zoom=72/fig_temp.dpi)
+    offset_img = matplotlib.offsetbox.OffsetImage(
+        img_scale_bar,
+        origin="upper",
+        zoom=72/fig_temp.dpi,
+        interpolation=_bar.get("interpolation", "none"),
+        dpi_cor=_bar.get("dpi_cor", True),
+        resample=_bar.get("resample", False),
+    )
     # If desired, we can just return the rendered image in the final OffsetImage
     # This will override any aob or draw selections! Only the OffsetImage is returned!
     if return_aob==False:
@@ -1087,15 +1125,18 @@ def _format_numeric(val, fmt, integer_override=True):
             return f"{val:{fmt}}"
 
 # A small function for creating a temporary figure based on a provided axis
-def _temp_figure(ax, axis=False, visible=False):
+def _temp_figure(ax, axis=False, visible=False, dpi=None):
     # Getting the figure of the provided axis
     fig = ax.get_figure()
+    # If no dpi is passed, fall back to the figure dpi
+    if dpi is None:
+        dpi = fig.dpi
     # Getting the dimensions of the axis
     ax_bbox = ax.patch.get_window_extent()
     # Converting to inches and rounding up
     ax_dim = math.ceil(max(ax_bbox.height, ax_bbox.width) / fig.dpi)
     # Creating a new temporary figure
-    fig_temp, ax_temp = matplotlib.pyplot.subplots(1,1, figsize=(ax_dim*1.5, ax_dim*1.5), dpi=fig.dpi)
+    fig_temp, ax_temp = matplotlib.pyplot.subplots(1,1, figsize=(ax_dim*1.5, ax_dim*1.5), dpi=dpi)
     # Turning off the x and y labels if desired
     if axis == False:
         ax_temp.axis("off")
@@ -1270,9 +1311,9 @@ def _render_as_image(fig, ax, artist, rotation, add=True, remove=True, close=Tru
     # If needed, adding the artist to the axis
     if add == True:
         ax.add_artist(artist)
-    # Draw the figure, but without showing it, to place all the elements
-    fig.draw_without_rendering()
-    # Sets the canvas for the figure to AGG (Anti-Grain Geometry)
+    # Render directly with Agg; a prior draw_without_rendering() can override
+    # temporary figure DPI in some wrappers (e.g., UltraPlot), which makes
+    # raster_dpi ineffective.
     canvas = FigureCanvasAgg(fig)
     # Draws the figure onto the canvas
     canvas.draw()
@@ -1291,4 +1332,15 @@ def _render_as_image(fig, ax, artist, rotation, add=True, remove=True, close=Tru
     if close == True:
         matplotlib.pyplot.close(fig)
     # Returning the image
-    return img
+    return img
+
+
+def _resolve_raster_dpi(bar, fig, renderer=None):
+    """
+    Resolve base raster DPI and raster scale for temporary rendering.
+    """
+    raster_dpi = bar.get("raster_dpi", None)
+    if raster_dpi is None:
+        raster_dpi = renderer.dpi if renderer is not None else fig.dpi
+    raster_dpi_scale = bar.get("raster_dpi_scale", 1)
+    return raster_dpi, raster_dpi_scale

matplotlib_map_utils/defaults/scale_bar.py

@@ -35,7 +35,12 @@ _BAR_XS = {
     "tick_loc":"above",
     "basecolors":["black"],
     "tickcolors":["black"],
-    "tickwidth":0.5 # changed
+    "tickwidth":0.5, # changed
+    "interpolation":"none",
+    "dpi_cor":True,
+    "resample":False,
+    "raster_dpi":None,
+    "raster_dpi_scale":1,
 }
 
 # Labels
@@ -107,7 +112,12 @@ _BAR_SM = {
     "tick_loc":"above",
     "basecolors":["black"],
     "tickcolors":["black"],
-    "tickwidth":0.75 # changed
+    "tickwidth":0.75, # changed
+    "interpolation":"none",
+    "dpi_cor":True,
+    "resample":False,
+    "raster_dpi":None,
+    "raster_dpi_scale":1,
 }
 
 # Labels
@@ -179,7 +189,12 @@ _BAR_MD = {
     "tick_loc":"above",
     "basecolors":["black"],
     "tickcolors":["black"],
-    "tickwidth":1.5 # changed
+    "tickwidth":1.5, # changed
+    "interpolation":"none",
+    "dpi_cor":True,
+    "resample":False,
+    "raster_dpi":None,
+    "raster_dpi_scale":1,
 }
 
 # Labels
@@ -251,7 +266,12 @@ _BAR_LG = {
     "tick_loc":"above",
     "basecolors":["black"],
     "tickcolors":["black"],
-    "tickwidth":3 # changed
+    "tickwidth":3, # changed
+    "interpolation":"none",
+    "dpi_cor":True,
+    "resample":False,
+    "raster_dpi":None,
+    "raster_dpi_scale":1,
 }
 
 # Labels
@@ -323,7 +343,12 @@ _BAR_XL = {
     "tick_loc":"above",
     "basecolors":["black"],
     "tickcolors":["black"],
-    "tickwidth":5 # changed
+    "tickwidth":5, # changed
+    "interpolation":"none",
+    "dpi_cor":True,
+    "resample":False,
+    "raster_dpi":None,
+    "raster_dpi_scale":1,
 }
 
 # Labels
@@ -379,4 +404,4 @@ _DEFAULTS_SB = {
     "md":[_BAR_MD, _LABELS_MD, _UNITS_MD, _TEXT_MD, _AOB_MD],
     "lg":[_BAR_LG, _LABELS_LG, _UNITS_LG, _TEXT_LG, _AOB_LG],
     "xl":[_BAR_XL, _LABELS_XL, _UNITS_XL, _TEXT_XL, _AOB_XL],
-}
+}

matplotlib_map_utils/validation/scale_bar.py

@@ -99,6 +99,11 @@ class _TYPE_BAR(TypedDict, total=False):
     basecolors: list | tuple | str # a color or list of colors to use for the bottom bar
     tickcolors: list | tuple | str # a color or list of colors to use for the ticks
     tickwidth: float | int # the line thickness of the bottom bar and ticks
+    interpolation: str | None # interpolation method used by OffsetImage; e.g. "none", "nearest", "bilinear"
+    dpi_cor: bool # whether OffsetImage should be corrected for renderer dpi (matplotlib default behavior)
+    resample: bool # whether OffsetImage should use image resampling during scaling
+    raster_dpi: float | int | None # explicit dpi for temporary rasterization step, None uses figure/renderer dpi
+    raster_dpi_scale: float | int # multiplier applied to raster_dpi for supersampling
 
 
 class _TYPE_LABELS(TypedDict, total=False):
@@ -195,6 +200,11 @@ _VALIDATE_BAR = {
     "basecolors":{"func":vf._validate_iterable, "kwargs":{"func":matplotlib.rcsetup.validate_color}}, # ticks only: any color value for matplotlib
     "tickcolors":{"func":vf._validate_iterable, "kwargs":{"func":matplotlib.rcsetup.validate_color}}, # ticks only: any color value for matplotlib
     "tickwidth":{"func":vf._validate_range, "kwargs":{"min":0, "max":None, "none_ok":True}}, # ticks only: between 0 and inf
+    "interpolation":{"func":vf._validate_type, "kwargs":{"match":str, "none_ok":True}},
+    "dpi_cor":{"func":vf._validate_type, "kwargs":{"match":bool}},
+    "resample":{"func":vf._validate_type, "kwargs":{"match":bool}},
+    "raster_dpi":{"func":vf._validate_range, "kwargs":{"min":1, "max":None, "none_ok":True}},
+    "raster_dpi_scale":{"func":vf._validate_range, "kwargs":{"min":0.0001, "max":None, "none_ok":True}},
 }
 
 _VALID_LABELS_STYLE = get_args(_TYPE_LABELS.__annotations__["style"])
@@ -272,4 +282,4 @@ _VALIDATE_AOB = {
     "frameon":{"func":vf._validate_type, "kwargs":{"match":bool}}, # any bool
     "bbox_to_anchor":{"func":vf._skip_validation}, # NOTE: currently unvalidated, use at your own risk!
     "bbox_transform":{"func":vf._skip_validation}, # NOTE: currently unvalidated, use at your own risk!
-}
+}

matplotlib_map_utils-4.0.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: matplotlib-map-utils
+Version: 4.0.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
+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.0.0`, featuring a brand-new documentation site!
+
+---
+
+### 👋 Introduction
+
+`matplotlib_map_utils` is a package that that assists with the creation of maps using [`matplotlib`](https://matplotlib.org/stable/).
+
+As of `v3.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)
+
+---
+
+### 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-3.1.1.dist-info → matplotlib_map_utils-4.0.0.dist-info}/RECORD

@@ -2,11 +2,11 @@ matplotlib_map_utils/__init__.py,sha256=2mL2sZOjfxC--EthFMTMuYh1uvozz-9PzM4EDprD
 matplotlib_map_utils/core/__init__.py,sha256=mIn7x-LZlvNaYMcmjZXwnKNTirv3Vv2lAJodwRg_AdU,471
 matplotlib_map_utils/core/inset_map.py,sha256=iJISV0gZ3OmhO-DzC5z5kH5qL8fpdqmHn5OkdhdtzAY,41561
 matplotlib_map_utils/core/north_arrow.py,sha256=UDn0TBnLuhuONbibb_XT8C2HNSY6ONLCQgadR19WpmI,22846
-matplotlib_map_utils/core/scale_bar.py,sha256=kM9WMwdpKJuShl8BkzsRcFhc0y-Kxu8wJpriz8iVYzk,67064
+matplotlib_map_utils/core/scale_bar.py,sha256=RPVFhQ1I5Z6fqc31JRdlUgcxxfoJQ9FKkRrK1fjgokQ,68993
 matplotlib_map_utils/defaults/__init__.py,sha256=_pegE5kv_sb0ansSF4XpWBRwboaP4zUjWY1KIGbK-TE,119
 matplotlib_map_utils/defaults/inset_map.py,sha256=RNwaZqWjDjdNwPgmqx_cN9lQQ6DW_Db61peaeMRCPlc,1569
 matplotlib_map_utils/defaults/north_arrow.py,sha256=uZb1RsUWxFTHywm8HATj_9iPF_GjCs_Z2HOn0JchjTY,8571
-matplotlib_map_utils/defaults/scale_bar.py,sha256=422U5hBtLpXrWZuj7vOnZNmIWI_KnOgDIwRX__m4GCY,8345
+matplotlib_map_utils/defaults/scale_bar.py,sha256=H_4shk1AwJkEj9IXk7BRdEsT0aaGm6FHWr57bzU1PMA,8972
 matplotlib_map_utils/scratch/map_utils.py,sha256=j8dOX9uuotl9rRCAXapFLHycUwVE4nzIrqWYOGG2Lgg,19653
 matplotlib_map_utils/scratch/north_arrow_old_classes.py,sha256=1xKQ6yUghX4BWzIv8GsGBHDDPJ8B0Na7ixdw2jgtTqw,50993
 matplotlib_map_utils/utils/__init__.py,sha256=uUy0kUMMGrDpvo88J_OLk2dQI-UwCXclccaEyk8x5R0,41
@@ -16,9 +16,9 @@ matplotlib_map_utils/validation/__init__.py,sha256=0fL3N63jxjRwTU44b7-6ZYZJfOT_0
 matplotlib_map_utils/validation/functions.py,sha256=IIT9DiPKVv_ZHUTC8FwXJPt2pzdQI-8zhx6SHqto65E,13020
 matplotlib_map_utils/validation/inset_map.py,sha256=C5e_zOBKHqVNgufhwoIxu1OhlvXoaj70WxreW4BSfnA,6019
 matplotlib_map_utils/validation/north_arrow.py,sha256=6D-uLiMmre0E9JwjR0BTWNZJyCqPuL0b3HGZ91UHoXw,10442
-matplotlib_map_utils/validation/scale_bar.py,sha256=dYhiuqBV8wkMmFsR8p4RMbfBmN1DU--5cWU-Om9m7UY,18162
-matplotlib_map_utils-3.1.1.dist-info/licenses/LICENSE,sha256=aFLFZg6LEJFpTlNQ8su3__jw4GfV-xWBmC1cePkKZVw,35802
-matplotlib_map_utils-3.1.1.dist-info/METADATA,sha256=AZQKlt58icL88wIRhSJwyEdU6XhEDwcr-zpiwBBsoQQ,63423
-matplotlib_map_utils-3.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-matplotlib_map_utils-3.1.1.dist-info/top_level.txt,sha256=6UyDpxsnMhSOd9a-abQe0lLJveybJyYtUHMdX7zXgKA,21
-matplotlib_map_utils-3.1.1.dist-info/RECORD,,
+matplotlib_map_utils/validation/scale_bar.py,sha256=DAPTK1BHJXAQQE4Zii4a2Dt7boBtgy4f5dDp4NSUxog,19097
+matplotlib_map_utils-4.0.0.dist-info/licenses/LICENSE,sha256=aFLFZg6LEJFpTlNQ8su3__jw4GfV-xWBmC1cePkKZVw,35802
+matplotlib_map_utils-4.0.0.dist-info/METADATA,sha256=RpGTjxrbQvDY3_hB66nSt0PScxdE7zQ6cGK-P-2c2TA,4613
+matplotlib_map_utils-4.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+matplotlib_map_utils-4.0.0.dist-info/top_level.txt,sha256=6UyDpxsnMhSOd9a-abQe0lLJveybJyYtUHMdX7zXgKA,21
+matplotlib_map_utils-4.0.0.dist-info/RECORD,,

{matplotlib_map_utils-3.1.1.dist-info → matplotlib_map_utils-4.0.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (82.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any