matplotlib-map-utils 2.1.0__py3-none-any.whl → 3.0.0__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)

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

{matplotlib_map_utils-2.1.0.dist-info → matplotlib_map_utils-3.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matplotlib-map-utils
-Version: 2.1.0
+Version: 3.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/
@@ -8,6 +8,7 @@ Project-URL: Bug Tracker, https://github.com/moss-xyz/matplotlib-map-utils/issue
 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
@@ -16,13 +17,15 @@ Requires-Dist: cartopy>=0.23.0
 Requires-Dist: great-circle-calculator>=1.3.1
 Dynamic: license-file
 
-# matplotlib-map-utils
+![matplotlib_map_utils logo](matplotlib_map_utils/docs/assets/mmu_logo_w_elements.png)
  
 ---
 
-**Documentation**: See `docs` folder
+**Documentation:** See `docs` folder
 
-**Source Code**: [Available on GitHub](https://github.com/moss-xyz/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.
 
 ---
 
@@ -30,15 +33,23 @@ Dynamic: license-file
 
 `matplotlib_map_utils` is intended to be a package that provides various functions and objects that assist with the the creation of maps using [`matplotlib`](https://matplotlib.org/stable/).
 
-As of `v2.x` (the current version), this includes two tools and one utility: 
+As of `v3.x` (the current version), this includes three-ish elements: 
+
+* `north_arrow.py`, for adding a north arrow to a given plot. 
+
+* `scale_bar.py`, for adding a scale bar to a given plot. 
+
+* `inset_map.py`, for adding inset maps and detail/extent indicators to a given plot. 
 
-* `north_arrow.py`, which generates a high quality, context-aware north arrow for a given plot. 
+The three elements listed above are all intended to be high-resolution, easily modifiable, and context-aware, relative to your specific plot.
 
-* `scale_bar.py`, which generates a high quality, context-aware scale bar to a given plot. 
+This package also contains a single utility object:
 
 * `usa.py`, which contains a class that helps filter for states and territories within the USA based on given characteristics.
 
-Future releases (if the project is continued) might provide a similar tool inset maps, or other functions that I have created myself that give more control in the formatting of maps.
+Together, these allow for the easy creation of a map such as the following:
+
+![Map with all common elements added](matplotlib_map_utils/docs/assets/readme_bigmap.png)
 
 ---
 
@@ -62,7 +73,8 @@ The requirements for this package are:
 
 ### Package Structure
 
-The package is arrayed in the following way:
+<details>
+<summary><i>The package is arrayed in the following way:</i></summary>
 
 ```bash
 package_name/
@@ -70,17 +82,20 @@ package_name/
 │
 ├── core/
 │   ├── __init__.py
+│   ├── inset_map.py
 │   ├── north_arrow.py
 │   ├── scale_bar.py
 ├── validation/
 │   ├── __init__.py
 │   ├── functions.py
+│   └── inset_map.py
 │   ├── north_arrow.py
 │   └── scale_bar.py
 ├── defaults/
 │   ├── __init__.py
 │   ├── north_arrow.py
 │   └── scale_bar.py
+│   └── inset_map.py
 ├── utils/
 │   ├── __init__.py
 │   ├── usa.py
@@ -95,9 +110,13 @@ Where:
 
 * `defaults` contains default settings for each object at different paper sizes
 
+* `utils` contains utility functions and objects
+
+</details>
+
 ---
 
-### North Arrow
+### 🧭 North Arrow
 
 <details>
 <summary><i>Expand instructions</i></summary>
@@ -108,6 +127,8 @@ Importing the North Arrow functions and classes can be done like so:
 
 ```py
 from matplotlib_map_utils.core.north_arrow import NorthArrow, north_arrow
+from matplotlib_map_utils.core import NorthArrow, north_arrow # also valid
+from matplotlib_map_utils import NorthArrow, north_arrow # also valid
 ```
 
 The quickest way to add a single north arrow to a single plot is to use the `north_arrow` function:
@@ -171,7 +192,7 @@ Instructions for how to do so can be found in `docs\howto_north_arrow`.
 
 ---
 
-### Scale Bar
+### 📏 Scale Bar
 
 <details>
 <summary><i>Expand instructions</i></summary>
@@ -182,6 +203,8 @@ Importing the Scale Bar functions and classes can be done like so:
 
 ```py
 from matplotlib_map_utils.core.scale_bar import ScaleBar, scale_bar
+from matplotlib_map_utils.core import ScaleBar, scale_bar # also valid
+from matplotlib_map_utils import ScaleBar, scale_bar # also valid
 ```
 
 There are two available styles for the scale bars: `boxes` and `ticks`. The quickest way to add one to a single plot is to use the `scale_bar` function:
@@ -201,7 +224,7 @@ An object-oriented approach is also supported:
 fig, ax = matplotlib.pyplot.subplots(1,1, figsize=(5,5), dpi=150)
 # Adding a scale bar to the upper-right corner of the axis, in the same projection as whatever geodata you plotted
 # Here, we change the boxes to "ticks"
-sb = ScaleBar(location="upper right", style="boxes", bar={"projection":3857})
+sb = ScaleBar(location="upper right", style="ticks", bar={"projection":3857})
 # Adding the artist to the plot
 ax.add_artist(sb)
 ```
@@ -237,7 +260,67 @@ Refer to `docs\howto_scale_bar` for details on how to customize each facet of th
 
 ---
 
-### Utilities
+### 🗺️ Inset Map
+
+<details>
+<summary><i>Expand instructions</i></summary>
+
+#### Quick Start
+
+Importing the Inset Map functions and classes can be done like so:
+
+```py
+from matplotlib_map_utils.core.inset_map import InsetMap, inset_map, ExtentIndicator, indicate_extent, DetailIndicator, indicate_detail
+from matplotlib_map_utils.core import InsetMap, inset_map, ExtentIndicator, indicate_extent, DetailIndicator, indicate_detail # also valid
+from matplotlib_map_utils import InsetMap, inset_map, ExtentIndicator, indicate_extent, DetailIndicator, indicate_detail # also valid
+```
+
+The quickest way to add a single inset map to an existing plot is the `inset_map` function:
+
+```python
+# Setting up a plot
+fig, ax = matplotlib.pyplot.subplots(1,1, figsize=(5,5), dpi=150)
+# Adding an inset map to the upper-right corner of the axis
+iax = inset_map(ax=ax, location="upper right", size=0.75, pad=0, xticks=[], yticks=[])
+# You can now plot additional data to iax as desired
+```
+
+An object-oriented approach is also supported:
+
+```python
+# Setting up a plot
+fig, ax = matplotlib.pyplot.subplots(1,1, figsize=(5,5), dpi=150)
+# Creating an object for the inset map
+im = InsetMap(location="upper right", size=0.75, pad=0, xticks=[], yticks=[])
+# Adding the inset map template to the plot
+iax = im.create(ax=ax)
+# You can now plot additional data to iax as desired
+```
+
+Both of these will create an output like the following:
+
+![Example inset map](matplotlib_map_utils/docs/assets/readme_insetmap.png)
+
+#### Extent and Detail Indicators
+
+Inset maps can be paired with either an extent or detail indicator, to provide additional geographic context to the inset map
+
+```python
+indicate_extent(inset_axis, parent_axis, inset_crs, parent_crs, ...)
+indicate_detail(parent_axis, inset_axis, parent_crs, inset_crs, ...)
+```
+
+This will create an output like the following (extent indicator on the left, detail indicator on the right):
+
+![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>
+
+---
+
+### 🛠️ Utilities
 
 <details>
 <summary><i>Expand instructions</i></summary>
@@ -283,23 +366,31 @@ Two more projects assisted with the creation of this script:
 
 #### Releases
 
-- `v2.0.1`: Fixed a bug in the `dual_bars()` function that prevented empty dictionaries to be passed. Also added a warning when auto-calculated bar widths appear to be exceeding the dimension of the axis (usually occurs when the axis is <2 kilometeres or miles long, depending on the units selected).
+- `v1.0.x`: Initial releases featuring the North Arrow element, along with some minor bug fixes.
+
+- `v2.0.0`: Initial release of the Scale Bar element.
+
+- `v2.0.1`: Fixed a bug in the `dual_bars()` function that prevented empty dictionaries to be passed. Also added a warning when auto-calculated bar widths appear to be exceeding the dimension of the axis (usually occurs when the axis is <2 kilometers or miles long, depending on the units selected).
 
 - `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.
 
+- `v3.0.0`: Release of inset map and extent and detail indicator classes and functions.
+
 #### Future Roadmap
 
-With the release of `v2.x`, and the addition of **Scale Bar** tools, this project has achieved the two main objectives that I set out to.
+With the release of `v3.x`, this project has achieved full coverage of the "main" map elements I think are necessary.
 
 If I continue development of this project, I will be looking to add or fix the following features:
 
+* For all: switch to a system based on Pydantic for easier type validation
+
 * **North Arrow:** 
 
   * Copy the image-rendering functionality of the Scale Bar to allow for rotation of the entire object, label and arrow together
   
-  * Create more styles for the arrow, potentiallly including a compass rose and a line-only arrow
+  * Create more styles for the arrow, potentially including a compass rose and a line-only arrow
 
 * **Scale Bar:**
 
@@ -309,7 +400,13 @@ If I continue development of this project, I will be looking to add or fix the f
 
   * Clean up the variable naming scheme (consistency on `loc` vs `position`, `style` vs `type`, etc.)
 
-  * Create more styles for the bar, potentiallly including dual boxes and a sawtooth bar
+  * Create more styles for the bar, potentially including dual boxes and a sawtooth bar
+
+* **Inset Map:**
+
+  * Clean up the way that connectors are drawn for detail indicators
+
+  * New functionality for placing multiple inset maps at once (with context-aware positioning to prevent overlap with each other)
 
 * **Utils:**
 
@@ -319,9 +416,7 @@ If I continue development of this project, I will be looking to add or fix the f
 
   * (USA): Stronger typing options, so you don't have to recall which `region` or `division` types are available, etc.
 
-If that goes well, `v3` can then either create a tool for generating inset maps (which `matplotlib` has *some* support for), or the various functions that I have created in the past that assist with formatting a map "properly", such as centering on a given object.
-
-I am also open to ideas for other extensions to create!
+Future releases (if the project is continued) will probably focus on other functions that I have created myself that give more control in the formatting of maps. I am also open to ideas for other extensions to create!
 
 #### Support and Contributions
 

matplotlib_map_utils-3.0.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+matplotlib_map_utils/__init__.py,sha256=2mL2sZOjfxC--EthFMTMuYh1uvozz-9PzM4EDprDicU,949
+matplotlib_map_utils/core/__init__.py,sha256=mIn7x-LZlvNaYMcmjZXwnKNTirv3Vv2lAJodwRg_AdU,471
+matplotlib_map_utils/core/inset_map.py,sha256=-lZxiORndgYQAZzAerPaMlH95zrRsBspdwxIzHcn_2Q,40880
+matplotlib_map_utils/core/north_arrow.py,sha256=BXagxPdy0uCWpGTFvw-qnaZZKZlXsINTha0sqaBRK-M,22415
+matplotlib_map_utils/core/scale_bar.py,sha256=qVJYUGnajEfW6FeQ37V_6tEHPbu4V-8B0K4XfU7c8YQ,62101
+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=GpXiWUHcOsv43G1HOfpqw-dzDPQQzQB7RNdtIf0e7Bc,8225
+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
+matplotlib_map_utils/utils/usa.json,sha256=kLB9JXNSWf8VU-9XwXuMRAPKO-zA4aluQUEln7Ktc_s,26563
+matplotlib_map_utils/utils/usa.py,sha256=7SlUdxtCan5PFNIoLe-HfOC5r2cxJAF-9QKhNIK71EI,16853
+matplotlib_map_utils/validation/__init__.py,sha256=0fL3N63jxjRwTU44b7-6ZYZJfOT_0ac7dx7M6Gpu_5M,52
+matplotlib_map_utils/validation/functions.py,sha256=gh3d6Gj1klL8jb0nOwavIe3b9KFpOOCgQx1dYv-XMTw,13173
+matplotlib_map_utils/validation/inset_map.py,sha256=g5YQByVnQBtRb_PI8xqghkJ0IGdBtYvwNwQz_-ddQ4U,5791
+matplotlib_map_utils/validation/north_arrow.py,sha256=Vs9ljD0PbxBI7-4J8PkzC8SRI-LCgZDnIrL1xA6h77E,10366
+matplotlib_map_utils/validation/scale_bar.py,sha256=XrnGoAXwJFUTOnvoei1pqVJKu-BxcAaih27H6a4CXgk,17625
+matplotlib_map_utils-3.0.0.dist-info/licenses/LICENSE,sha256=aFLFZg6LEJFpTlNQ8su3__jw4GfV-xWBmC1cePkKZVw,35802
+matplotlib_map_utils-3.0.0.dist-info/METADATA,sha256=OqqR0p5BphIlwUHJWH8iEP9mQlVfjtY_iTE6jBxlZSE,16354
+matplotlib_map_utils-3.0.0.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
+matplotlib_map_utils-3.0.0.dist-info/top_level.txt,sha256=6UyDpxsnMhSOd9a-abQe0lLJveybJyYtUHMdX7zXgKA,21
+matplotlib_map_utils-3.0.0.dist-info/RECORD,,