matplotlib-map-utils 2.1.0__py3-none-any.whl → 3.0.1__py3-none-any.whl

matplotlib_map_utils/core/north_arrow.py

@@ -15,14 +15,10 @@ import numpy
 import cartopy
 import pyproj
 # Graphical packages
-import matplotlib
 import matplotlib.artist
-import matplotlib.pyplot
 import matplotlib.patches
 import matplotlib.patheffects
 import matplotlib.offsetbox
-# matplotlib's useful validation functions
-import matplotlib.rcsetup
 # The types we use in this script
 from typing import Literal
 # The information contained in our helper scripts (validation and defaults)

matplotlib_map_utils/core/scale_bar.py

@@ -9,27 +9,21 @@
 import warnings
 import math
 import copy
-import re
 # Math packages
 import numpy
 # Geo packages
-import cartopy
 import pyproj
 from great_circle_calculator.great_circle_calculator import distance_between_points
 # Graphical packages
 import PIL.Image
-import matplotlib
 import matplotlib.artist
 import matplotlib.lines
 import matplotlib.pyplot
 import matplotlib.patches
 import matplotlib.patheffects
 import matplotlib.offsetbox
-import matplotlib.transforms
 import matplotlib.font_manager
 from matplotlib.backends.backend_agg import FigureCanvasAgg
-# matplotlib's useful validation functions
-import matplotlib.rcsetup
 # The types we use in this script
 from typing import Literal
 # The information contained in our helper scripts (validation and defaults)
