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

{matplotlib_map_utils-3.1.0 → matplotlib_map_utils-3.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matplotlib-map-utils
-Version: 3.1.0
+Version: 3.1.2
 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/
@@ -179,7 +179,9 @@ This will create an output like the following:
 
 ![Customized north arrow](matplotlib_map_utils/docs/assets/readme_northarrow_customization.png)
 
-Refer to `docs\howto_north_arrow` for details on how to customize each facet of the north arrow.
+Refer to `docs\howto_north_arrow` for details on how to customize each facet of the north arrow. 
+
+_Note: only add a north arrow **after** adding all of your geodata and changing your axis limits!_
 
 #### Rotation
 
@@ -260,6 +262,8 @@ This will create an output like the following:
 
 Refer to `docs\howto_scale_bar` for details on how to customize each facet of the scale bar.
 
+_Note: only add a scale bar **after** adding all of your geodata and changing your axis limits!_
+
 #### Specifying Length
 
 There are three main ways of specifying the length of a scale bar:
@@ -291,7 +295,6 @@ All of the above cases expect a valid CRS to be supplied to the `projection` par
 - If `projection` is set to `dx`, `custom`, or `axis`, then values for `max` and `major_mult` are interpreted as being in _the units of the x or y axis_ (so a `max` of 1,000 will result in a bar equal to 1,000 units of the x-axis (if orientated horizontally))
 
 The intent of these additional methods is to provide an alternative interface for defining the bar, in the case of non-standard projections, or for non-cartographic use cases (in particular, this is inspired by the `dx` implementation of `matplotlib-scalebar`). However, this puts the onus on the user to know how big their bar should be - you also cannot pass a value to `unit` to convert! Note you can provide custom label text to the bar via the `labels` and `units` arguments (ex. if you need to label "inches" or something).
-
 </details>
 
 ---
@@ -351,7 +354,6 @@ This will create an output like the following (extent indicator on the left, det
 ![Customized scale bar](matplotlib_map_utils/docs/assets/readme_indicators.png)
 
 Refer to `docs\howto_inset_map` for details on how to customize the inset map and indicators to your liking.
-
 </details>
 
 ---
@@ -383,7 +385,6 @@ usa.filter(region=["South","Midwest"], to_return="name")
 ```
 
 Refer to `docs\howto_utils` for details on how to use this class, including with `pandas.apply()`.
-
 </details>
 
 ---
@@ -414,9 +415,7 @@ Two more projects assisted with the creation of this script:
 - `v2.0.2`: Changed f-string formatting to alternate double and single quotes, so as to maintain compatibility with versions of Python before 3.12 (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/3)). However, this did reveal that another aspect of the code, namely concatenating `type` in function arguments, requires 3.10, and so the minimum python version was incremented.
 
 - `v2.1.0`: Added a utility class, `USA`, for filtering subsets of US states and territories based on FIPS code, name, abbreviation, region, division, and more. This is considered a beta release, and might be subject to change later on.
-
 </details>
-<br>
 
 - `v3.0.0`: Release of inset map and extent and detail indicator classes and functions.
 
@@ -424,6 +423,10 @@ Two more projects assisted with the creation of this script:
 
 - `v3.1.0`: Overhauled the functionality for specifying the the length of a scale bar, including support for custom units/projections (similar to `matplotlib-scalebar`'s `dx` argument) and to specify the length of a major division instead of the entire scale bar, as requested [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/10). Added ability to set artist-level `zorder` variables for all elements, with both the function and class method approaches, as requested [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/9) and [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/10). Also fixed a bug related to custom division labels on the scale bar.
 
+- `v3.1.1`: Fixed a bug that led to errors when creating a `scale_bar` at resolutions below 5km or 1 mile, due to a bug in the backend configuration functions (namely, `_config_bar_dim()`), which was fixed by correctly instantiating the necessary variable `ax_units` in other cases via an `else` statement (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/14) for details).
+
+- `v3.1.2`: Fixed a compatibility issue with [Ultraplot](https://github.com/Ultraplot/UltraPlot), primarily affecting the `ScaleBar` element, where text would rasterize at a low resolution (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/16) and [here](https://github.com/moss-xyz/matplotlib-map-utils/pull/17) for details). A big thank you to cvanelteren on the Ultraplot team for identifying and implementing the necessary fixes, as well as making adjustments to the Ultraplot package to improve compatibility!
+
 #### Future Roadmap
 
 With the release of `v3.x`, this project has achieved full coverage of the "main" map elements I think are necessary.

{matplotlib_map_utils-3.1.0 → matplotlib_map_utils-3.1.2}/README.md

@@ -160,7 +160,9 @@ This will create an output like the following:
 
 ![Customized north arrow](matplotlib_map_utils/docs/assets/readme_northarrow_customization.png)
 
-Refer to `docs\howto_north_arrow` for details on how to customize each facet of the north arrow.
+Refer to `docs\howto_north_arrow` for details on how to customize each facet of the north arrow. 
+
+_Note: only add a north arrow **after** adding all of your geodata and changing your axis limits!_
 
 #### Rotation
 
@@ -241,6 +243,8 @@ This will create an output like the following:
 
 Refer to `docs\howto_scale_bar` for details on how to customize each facet of the scale bar.
 
+_Note: only add a scale bar **after** adding all of your geodata and changing your axis limits!_
+
 #### Specifying Length
 
 There are three main ways of specifying the length of a scale bar:
@@ -272,7 +276,6 @@ All of the above cases expect a valid CRS to be supplied to the `projection` par
 - If `projection` is set to `dx`, `custom`, or `axis`, then values for `max` and `major_mult` are interpreted as being in _the units of the x or y axis_ (so a `max` of 1,000 will result in a bar equal to 1,000 units of the x-axis (if orientated horizontally))
 
 The intent of these additional methods is to provide an alternative interface for defining the bar, in the case of non-standard projections, or for non-cartographic use cases (in particular, this is inspired by the `dx` implementation of `matplotlib-scalebar`). However, this puts the onus on the user to know how big their bar should be - you also cannot pass a value to `unit` to convert! Note you can provide custom label text to the bar via the `labels` and `units` arguments (ex. if you need to label "inches" or something).
-
 </details>
 
 ---
@@ -332,7 +335,6 @@ This will create an output like the following (extent indicator on the left, det
 ![Customized scale bar](matplotlib_map_utils/docs/assets/readme_indicators.png)
 
 Refer to `docs\howto_inset_map` for details on how to customize the inset map and indicators to your liking.
-
 </details>
 
 ---
@@ -364,7 +366,6 @@ usa.filter(region=["South","Midwest"], to_return="name")
 ```
 
 Refer to `docs\howto_utils` for details on how to use this class, including with `pandas.apply()`.
-
 </details>
 
 ---
@@ -395,9 +396,7 @@ Two more projects assisted with the creation of this script:
 - `v2.0.2`: Changed f-string formatting to alternate double and single quotes, so as to maintain compatibility with versions of Python before 3.12 (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/3)). However, this did reveal that another aspect of the code, namely concatenating `type` in function arguments, requires 3.10, and so the minimum python version was incremented.
 
 - `v2.1.0`: Added a utility class, `USA`, for filtering subsets of US states and territories based on FIPS code, name, abbreviation, region, division, and more. This is considered a beta release, and might be subject to change later on.
-
 </details>
-<br>
 
 - `v3.0.0`: Release of inset map and extent and detail indicator classes and functions.
 
@@ -405,6 +404,10 @@ Two more projects assisted with the creation of this script:
 
 - `v3.1.0`: Overhauled the functionality for specifying the the length of a scale bar, including support for custom units/projections (similar to `matplotlib-scalebar`'s `dx` argument) and to specify the length of a major division instead of the entire scale bar, as requested [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/10). Added ability to set artist-level `zorder` variables for all elements, with both the function and class method approaches, as requested [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/9) and [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/10). Also fixed a bug related to custom division labels on the scale bar.
 
+- `v3.1.1`: Fixed a bug that led to errors when creating a `scale_bar` at resolutions below 5km or 1 mile, due to a bug in the backend configuration functions (namely, `_config_bar_dim()`), which was fixed by correctly instantiating the necessary variable `ax_units` in other cases via an `else` statement (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/14) for details).
+
+- `v3.1.2`: Fixed a compatibility issue with [Ultraplot](https://github.com/Ultraplot/UltraPlot), primarily affecting the `ScaleBar` element, where text would rasterize at a low resolution (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/16) and [here](https://github.com/moss-xyz/matplotlib-map-utils/pull/17) for details). A big thank you to cvanelteren on the Ultraplot team for identifying and implementing the necessary fixes, as well as making adjustments to the Ultraplot package to improve compatibility!
+
 #### Future Roadmap
 
 With the release of `v3.x`, this project has achieved full coverage of the "main" map elements I think are necessary.

{matplotlib_map_utils-3.1.0 → matplotlib_map_utils-3.1.2}/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:
@@ -771,7 +809,6 @@ def _config_bar_dim(ax, bar_vertical, bar_projection, bar_unit):
             units_user = None
 
         # Converting
-
         # First, the case where the user doesn't provide any units
         # In this instance, we just use the units from the projection
         if units_user is None:
@@ -785,6 +822,9 @@ def _config_bar_dim(ax, bar_vertical, bar_projection, bar_unit):
             elif units_proj == "ft" and ax_range > (5280*5):
                 ax_units = ax_range / 5280
                 units_label = "mi"
+            # Otherwise, if no scaling is necessary...
+            else:
+                ax_units = ax_range
 
         # Otherwise, if the user supplied a unit of some sort, then handle conversion
         else:
@@ -793,6 +833,9 @@ def _config_bar_dim(ax, bar_vertical, bar_projection, bar_unit):
             if units_user != units_proj:
                 # This works by finding the ratios between the two units, using meters as the base
                 ax_units = ax_range * (sbt.convert_dict[units_proj] / sbt.convert_dict[units_user])
+            # Otherwise, if the units are the same
+            else: 
+                ax_units = ax_range
     
     return ax_inches, ax_units, units_label
 
@@ -1082,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")
@@ -1265,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()
@@ -1286,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-3.1.0 → matplotlib_map_utils-3.1.2}/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-3.1.0 → matplotlib_map_utils-3.1.2}/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-3.1.0 → matplotlib_map_utils-3.1.2}/matplotlib_map_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matplotlib-map-utils
-Version: 3.1.0
+Version: 3.1.2
 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/
