matplotlib-map-utils 1.0.2__py3-none-any.whl → 2.0.0__py3-none-any.whl

matplotlib_map_utils/defaults/__init__.py

@@ -0,0 +1,4 @@
+from .north_arrow import _DEFAULTS_NA
+from .scale_bar import _DEFAULTS_SB
+
+__all__ = ["_DEFAULTS_NA","_DEFAULTS_SB"]

matplotlib_map_utils/{defaults.py → defaults/north_arrow.py}

@@ -1,8 +1,8 @@
-############################################################
-# defaults.py contains default values for the artists
+#####################################################################
+# defaults/north_arrow.py contains default values for the NorthArrows
 # at difference plot sizes (xsmall to xlarge)
 # see their corresponding sizes under each default heading
-############################################################
+#####################################################################
 
 # The main variables that update are the following:
 # base: scale, linewidth
@@ -407,7 +407,7 @@ _AOB_XL = {
 
 ## CONTAINER
 # This makes an easy-to-call dictionary of all the defaults we've set, for easy unpacking by the set_size function
-_DEFAULT_CONTAINER = {
+_DEFAULTS_NA = {
     "xs":[_SCALE_XS, _BASE_XS, _FANCY_XS, _LABEL_XS, _SHADOW_XS, _PACK_XS, _AOB_XS],
     "sm":[_SCALE_SM, _BASE_SM, _FANCY_SM, _LABEL_SM, _SHADOW_SM, _PACK_SM, _AOB_SM],
     "md":[_SCALE_MD, _BASE_MD, _FANCY_MD, _LABEL_MD, _SHADOW_MD, _PACK_MD, _AOB_MD],

matplotlib_map_utils/defaults/scale_bar.py

@@ -0,0 +1,377 @@
+#################################################################
+# defaults/scale_bar.py contains default values for the ScaleBars
+# at difference plot sizes (xsmall to xlarge)
+# see their corresponding sizes under each default heading
+#################################################################
+
+# The main variables that update are the following:
+# bar: height, edgewidth, tickwidth
+# 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)
+# The arrow will appear to be ~1/10 of an inch in height
+
+# Bar
+_BAR_XS = {
+    "projection":None,
+    "unit":None,
+    "rotation":0,
+    "max":None,
+    "length":None,
+    "height":0.05, # changed
+    "reverse":False,
+    "major_div":None,
+    "minor_div":None,
+    "minor_frac":0.66,
+    "minor_type":"none",
+    "facecolors":["black","white"],
+    "edgecolors":"black",
+    "edgewidth":0.5, # changed
+    "tick_loc":"above",
+    "basecolors":["black"],
+    "tickcolors":["black"],
+    "tickwidth":0.5 # changed
+}
+
+# Labels
+_LABELS_XS = {
+    "labels":None,
+    "format":".2f",
+    "format_int":True,
+    "style":"first_last", # changed
+    "loc":"above",
+    "pad":0,
+    "sep":1.5, # changed
+}
+
+# Units
+_UNITS_XS = {
+    "label":None,
+    "loc":"bar",
+    "pad":0,
+    "sep":1.5, # changed
+}
+
+# Text
+_TEXT_XS = {
+    "fontsize":4, # changed
+    "textcolor":"black",
+    "fontfamily":"sans-serif",
+    "fontstyle":"normal",
+    "fontweight":"regular",
+    "stroke_width":0.5, # changed
+    "stroke_color":"white",
+    "rotation":None,
+    "rotation_mode":"anchor",
+}
+
+# AOB
+_AOB_XS = {
+    "facecolor":None,
+    "edgecolor":None,
+    "alpha":None,
+    "pad":0.1, # changed
+    "borderpad":0.1, # changed
+    "prop":"medium",
+    "frameon":False,
+    "bbox_to_anchor":None,
+    "bbox_transform":None
+}
+
+## SMALL DEFAULTS
+# Should work well for ~A6 paper (4 to 6 inches, or 11 to 15 cm)
+# The arrow will appear to be ~1/4 of an inch in height
+
+# Bar
+_BAR_SM = {
+    "projection":None,
+    "unit":None,
+    "rotation":0,
+    "max":None,
+    "length":None,
+    "height":0.075, # changed
+    "reverse":False,
+    "major_div":None,
+    "minor_div":None,
+    "minor_frac":0.66,
+    "minor_type":"none",
+    "facecolors":["black","white"],
+    "edgecolors":"black",
+    "edgewidth":0.75, # changed
+    "tick_loc":"above",
+    "basecolors":["black"],
+    "tickcolors":["black"],
+    "tickwidth":0.75 # changed
+}
+
+# Labels
+_LABELS_SM = {
+    "labels":None,
+    "format":".2f",
+    "format_int":True,
+    "style":"first_last", # changed
+    "loc":"above",
+    "pad":0,
+    "sep":3, # changed
+}
+
+# Units
+_UNITS_SM = {
+    "label":None,
+    "loc":"bar",
+    "pad":0,
+    "sep":3, # changed
+}
+
+# Text
+_TEXT_SM = {
+    "fontsize":6, # changed
+    "textcolor":"black",
+    "fontfamily":"sans-serif",
+    "fontstyle":"normal",
+    "fontweight":"regular",
+    "stroke_width":0.5, # changed
+    "stroke_color":"white",
+    "rotation":None,
+    "rotation_mode":"anchor",
+}
+
+# AOB
+_AOB_SM = {
+    "facecolor":None,
+    "edgecolor":None,
+    "alpha":None,
+    "pad":0.33, # changed
+    "borderpad":0.33, # changed
+    "prop":"medium",
+    "frameon":False,
+    "bbox_to_anchor":None,
+    "bbox_transform":None
+}
+
+## MEDIUM DEFAULTS
+# Should work well for ~A4/Letter paper (8 to 12 inches, or 21 to 30 cm)
+# The arrow will appear to be ~ 1/2 an inch or ~1 cm in height
+
+# Bar
+_BAR_MD = {
+    "projection":None,
+    "unit":None,
+    "rotation":0,
+    "max":None,
+    "length":None,
+    "height":0.1, # changed
+    "reverse":False,
+    "major_div":None,
+    "minor_div":None,
+    "minor_frac":0.66,
+    "minor_type":"first",
+    "facecolors":["black","white"],
+    "edgecolors":"black",
+    "edgewidth":1, # changed
+    "tick_loc":"above",
+    "basecolors":["black"],
+    "tickcolors":["black"],
+    "tickwidth":1.5 # changed
+}
+
+# Labels
+_LABELS_MD = {
+    "labels":None,
+    "format":".2f",
+    "format_int":True,
+    "style":"major",
+    "loc":"above",
+    "pad":0,
+    "sep":5, # changed
+}
+
+# Units
+_UNITS_MD = {
+    "label":None,
+    "loc":"bar",
+    "pad":0,
+    "sep":5, # changed
+}
+
+# Text
+_TEXT_MD = {
+    "fontsize":12, # changed
+    "textcolor":"black",
+    "fontfamily":"sans-serif",
+    "fontstyle":"normal",
+    "fontweight":"regular",
+    "stroke_width":1, # changed
+    "stroke_color":"white",
+    "rotation":None,
+    "rotation_mode":"anchor",
+}
+
+# AOB
+_AOB_MD = {
+    "facecolor":None,
+    "edgecolor":None,
+    "alpha":None,
+    "pad":0.5, # changed
+    "borderpad":0.5, # changed
+    "prop":"medium",
+    "frameon":False,
+    "bbox_to_anchor":None,
+    "bbox_transform":None
+}
+
+## LARGE DEFAULTS
+# Should work well for ~A2 paper (16 to 24 inches, or 42 to 60 cm)
+# The arrow will appear to be ~an inch in height
+
+# Bar
+_BAR_LG = {
+    "projection":None,
+    "unit":None,
+    "rotation":0,
+    "max":None,
+    "length":None,
+    "height":0.2, # changed
+    "reverse":False,
+    "major_div":None,
+    "minor_div":None,
+    "minor_frac":0.66,
+    "minor_type":"first",
+    "facecolors":["black","white"],
+    "edgecolors":"black",
+    "edgewidth":2, # changed
+    "tick_loc":"above",
+    "basecolors":["black"],
+    "tickcolors":["black"],
+    "tickwidth":3 # changed
+}
+
+# Labels
+_LABELS_LG = {
+    "labels":None,
+    "format":".2f",
+    "format_int":True,
+    "style":"major",
+    "loc":"above",
+    "pad":0,
+    "sep":8, # changed
+}
+
+# Units
+_UNITS_LG = {
+    "label":None,
+    "loc":"bar",
+    "pad":0,
+    "sep":8, # changed
+}
+
+# Text
+_TEXT_LG = {
+    "fontsize":24, # changed
+    "textcolor":"black",
+    "fontfamily":"sans-serif",
+    "fontstyle":"normal",
+    "fontweight":"regular",
+    "stroke_width":2, # changed
+    "stroke_color":"white",
+    "rotation":None,
+    "rotation_mode":"anchor",
+}
+
+# AOB
+_AOB_LG = {
+    "facecolor":None,
+    "edgecolor":None,
+    "alpha":None,
+    "pad":1, # changed
+    "borderpad":1, # changed
+    "prop":"medium",
+    "frameon":False,
+    "bbox_to_anchor":None,
+    "bbox_transform":None
+}
+
+## X-LARGE DEFAULTS
+# Should work well for ~A0/Poster paper (33 to 47 inches, or 85 to 120 cm)
+# The arrow will appear to be ~2 inches in height
+
+# Bar
+_BAR_XL = {
+    "projection":None,
+    "unit":None,
+    "rotation":0,
+    "max":None,
+    "length":None,
+    "height":0.4, # changed
+    "reverse":False,
+    "major_div":None,
+    "minor_div":None,
+    "minor_frac":0.66,
+    "minor_type":"first",
+    "facecolors":["black","white"],
+    "edgecolors":"black",
+    "edgewidth":4, # changed
+    "tick_loc":"above",
+    "basecolors":["black"],
+    "tickcolors":["black"],
+    "tickwidth":5 # changed
+}
+
+# Labels
+_LABELS_XL = {
+    "labels":None,
+    "format":".2f",
+    "format_int":True,
+    "style":"major",
+    "loc":"above",
+    "pad":0,
+    "sep":12, # changed
+}
+
+# Units
+_UNITS_XL = {
+    "label":None,
+    "loc":"bar",
+    "pad":0,
+    "sep":12, # changed
+}
+
+# Text
+_TEXT_XL = {
+    "fontsize":48, # changed
+    "textcolor":"black",
+    "fontfamily":"sans-serif",
+    "fontstyle":"normal",
+    "fontweight":"regular",
+    "stroke_width":4, # changed
+    "stroke_color":"white",
+    "rotation":None,
+    "rotation_mode":"anchor",
+}
+
+# AOB
+_AOB_XL = {
+    "facecolor":None,
+    "edgecolor":None,
+    "alpha":None,
+    "pad":2, # changed
+    "borderpad":2, # changed
+    "prop":"medium",
+    "frameon":False,
+    "bbox_to_anchor":None,
+    "bbox_transform":None
+}
+
+## CONTAINER
+# This makes an easy-to-call dictionary of all the defaults we've set, for easy unpacking by the set_size function
+_DEFAULTS_SB = {
+    "xs":[_BAR_XS, _LABELS_XS, _UNITS_XS, _TEXT_XS, _AOB_XS],
+    "sm":[_BAR_SM, _LABELS_SM, _UNITS_SM, _TEXT_SM, _AOB_SM],
+    "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/__init__.py

@@ -0,0 +1,2 @@
+from .north_arrow import *
+from .scale_bar import *

matplotlib_map_utils/validation/functions.py

@@ -0,0 +1,231 @@
+# Default packages
+import warnings
+# Geo packages
+import pyproj
+# matplotlib's useful validation functions
+import matplotlib.rcsetup
+
+### VALIDITY CHECKS ###
+# Functions and variables used for validating inputs for classes
+# All have a similar form, taking in the name of the property (prop), the value (val)
+# some parameters to check against (min/max, list, type, etc.),
+# and whether or not None is acceptable value
+
+def _validate_list(prop, val, list, 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 in this list: {list}")
+    elif none_ok==True and val is None:
+        return val
+    elif not val in list:
+        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):
+    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:
+        return val
+    elif type(val) != int and type(val) != float:
+        raise ValueError(f"The supplied type is not valid for {prop}, please provide a float or integer between {min} and {max}")
+    elif max is not None:
+        if not val >= min and not val <= max:
+            raise ValueError(f"'{val}' is not a valid value for {prop}, please provide a value between {min} and {max}")
+    elif max is None:
+        if not val >= min:
+            raise ValueError(f"'{val}' is not a valid value for {prop}, please provide a value greater than {min}")
+    return val
+
+def _validate_type(prop, val, match, none_ok=False):
+    if none_ok==False and val is None:
+        raise ValueError(f"None is not a valid value for {prop}, please provide an object of type {match}")
+    elif none_ok==True and val is None:
+        return val
+    elif not type(val)==match:
+        raise ValueError(f"'{val}' is not a valid value for {prop}, please provide an object of type {match}")
+    return val
+
+def _validate_types(prop, val, matches, none_ok=False):
+    if none_ok==False and val is None:
+        raise ValueError(f"None is not a valid value for {prop}, please provide an object of type {matches}")
+    elif none_ok==True and val is None:
+        return val
+    elif not type(val) in matches:
+        raise ValueError(f"'{val}' is not a valid value for {prop}, please provide an object of type {matches}")
+    return val
+
+def _validate_coords(prop, val, numpy_type, dims, none_ok=False):
+    if none_ok==False and val is None:
+        raise ValueError(f"None is not a valid value for {prop}, please provide an object of type {numpy_type}")
+    elif none_ok==True and val is None:
+        return val
+    elif not type(val)==numpy_type:
+        raise ValueError(f"'{val}' is not a valid value for {prop}, please provide an object of type {numpy_type}")
+    elif not val.ndim==dims:
+        raise ValueError(f"'{val}' is not a valid value for {prop}, please provide a numpy array with {dims} dimensions")
+    return val
+
+def _validate_tuple(prop, val, length, types, 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 tuple of length {length} instead")
+    elif none_ok==True and val is None:
+        return val
+    elif type(val)!=tuple:
+        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")
+    else:
+        for item in val:
+            if type(item) not in types:
+                raise ValueError(f"{type(item)} is not a valid value for the items in {prop}, please provide a value of one of the following types: {types}")
+    return val
+
+def _validate_color_or_none(prop, val, 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 color string acceptable to matplotlib instead")
+    elif none_ok==True and val is None:
+        return val
+    else:
+        matplotlib.rcsetup.validate_color(val)
+    return val
+
+# NOTE: This one is a bit messy, particularly with the rotation module, but I can't think of a better way to do it...
+def _validate_crs(prop, val, rotation_dict, none_ok=False):
+    degrees = rotation_dict.get("degrees",None)
+    crs = rotation_dict.get("crs",None)
+    reference = rotation_dict.get("reference",None)
+    coords = rotation_dict.get("coords",None)
+    
+    if degrees is None:
+        if reference == "center":
+            if crs is None:
+                raise ValueError(f"If degrees is set to None, and reference is 'center', then a valid crs must be supplied")
+        else:
+            if crs is None or reference is None or coords is None:
+                raise ValueError(f"If degrees is set to None, then crs, reference, and coords cannot be None: please provide a valid input for each of these variables instead")
+    elif (type(degrees)==int or type(degrees)==float) and (crs is not None or reference is not None or coords is not None):
+            warnings.warn(f"A value for degrees was supplied; values for crs, reference, and coords will be ignored")
+            return val
+    else:
+        if none_ok==False and val is None:
+            raise ValueError(f"If degrees is set to None, then {prop} cannot be None: please provide a valid CRS input for PyProj instead")
+        elif none_ok==True and val is None:
+            return val
+    # This happens if (a) a value for CRS is supplied and (b) a value for degrees is NOT supplied
+    if type(val)==pyproj.CRS:
+        pass
+    else:
+        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")
+    return val
+
+# A simpler validation function for CRSs
+def _validate_projection(prop, val, none_ok=False):
+    if type(val)==pyproj.CRS:
+        pass
+    else:
+        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")
+    return val    
+
+# It 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]:
+        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:
+        for v in val:
+            v = func(prop=prop, val=v, **kwargs)
+        return val
+    # The matplotlib built-in functions DON'T have that, and only ever take the one value
+    else:
+        for v in val:
+            v = func(v)
+        return val
+    
+# This is specifically to apply multiple validation functions to a value, if needed
+# 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):
+    # 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)
+             # If we pass, we can stop here and return the value
+            return val
+        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")
+
+# This final one is used for keys that are not validated
+def _skip_validation(val, none_ok=False):
+    return val
+
+
+### MORE VALIDITY FUNCTIONS ###
+# These are more customized, and so are separated from the _validate_* functions above
+# Mainly, they can process the input dictionaries wholesale, as well as the individual functions in it
+def _validate_dict(input_dict, default_dict, functions, to_validate=None, return_clean=False, parse_false=True):
+    if input_dict == False:
+        if parse_false == True:
+            return None
+        else:
+            return False
+    elif input_dict is None or input_dict == True:
+        return default_dict
+    elif type(input_dict) != dict:
+        raise ValueError(f"A dictionary (NoneType) must be provided, please double-check your inputs")
+    else:
+        values = default_dict | input_dict
+        # Pre-checking that no invalid keys are passed
+        invalid = [key for key in values.keys() if key not in functions.keys() and key not in ["bbox_to_anchor", "bbox_transform"]]
+        if len(invalid) > 0:
+            print(f"Warning: Invalid keys detected ({invalid}). These will be ignored.")
+        # First, trimming our values to only those we need to validate
+        if to_validate == "input":
+            values = {key: val for key, val in values.items() if (key in input_dict.keys() and key in functions.keys())} # have to check against both here
+            functions = {key: val for key, val in functions.items() if key in values.keys()}
+        elif to_validate is not None:
+            values = {key: val for key, val in values.items() if key in to_validate}
+            functions = {key: val for key, val in functions.items() if key in values.keys()}
+        else:
+            values = {key: val for key, val in values.items() if key in functions.keys()}
+            functions = {key: val for key, val in functions.items() if key in values.keys()}
+        # Now, running the function with the necessary kwargs
+        for key,val in values.items():
+            fd = functions[key]
+            func = fd["func"]
+            # NOTE: This is messy but the only way to get the rotation value to the crs function
+            if key=="crs":
+                _ = func(prop=key, val=val, rotation_dict=values, **fd["kwargs"])
+            # NOTE: This is messy but the only way to check the projection dict without keywords
+            elif key=="projection":
+                _ = func(prop=key, val=val)
+            # Our custom functions always have this dictionary key in them, so we know what form they take
+            elif "kwargs" in fd:
+                _ = func(prop=key, val=val, **fd["kwargs"])
+            # The matplotlib built-in functions DON'T have that, and only ever take the one value
+            else:
+                _ = func(val)
+        if return_clean==True:
+            return values
+
+# This function can process the _VALIDATE dictionaries we established above, but for single variables at a time
+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
+    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
+    else:
+        val = func(val)
+    if return_val==True:
+        return val