@@ -286,6 +280,13 @@ def scale_bar(ax, draw=True, style: Literal["ticks","boxes"]="boxes",
     ##### CONFIG #####
 
     # Getting the config for the bar (length, text, divs, etc.)
+    if draw:
+        ax.get_figure().draw_without_rendering()
+
+    # window = ax.get_window_extent()
+    # tight = ax.patch.get_tightbbox()
+    # print(f"{draw} Window: width {round(window.width,2)} ({round(ax.get_figure().dpi_scale_trans.inverted().transform([window.width,0])[0],2)}), height {round(window.height,2)} ({round(ax.get_figure().dpi_scale_trans.inverted().transform([0,window.height])[1],2)})")
+    # print(f"{draw} Tight: width {round(tight.width,2)} ({round(ax.get_figure().dpi_scale_trans.inverted().transform([tight.width,0])[0],2)}), height {round(tight.height,2)} ({round(ax.get_figure().dpi_scale_trans.inverted().transform([0,tight.height])[1],2)})")
     bar_max, bar_length, units_label, major_div, minor_div = _config_bar(ax, _bar)
 
     # Getting the config for the segments (width, label, etc.)
@@ -458,7 +459,6 @@ def scale_bar(ax, draw=True, style: Literal["ticks","boxes"]="boxes",
 
     # AOB will contain the final artist
     aob_box = matplotlib.offsetbox.AnchoredOffsetbox(loc="center", child=major_pack, frameon=False, pad=0, borderpad=0)
-
     # Function that will handle invisibly rendering our object, returning an image
     img_scale_bar = _render_as_image(fig_temp, ax_temp, aob_box, _bar["rotation"])
 
@@ -647,6 +647,11 @@ def _config_bar(ax, bar):
     # Literally just getting the figure for the passed axis
 
     fig = ax.get_figure()
+    # fig.draw_without_rendering()
+    # Sets the canvas for the figure to AGG (Anti-Grain Geometry)
+    # canvas = FigureCanvasAgg(fig)
+    # Draws the figure onto the canvas
+    # canvas.draw()
     
     ## ROTATION ##
     # Calculating if the rotation is vertical or horizontal
@@ -657,15 +662,15 @@ def _config_bar(ax, bar):
     # Finding the max length and optimal divisions of the scale bar
 
     # Finding the dimensions of the axis and the limits
-    # get_tightbbox() returns values in pixel coordinates
+    # get_window_extent() returns values in pixel coordinates
     # so dividing by dpi gets us the inches of the axis
     # Vertical scale bars are oriented against the y-axis (height)
     if bar_vertical==True:
-        ax_dim = ax.patch.get_tightbbox().height / fig.dpi
+        ax_dim = ax.patch.get_window_extent().height / fig.dpi
         min_lim, max_lim = ax.get_ylim()
     # Horizontal scale bars are oriented against the x-axis (width)
     else:
-        ax_dim = ax.patch.get_tightbbox().width / fig.dpi
+        ax_dim = ax.patch.get_window_extent().width / fig.dpi
         min_lim, max_lim = ax.get_xlim()
     # This calculates the range from max to min on the axis of interest
     ax_range = abs(max_lim - min_lim)
@@ -1017,7 +1022,7 @@ def _temp_figure(ax, axis=False, visible=False):
     # Getting the figure of the provided axis
     fig = ax.get_figure()
     # Getting the dimensions of the axis
-    ax_bbox = ax.patch.get_tightbbox()
+    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

matplotlib_map_utils/defaults/inset_map.py

@@ -0,0 +1,67 @@
+#################################################################
+# defaults/inset_map.py contains default values for the InsetMaps
+# at difference plot sizes (xsmall to xlarge)
+# see their corresponding sizes under each default heading
+#################################################################
+
+# The main variables that update are the following:
+# inset map: size, pad
+# labels: sep, style
+# units: sep
+# text: fontsize, stroke_width (also changes labels and units)
+# aob: pad, borderpad
+
+## X-SMALL DEFAULTS
+# Should work well for ~A8ish paper (2 to 3 inches, or 5 to 8 cm)
+
+# Map
+_INSET_MAP_XS = {
+    "size":0.5,
+    "pad":0.05,
+}
+
+## SMALL DEFAULTS
+# Should work well for ~A6 paper (4 to 6 inches, or 11 to 15 cm)
+
+# Map
+_INSET_MAP_SM = {
+    "size":1,
+    "pad":0.1,
+}
+
+## MEDIUM DEFAULTS
+# Should work well for ~A4/Letter paper (8 to 12 inches, or 21 to 30 cm)
+
+# Map
+_INSET_MAP_MD = {
+    "size":2,
+    "pad":0.25,
+}
+
+## LARGE DEFAULTS
+# Should work well for ~A2 paper (16 to 24 inches, or 42 to 60 cm)
+
+# Map
+_INSET_MAP_LG = {
+    "size":4,
+    "pad":0.5,
+}
+
+## X-LARGE DEFAULTS
+# Should work well for ~A0/Poster paper (33 to 47 inches, or 85 to 120 cm)
+
+# Map
+_INSET_MAP_XL = {
+    "size":8,
+    "pad":1,
+}
+
+## CONTAINER
+# This makes an easy-to-call dictionary of all the defaults we've set, for easy unpacking by the set_size function
+_DEFAULTS_IM = {
+    "xs":[_INSET_MAP_XS],
+    "sm":[_INSET_MAP_SM],
+    "md":[_INSET_MAP_MD],
+    "lg":[_INSET_MAP_LG],
+    "xl":[_INSET_MAP_XL],
+}

matplotlib_map_utils/validation/functions.py

@@ -20,7 +20,7 @@ def _validate_list(prop, val, list, none_ok=False):
         raise ValueError(f"'{val}' is not a valid value for {prop}, please provide a value in this list: {list}")
     return val
 
-def _validate_range(prop, val, min, max, none_ok=False):
+def _validate_range(prop, val, min, max=None, none_ok=False):
     if none_ok==False and val is None:
         raise ValueError(f"None is not a valid value for {prop}, please provide a value between {min} and {max}")
     elif none_ok==True and val is None:
@@ -69,7 +69,7 @@ def _validate_tuple(prop, val, length, types, none_ok=False):
         raise ValueError(f"None is not a valid value for {prop}, please provide a tuple of length {length} instead")
     elif none_ok==True and val is None:
         return val
-    elif type(val)!=tuple:
+    elif not isinstance(val, (tuple, list)):
         raise ValueError(f"{val} is not a valid value for {prop}, please provide a tuple of length {length} instead")
     elif len(val)!=length:
         raise ValueError(f"{val} is not a valid value for {prop}, please provide a tuple of length {length} instead")
@@ -117,7 +117,7 @@ def _validate_crs(prop, val, rotation_dict, none_ok=False):
         try:
             val = pyproj.CRS.from_user_input(val)
         except:
-            raise Exception(f"Invalid CRS supplied ({val}), please provide a valid CRS input for PyProj instead")
+            raise Exception(f"Invalid CRS supplied ({val}), please provide a valid CRS input that PyProj can use instead")
     return val
 
 # A simpler validation function for CRSs
@@ -128,14 +128,14 @@ def _validate_projection(prop, val, none_ok=False):
         try:
             val = pyproj.CRS.from_user_input(val)
         except:
-            raise Exception(f"Invalid CRS supplied ({val}), please provide a valid CRS input for PyProj instead")
+            raise Exception(f"Invalid CRS supplied ({val}) for {prop}, please provide a valid CRS input that PyProj can use instead")
     return val    
 
-# It is specifically to apply another validation function to the items in a list 
+# This is specifically to apply another validation function to the items in a list 
 # Ex. if we want to validate a LIST of colors instead of a single color
 def _validate_iterable(prop, val, func, kwargs=None):
     # Making sure we wrap everything in a list
-    if type(val) not in [tuple, list]:
+    if not isinstance(val, (tuple, list)):
         val = [val]
     # Then, we apply our validation func with optional kwargs to each item in said list, relying on it to return an error value
     if kwargs is not None:
@@ -148,21 +148,57 @@ def _validate_iterable(prop, val, func, kwargs=None):
             v = func(v)
         return val
     
-# This is specifically to apply multiple validation functions to a value, if needed
+# This is to check for the structure of a dictionary-like object 
+def _validate_keys(prop, val, keys, none_ok=False):
+    if none_ok==False and val is None:
+        raise ValueError(f"None is not a valid value for {prop}, please provide a dictionary with keys {keys} instead")
+    elif none_ok==True and val is None:
+        return val
+    elif not isinstance(val, (dict)):
+        raise ValueError(f"{val} is not a valid value for {prop}, please provide a dictionary with keys {keys} instead")
+    else:
+        for k in val.keys():
+            if k not in keys:
+                raise ValueError(f"{k} is not a valid key for the items in {prop}, please provide a dictionary with keys {keys} instead")
+    return val
+
+# This is to apply multiple validation functions to a value, if needed - only one needs to pass
 # Ex. If an item can be a string OR a list of strings, we can use this to validate it
-# "labels":{"func":_validate_multiple, "kwargs":{"funcs":[_validate_type, _validate_list], "kwargs":[{"match":str, "none_ok":True}, {"list":["major","first_last","minor_all","minor_first"], "none_ok":True}]}}, # any string or any item in the list
-def _validate_multiple(prop, val, funcs, kwargs):
+def _validate_or(prop, val, funcs, kwargs):
+    success = False
     # Simply iterate through each func and kwarg
     for f,k in zip(funcs,kwargs):
         # We wrap the attempts in a try block to suppress the errors
         try:
-            v = f(prop=prop, val=v, **k)
+            val = f(prop=prop, val=val, **k)
              # If we pass, we can stop here and return the value
-            return val
+            success = True 
+            break
         except:
-            continue
-    # If we didn't return a value and exit the loop yet, then the passed value is incorrect, as we raise an error
-    raise ValueError(f"{val} is not a valid value for {prop}, please provide check the documentation")
+            pass
+    if success == False:
+        # If we didn't return a value and exit the loop yet, then the passed value is incorrect, as we raise an error
+        raise ValueError(f"{val} is not a valid value for {prop}, please check the documentation")
+    else:
+        return val
+
+# This is the same, but ALL need to pass
+def _validate_and(prop, val, funcs, kwargs):
+    success = True
+    # Simply iterate through each func and kwarg
+    for f,k in zip(funcs,kwargs):
+        # We wrap the attempts in a try block to suppress the errors
+        try:
+            val = f(prop=prop, val=val, **k)
+        except:
+             # If we fail, we can stop here and return the value
+            success = False
+            break
+    if success == False:
+        # If we didn't return a value and exit the loop yet, then the passed value is incorrect, as we raise an error
+        raise ValueError(f"{val} is not a valid value for {prop}, please check the documentation")
+    else:
+        return val
 
 # This final one is used for keys that are not validated
 def _skip_validation(val, none_ok=False):
@@ -221,7 +257,7 @@ def _validate_dict(input_dict, default_dict, functions, to_validate=None, return
 def _validate(validate_dict, prop, val, return_val=True, kwargs={}):
     fd = validate_dict[prop]
     func = fd["func"]
-    # Our custom functions always have this dictionary key in them, so we know what form they take
+    # Most of our custom functions always have this dictionary key in them, so we know what form they take
     if "kwargs" in fd:
         val = func(prop=prop, val=val, **(fd["kwargs"] | kwargs))
     # The matplotlib built-in functions DON'T have that, and only ever take the one value

matplotlib_map_utils/validation/inset_map.py

@@ -0,0 +1,88 @@
+############################################################
+# validation/inset_map.py contains all the main objects
+# for checking inputs passed to class definitions
+############################################################
+
+### IMPORTING PACKAGES ###
+
+# Geo packages
+import matplotlib.axes
+import pyproj
+# Graphical packages
+import matplotlib
+# matplotlib's useful validation functions
+import matplotlib.rcsetup
+# The types we use in this script
+from typing import TypedDict, Literal
+# Finally, the validation functions
+from . import functions as vf
+
+### ALL ###
+# This code tells other packages what to import if not explicitly stated
+__all__ = [
+    "_TYPE_INSET", "_VALIDATE_INSET",
+    "_TYPE_EXTENT", "_VALIDATE_EXTENT",
+    "_TYPE_DETAIL", "_VALIDATE_DETAIL",
+]
+
+### TYPE HINTS ###
+# This section of the code is for defining structured dictionaries and lists
+# for the inputs necessary for object creation we've created (such as the style dictionaries)
+# so that intellisense can help with autocompletion
+
+class _TYPE_INSET(TypedDict, total=False):
+    size: int | float | tuple[int | float, int | float] | list[int | float, int | float] # each int or float should be between 0 and inf
+    pad: int | float | tuple[int | float, int | float] | list[int | float, int | float] # each int or float should be between 0 and inf
+    coords: tuple[int | float, int | float] | list[int | float, int | float] # each int or float should be between -inf and inf
+
+class _TYPE_EXTENT(TypedDict, total=False):
+    pax: matplotlib.axes.Axes # any Matplotlib Axes
+    bax: matplotlib.axes.Axes # any Matplotlib Axes
+    pcrs: str | int | pyproj.CRS # should be a valid cartopy or pyproj crs, or a string or int that can be converted to that
+    bcrs: str | int | pyproj.CRS # should be a valid cartopy or pyproj crs, or a string or int that can be converted to that
+    straighten: bool # either true or false
+    pad: float | int # any positive float or integer
+    plot: bool # either true or false
+    to_return: Literal["shape","patch","fig","ax"] | None # any item in the list, or None if nothing should be returned
+    facecolor: str # a color to use for the face of the box
+    linecolor: str # a color to use for the edge of the box
+    alpha: float | int # any positive float or integer
+    linewidth: float | int # any positive float or integer
+
+class _TYPE_DETAIL(TypedDict, total=False):
+    to_return: Literal["connectors", "lines"] | None # any item in the list, or None if nothing should be returned
+    connector_color: str # a color to use for the face of the box
+    connector_width: float | int # any positive float or integer
+
+### VALIDITY DICTS ###
+# These compile the functions in validation/functions, as well as matplotlib's built-in validity functions
+# into dictionaries that can be used to validate all the inputs to a dictionary at once
+
+_VALIDATE_INSET = {
+    "location":{"func":vf._validate_list, "kwargs":{"list":["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]}},
+    "size":{"func":vf._validate_or, "kwargs":{"funcs":[vf._validate_range, vf._validate_and], "kwargs":[{"min":0, "none_ok":True}, {"funcs":[vf._validate_tuple, vf._validate_iterable], "kwargs":[{"length":2, "types":[float, int]}, {"func":vf._validate_range, "kwargs":{"min":0}}]}]}}, # between 0 and inf, or a two-tuple of (x,y) size, each between 0 and inf
+    "pad":{"func":vf._validate_or, "kwargs":{"funcs":[vf._validate_range, vf._validate_and], "kwargs":[{"min":0, "none_ok":True}, {"funcs":[vf._validate_tuple, vf._validate_iterable], "kwargs":[{"length":2, "types":[float, int]}, {"func":vf._validate_range, "kwargs":{"min":0}}]}]}}, # between 0 and inf, or a two-tuple of (x,y) size, each between 0 and inf
+    "coords":{"func":vf._validate_tuple, "kwargs":{"length":2, "types":[float, int], "none_ok":True}}, # a two-tuple of coordinates where you want to place the inset map
+    "to_plot":{"func":vf._validate_iterable, "kwargs":{"func":vf._validate_keys, "kwargs":{"keys":["data","kwargs"], "none_ok":True}}}, # a list of dictionaries, where each contains "data" and "kwargs" keys
+}
+
+_VALIDATE_EXTENT = {
+    "pax":{"func":vf._validate_type, "kwargs":{"match":matplotlib.axes.Axes}}, # any Matplotlib Axes
+    "bax":{"func":vf._validate_type, "kwargs":{"match":matplotlib.axes.Axes}}, # any Matplotlib Axes
+    "pcrs":{"func":vf._validate_projection, "kwargs":{"none_ok":False}}, # any valid projection input for PyProj
+    "bcrs":{"func":vf._validate_projection, "kwargs":{"none_ok":False}}, # any valid projection input for PyProj
+    "straighten":{"func":vf._validate_type, "kwargs":{"match":bool}}, # true or false
+    "pad":{"func":vf._validate_range, "kwargs":{"min":0}}, # any positive number
+    "plot":{"func":vf._validate_type, "kwargs":{"match":bool}}, # true or false
+    "facecolor":{"func":matplotlib.rcsetup.validate_color}, # any color value for matplotlib
+    "linecolor":{"func":matplotlib.rcsetup.validate_color}, # any color value for matplotlib
+    "alpha":{"func":vf._validate_range, "kwargs":{"min":0}}, # any positive number
+    "linewidth":{"func":vf._validate_range, "kwargs":{"min":0}}, # any positive number
+    "to_return":{"func":vf._validate_list, "kwargs":{"list":["shape", "patch", "fig", "ax"], "none_ok":True}}, # any value in this list
+}
+
+_VALIDATE_DETAIL = {
+    "to_return":{"func":vf._validate_list, "kwargs":{"list":["connectors", "lines"], "none_ok":True}}, # any value in this list
+    "connector_color":{"func":matplotlib.rcsetup.validate_color}, # any color value for matplotlib
+    "connector_width":{"func":vf._validate_range, "kwargs":{"min":0}}, # any positive number
+}

matplotlib_map_utils/validation/north_arrow.py

@@ -90,7 +90,7 @@ class _TYPE_ROTATION(TypedDict, total=False):
     coords: Tuple[float | int, float | int] # only required if degrees is None: should be a tuple of coordinates in the relevant reference window
 
 ### VALIDITY DICTS ###
-# These compile the functions above^, as well as matplotlib's built-in validity functions
+# These compile the functions in validation/functions, as well as matplotlib's built-in validity functions
 # into dictionaries that can be used to validate all the inputs to a dictionary at once
 
 _VALIDATE_PRIMARY = {

matplotlib_map_utils/validation/scale_bar.py

@@ -7,12 +7,10 @@
 
 # Geo packages
 import pyproj
-# Graphical packages
-import matplotlib
 # matplotlib's useful validation functions
 import matplotlib.rcsetup
 # The types we use in this script
-from typing import Tuple, TypedDict, Literal, get_args
+from typing import TypedDict, Literal, get_args
 # Finally, the validation functions
 from . import functions as vf
 
@@ -161,7 +159,7 @@ class _TYPE_AOB(TypedDict, total=False):
     # bbox_transform: None # NOTE: currently unvalidated, use at your own risk!
 
 ### VALIDITY DICTS ###
-# These compile the functions above^, as well as matplotlib's built-in validity functions
+# These compile the functions in validation/functions, as well as matplotlib's built-in validity functions
 # into dictionaries that can be used to validate all the inputs to a dictionary at once
 
 _VALIDATE_PRIMARY = {
@@ -173,7 +171,7 @@ _VALID_BAR_TICK_LOC = get_args(_TYPE_BAR.__annotations__["tick_loc"])
 _VALID_BAR_MINOR_TYPE = get_args(_TYPE_BAR.__annotations__["minor_type"]) 
 
 _VALIDATE_BAR = {
-    "projection":{"func":vf._validate_projection}, # must be a valid CRS
+    "projection":{"func":vf._validate_projection, "kwargs":{"none_ok":False}}, # must be a valid CRS
     "unit":{"func":vf._validate_list, "kwargs":{"list":list(units_standard.keys()), "none_ok":True}}, # any of the listed unit values are accepted
     "rotation":{"func":vf._validate_range, "kwargs":{"min":-360, "max":360, "none_ok":True}}, # between -360 and 360 degrees
     "max":{"func":vf._validate_range, "kwargs":{"min":0, "max":None, "none_ok":True}}, # between 0 and inf