@@ -179,7 +179,9 @@ This will create an output like the following:
 
 ![Customized north arrow](matplotlib_map_utils/docs/assets/readme_northarrow_customization.png)
 
-Refer to `docs\howto_north_arrow` for details on how to customize each facet of the north arrow.
+Refer to `docs\howto_north_arrow` for details on how to customize each facet of the north arrow. 
+
+_Note: only add a north arrow **after** adding all of your geodata and changing your axis limits!_
 
 #### Rotation
 
@@ -260,6 +262,8 @@ This will create an output like the following:
 
 Refer to `docs\howto_scale_bar` for details on how to customize each facet of the scale bar.
 
+_Note: only add a scale bar **after** adding all of your geodata and changing your axis limits!_
+
 #### Specifying Length
 
 There are three main ways of specifying the length of a scale bar:
@@ -291,7 +295,6 @@ All of the above cases expect a valid CRS to be supplied to the `projection` par
 - If `projection` is set to `dx`, `custom`, or `axis`, then values for `max` and `major_mult` are interpreted as being in _the units of the x or y axis_ (so a `max` of 1,000 will result in a bar equal to 1,000 units of the x-axis (if orientated horizontally))
 
 The intent of these additional methods is to provide an alternative interface for defining the bar, in the case of non-standard projections, or for non-cartographic use cases (in particular, this is inspired by the `dx` implementation of `matplotlib-scalebar`). However, this puts the onus on the user to know how big their bar should be - you also cannot pass a value to `unit` to convert! Note you can provide custom label text to the bar via the `labels` and `units` arguments (ex. if you need to label "inches" or something).
-
 </details>
 
 ---
@@ -351,7 +354,6 @@ This will create an output like the following (extent indicator on the left, det
 ![Customized scale bar](matplotlib_map_utils/docs/assets/readme_indicators.png)
 
 Refer to `docs\howto_inset_map` for details on how to customize the inset map and indicators to your liking.
-
 </details>
 
 ---
@@ -383,7 +385,6 @@ usa.filter(region=["South","Midwest"], to_return="name")
 ```
 
 Refer to `docs\howto_utils` for details on how to use this class, including with `pandas.apply()`.
-
 </details>
 
 ---
@@ -414,9 +415,7 @@ Two more projects assisted with the creation of this script:
 - `v2.0.2`: Changed f-string formatting to alternate double and single quotes, so as to maintain compatibility with versions of Python before 3.12 (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/3)). However, this did reveal that another aspect of the code, namely concatenating `type` in function arguments, requires 3.10, and so the minimum python version was incremented.
 
 - `v2.1.0`: Added a utility class, `USA`, for filtering subsets of US states and territories based on FIPS code, name, abbreviation, region, division, and more. This is considered a beta release, and might be subject to change later on.
-
 </details>
-<br>
 
 - `v3.0.0`: Release of inset map and extent and detail indicator classes and functions.
 
@@ -424,6 +423,10 @@ Two more projects assisted with the creation of this script:
 
 - `v3.1.0`: Overhauled the functionality for specifying the the length of a scale bar, including support for custom units/projections (similar to `matplotlib-scalebar`'s `dx` argument) and to specify the length of a major division instead of the entire scale bar, as requested [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/10). Added ability to set artist-level `zorder` variables for all elements, with both the function and class method approaches, as requested [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/9) and [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/10). Also fixed a bug related to custom division labels on the scale bar.
 
+- `v3.1.1`: Fixed a bug that led to errors when creating a `scale_bar` at resolutions below 5km or 1 mile, due to a bug in the backend configuration functions (namely, `_config_bar_dim()`), which was fixed by correctly instantiating the necessary variable `ax_units` in other cases via an `else` statement (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/14) for details).
+
+- `v3.1.2`: Fixed a compatibility issue with [Ultraplot](https://github.com/Ultraplot/UltraPlot), primarily affecting the `ScaleBar` element, where text would rasterize at a low resolution (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/16) and [here](https://github.com/moss-xyz/matplotlib-map-utils/pull/17) for details). A big thank you to cvanelteren on the Ultraplot team for identifying and implementing the necessary fixes, as well as making adjustments to the Ultraplot package to improve compatibility!
+
 #### Future Roadmap
 
 With the release of `v3.x`, this project has achieved full coverage of the "main" map elements I think are necessary.

{matplotlib_map_utils-3.1.0 → matplotlib_map_utils-3.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "matplotlib-map-utils"
-version = "3.1.0"
+version = "3.1.2"
 authors = [
   { name="David Moss", email="davidmoss1221@gmail.com" },
 ]
@@ -29,6 +29,17 @@ exclude = ["matplotlib_map_utils.scratch*"]
 [tool.setuptools.package-data]
 "matplotlib_map_utils.utils" = ["*.json"]
 
+[dependency-groups]
+dev = [
+    "contextily>=1.6.2",
+    "geopandas>=1.1.1",
+    "ipykernel>=6.30.1",
+    "jupyter>=1.1.1",
+    "notebook>=7.4.7",
+    "pip>=25.2",
+    "pygris>=0.2.0",
+]
+
 [project.urls]
 "Homepage" = "https://github.com/moss-xyz/matplotlib-map-utils/"
 "Bug Tracker" = "https://github.com/moss-xyz/matplotlib-map-utils/issues"