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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matplotlib-map-utils
-Version: 3.0.1
+Version: 3.1.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/
@@ -29,7 +29,7 @@ Dynamic: license-file
 
 ---
 
-### Introduction
+### 👋 Introduction
 
 `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/).
 
@@ -53,7 +53,7 @@ Together, these allow for the easy creation of a map such as the following:
 
 ---
 
-### Installation
+### 💾 Installation
 
 This package is available on PyPi, and can be installed like so:
 
@@ -71,7 +71,7 @@ The requirements for this package are:
 
 ---
 
-### Package Structure
+### 📦 Package Structure
 
 <details>
 <summary><i>The package is arrayed in the following way:</i></summary>
@@ -260,6 +260,38 @@ 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.
 
+#### Specifying Length
+
+There are three main ways of specifying the length of a scale bar:
+
+- `length` is used to set the total length of the bar, either in _inches_ (for values >= 1) or as a _fraction of the axis_ (for values < 1).
+  - The default value of the scale bar utilizes this method, with a `length` value of `0.25` (meaning 25% of the axis).
+  - It will automatically orient itself against the horizontal or vertical axis when calculating its fraction, based on the value supplied for `rotation`.
+  - Note that any values here will be rounded to a "nice" whole integer, so the length will *always be approximate*; ex., if two inches is 9,128 units, your scale bar will end up being 9,000 units, and therefore a little less than two inches.
+  - Values `major_div` and `minor_div` are ignored, while a value for `max` will _override_ `length`.
+
+- `max` is used to define the total length of the bar, _in the same units as your map_, as determined by the value of `projection` and `unit`.
+  - Ex: If you are using a projection in feet, and give a `max` of `1000`, your scale bar will be representative of 1,000 feet.
+  - Ex: If you are using a projection in feet, but provide a value of `meter` to `unit`, and give a `max` of `1000`, your scale bar will be representative of 1,000 meters.
+  - Will _override_ any value provided for `length`, and give a warning that it is doing so!
+  - Values can be optionally be provided for `major_div` and `minor_div`, to subdivide the bar into major or minor segments as you desire; if left blank, values for these will be calculated automatically (see `preferred_divs` in `validation/scale_bar.py` for the values used).
+
+- `major_mult` can be used alongside `major_div` to _derive_ the total length: `major_mult` is the _length of a **single** major division_, in the _same units as your map_ (as determined by the value of `projection` and `unit`), which is then multiplied out by `major_div` to arrive at the desired length of the bar.
+  - Ex: If you set `major_mult` to 1,000, and `major_div` to 3, your bar will be 3,000 units long, divided into three 1,000 segments.
+  - This is the _only_ use case for `major_mult` - using it anywhere else will result in warnings and/or errors!
+  - Specifying either `max` or `length` will override this method!
+  - `minor_div` can still be _optionally_ provided.
+
+All of the above cases expect a valid CRS to be supplied to the `projection` parameter, to correctly calculate the relative size of the bar with respect to the map's underlying units. However, three _additional_ values may be passed to `projection`, to override this behavior entirely:
+
+- If `projection` is set to `px`, `pixel`, or `pixels`, then values for `max` and `major_mult` are interpreted as being in _pixels_ (so a `max` of 1,000 will result in a bar 1,000 pixels long)
+
+- If `projection` is set to `pt`, `point`, or `points`, then values for `max` and `major_mult` are interpreted as being in _points_ (so a `max` of 1,000 will result in a bar 1,000 points long (a point is 1/72 of an inch))
+
+- 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>
 
 ---
@@ -347,7 +379,7 @@ usa = USA()
 # Getting a list FIPS codes for US States
 usa.filter(states=True, to_return="fips")
 # Getting a list of State Names for states in the South and Midwest regions
-usa.filter(region=["South","Midtwest"], to_return="name")
+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()`.
@@ -356,7 +388,7 @@ Refer to `docs\howto_utils` for details on how to use this class, including with
 
 ---
 
-### Development Notes
+### 📝 Development Notes
 
 #### Inspiration and Thanks
 
@@ -370,6 +402,9 @@ Two more projects assisted with the creation of this script:
 
 #### Releases
 
+<details>
+<summary><i>See prior release notes</i></summary>
+
 - `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.
@@ -380,15 +415,21 @@ Two more projects assisted with the creation of this script:
 
 - `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.
 
 - `v3.0.1`: Fixed a bug that led to an incorrect Scale Bar being rendered when using the function method (`scale_bar()`) on a plot containing raster data (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/10) for details).
 
+- `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.
+
 #### Future Roadmap
 
 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:
+<details>
+<summary><i>If I continue development of this project, I will be looking to add or fix the following features:</i></summary>
 
 * For all: switch to a system based on Pydantic for easier type validation
 
@@ -424,14 +465,18 @@ If I continue development of this project, I will be looking to add or fix the f
 
 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!
 
+</details>
+
 #### Support and Contributions
 
 If you notice something is not working as intended or if you'd like to add a feature yourself, I welcome PRs - just be sure to be descriptive as to what you are changing and why, including code examples!
 
 If you are having issues using this script, feel free to leave a post explaining your issue, and I will try and assist, though I have no guaranteed SLAs as this is just a hobby project.
 
+I am open to contributions, especially to help tackle the roadmap above!
+
 ---
 
-### License
+### ⚖️ License
 
 I know nothing about licensing, so I went with the GPL license. If that is incompatible with any of the dependencies, please let me know.

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

@@ -10,7 +10,7 @@
 
 ---
 
-### Introduction
+### 👋 Introduction
 
 `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/).
 
@@ -34,7 +34,7 @@ Together, these allow for the easy creation of a map such as the following:
 
 ---
 
-### Installation
+### 💾 Installation
 
 This package is available on PyPi, and can be installed like so:
 
@@ -52,7 +52,7 @@ The requirements for this package are:
 
 ---
 
-### Package Structure
+### 📦 Package Structure
 
 <details>
 <summary><i>The package is arrayed in the following way:</i></summary>
@@ -241,6 +241,38 @@ 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.
 
+#### Specifying Length
+
+There are three main ways of specifying the length of a scale bar:
+
+- `length` is used to set the total length of the bar, either in _inches_ (for values >= 1) or as a _fraction of the axis_ (for values < 1).
+  - The default value of the scale bar utilizes this method, with a `length` value of `0.25` (meaning 25% of the axis).
+  - It will automatically orient itself against the horizontal or vertical axis when calculating its fraction, based on the value supplied for `rotation`.
+  - Note that any values here will be rounded to a "nice" whole integer, so the length will *always be approximate*; ex., if two inches is 9,128 units, your scale bar will end up being 9,000 units, and therefore a little less than two inches.
+  - Values `major_div` and `minor_div` are ignored, while a value for `max` will _override_ `length`.
+
+- `max` is used to define the total length of the bar, _in the same units as your map_, as determined by the value of `projection` and `unit`.
+  - Ex: If you are using a projection in feet, and give a `max` of `1000`, your scale bar will be representative of 1,000 feet.
+  - Ex: If you are using a projection in feet, but provide a value of `meter` to `unit`, and give a `max` of `1000`, your scale bar will be representative of 1,000 meters.
+  - Will _override_ any value provided for `length`, and give a warning that it is doing so!
+  - Values can be optionally be provided for `major_div` and `minor_div`, to subdivide the bar into major or minor segments as you desire; if left blank, values for these will be calculated automatically (see `preferred_divs` in `validation/scale_bar.py` for the values used).
+
+- `major_mult` can be used alongside `major_div` to _derive_ the total length: `major_mult` is the _length of a **single** major division_, in the _same units as your map_ (as determined by the value of `projection` and `unit`), which is then multiplied out by `major_div` to arrive at the desired length of the bar.
+  - Ex: If you set `major_mult` to 1,000, and `major_div` to 3, your bar will be 3,000 units long, divided into three 1,000 segments.
+  - This is the _only_ use case for `major_mult` - using it anywhere else will result in warnings and/or errors!
+  - Specifying either `max` or `length` will override this method!
+  - `minor_div` can still be _optionally_ provided.
+
+All of the above cases expect a valid CRS to be supplied to the `projection` parameter, to correctly calculate the relative size of the bar with respect to the map's underlying units. However, three _additional_ values may be passed to `projection`, to override this behavior entirely:
+
+- If `projection` is set to `px`, `pixel`, or `pixels`, then values for `max` and `major_mult` are interpreted as being in _pixels_ (so a `max` of 1,000 will result in a bar 1,000 pixels long)
+
+- If `projection` is set to `pt`, `point`, or `points`, then values for `max` and `major_mult` are interpreted as being in _points_ (so a `max` of 1,000 will result in a bar 1,000 points long (a point is 1/72 of an inch))
+
+- 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>
 
 ---
@@ -328,7 +360,7 @@ usa = USA()
 # Getting a list FIPS codes for US States
 usa.filter(states=True, to_return="fips")
 # Getting a list of State Names for states in the South and Midwest regions
-usa.filter(region=["South","Midtwest"], to_return="name")
+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()`.
@@ -337,7 +369,7 @@ Refer to `docs\howto_utils` for details on how to use this class, including with
 
 ---
 
-### Development Notes
+### 📝 Development Notes
 
 #### Inspiration and Thanks
 
@@ -351,6 +383,9 @@ Two more projects assisted with the creation of this script:
 
 #### Releases
 
+<details>
+<summary><i>See prior release notes</i></summary>
+
 - `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.
@@ -361,15 +396,21 @@ Two more projects assisted with the creation of this script:
 
 - `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.
 
 - `v3.0.1`: Fixed a bug that led to an incorrect Scale Bar being rendered when using the function method (`scale_bar()`) on a plot containing raster data (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/10) for details).
 
+- `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.
+
 #### Future Roadmap
 
 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:
+<details>
+<summary><i>If I continue development of this project, I will be looking to add or fix the following features:</i></summary>
 
 * For all: switch to a system based on Pydantic for easier type validation
 
@@ -405,14 +446,18 @@ If I continue development of this project, I will be looking to add or fix the f
 
 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!
 
+</details>
+
 #### Support and Contributions
 
 If you notice something is not working as intended or if you'd like to add a feature yourself, I welcome PRs - just be sure to be descriptive as to what you are changing and why, including code examples!
 
 If you are having issues using this script, feel free to leave a post explaining your issue, and I will try and assist, though I have no guaranteed SLAs as this is just a hobby project.
 
+I am open to contributions, especially to help tackle the roadmap above!
+
 ---
 
-### License
+### ⚖️ License
 
 I know nothing about licensing, so I went with the GPL license. If that is incompatible with any of the dependencies, please let me know.

{matplotlib_map_utils-3.0.1 → matplotlib_map_utils-3.1.0}/matplotlib_map_utils/core/inset_map.py

@@ -46,6 +46,7 @@ class InsetMap(matplotlib.artist.Artist):
                  coords: imt._TYPE_INSET["coords"]=None,
                  transform=None,
                  to_plot=None,
+                 zorder: int=99,
                  **kwargs):
         # Starting up the object with the base properties of a matplotlib Artist
         matplotlib.artist.Artist.__init__(self)
@@ -56,6 +57,7 @@ class InsetMap(matplotlib.artist.Artist):
         self._pad = imf._validate(imt._VALIDATE_INSET, "pad", pad)
         self._coords = imf._validate(imt._VALIDATE_INSET, "coords", coords)
         self._to_plot = imf._validate(imt._VALIDATE_INSET, "to_plot", to_plot)
+        self._zorder = imf._validate(imt._VALIDATE_INSET, "zorder", zorder)
 
         # Checking if we need to override values for size and pad
         if self._size is None:
@@ -65,11 +67,6 @@ class InsetMap(matplotlib.artist.Artist):
         
         self._transform = transform # not validated!
         self._kwargs = kwargs # not validated!
-    
-    # We do set the zorder for our objects individually,
-    # but we ALSO set it for the entire artist, here
-    # Thank you to matplotlib-scalebar for this tip
-    zorder = 99
 
     ## INTERNAL PROPERTIES ##
     # This allows for easy-updating of properties
@@ -162,6 +159,16 @@ class InsetMap(matplotlib.artist.Artist):
     def to_plot(self, val):
         val = imf._validate(imt._VALIDATE_INSET, "to_plot", val)
         self._to_plot = val
+    
+    # zorder
+    @property
+    def zorder(self):
+        return self._zorder
+
+    @zorder.setter
+    def zorder(self, val):
+        val = imf._validate(imt._VALIDATE_INSET, "zorder", val)
+        self._zorder = val
 
     ## COPY FUNCTION ##
     # This is solely to get around matplotlib's restrictions around re-using an artist across multiple axes
@@ -176,7 +183,7 @@ class InsetMap(matplotlib.artist.Artist):
     def create(self, pax, **kwargs):
         # Can re-use the drawing function we already established, but return the object instead
         iax = inset_map(ax=pax, location=self._location, size=self._size,
-                        pad=self._pad, coords=self._coords, transform=self._transform,
+                        pad=self._pad, coords=self._coords, transform=self._transform, zorder=self._zorder,
                         **self._kwargs, **kwargs)
         
         # If data is passed to to_plot, then we plot that on the newly created axis as well
@@ -226,6 +233,7 @@ class ExtentIndicator(matplotlib.artist.Artist):
                  linecolor: imt._TYPE_EXTENT["linecolor"]="red",
                  alpha: imt._TYPE_EXTENT["alpha"]=0.5,
                  linewidth: imt._TYPE_EXTENT["linewidth"]=1,
+                 zorder: int=99,
                  **kwargs):
         # Starting up the object with the base properties of a matplotlib Artist
         matplotlib.artist.Artist.__init__(self)
@@ -239,13 +247,9 @@ class ExtentIndicator(matplotlib.artist.Artist):
         self._linecolor = imf._validate(imt._VALIDATE_EXTENT, "linecolor", linecolor)
         self._alpha = imf._validate(imt._VALIDATE_EXTENT, "alpha", alpha)
         self._linewidth = imf._validate(imt._VALIDATE_EXTENT, "linewidth", linewidth)
+        self._zorder = imf._validate(imt._VALIDATE_EXTENT, "zorder", zorder)
 
         self._kwargs = kwargs # not validated!
-    
-    # We do set the zorder for our objects individually,
-    # but we ALSO set it for the entire artist, here
-    # Thank you to matplotlib-scalebar for this tip
-    zorder = 99
 
     ## INTERNAL PROPERTIES ##
     # This allows for easy-updating of properties
@@ -332,6 +336,16 @@ class ExtentIndicator(matplotlib.artist.Artist):
     def linewidth(self, val):
         val = imf._validate(imt._VALIDATE_EXTENT, "linewidth", val)
         self._linewidth = val
+    
+    # zorder
+    @property
+    def zorder(self):
+        return self._zorder
+
+    @zorder.setter
+    def zorder(self, val):
+        val = imf._validate(imt._VALIDATE_EXTENT, "zorder", val)
+        self._zorder = val
 
     # kwargs
     @property
@@ -366,7 +380,7 @@ class ExtentIndicator(matplotlib.artist.Artist):
                               to_return=self._to_return, straighten=self._straighten,
                               pad=self._pad, plot=self._plot,
                               facecolor=self._facecolor, linecolor=self._linecolor,
-                              alpha=self._alpha, linewidth=self._linewidth,
+                              alpha=self._alpha, linewidth=self._linewidth, zorder=self._zorder,
                               **self._kwargs, **kwargs)
         
         # The indicator will be drawn automatically if plot is True
@@ -389,6 +403,7 @@ class DetailIndicator(matplotlib.artist.Artist):
                  linewidth: imt._TYPE_EXTENT["linewidth"]=1,
                  connector_color: imt._TYPE_DETAIL["connector_color"]="black",
                  connector_width: imt._TYPE_DETAIL["connector_width"]=1,
+                 zorder: int=99,
                  **kwargs):
         # Starting up the object with the base properties of a matplotlib Artist
         matplotlib.artist.Artist.__init__(self)
@@ -404,13 +419,9 @@ class DetailIndicator(matplotlib.artist.Artist):
         self._to_return = imf._validate(imt._VALIDATE_DETAIL, "to_return", to_return)
         self._connector_color = imf._validate(imt._VALIDATE_DETAIL, "connector_color", connector_color)
         self._connector_width = imf._validate(imt._VALIDATE_DETAIL, "connector_width", connector_width)
+        self._zorder = imf._validate(imt._VALIDATE_DETAIL, "zorder", zorder)
 
         self._kwargs = kwargs # not validated!
-    
-    # We do set the zorder for our objects individually,
-    # but we ALSO set it for the entire artist, here
-    # Thank you to matplotlib-scalebar for this tip
-    zorder = 99
 
     ## INTERNAL PROPERTIES ##
     # This allows for easy-updating of properties
@@ -517,6 +528,16 @@ class DetailIndicator(matplotlib.artist.Artist):
     def connector_width(self, val):
         val = imf._validate(imt._VALIDATE_DETAIL, "connector_width", val)
         self._connector_width = val
+    
+    # zorder
+    @property
+    def zorder(self):
+        return self._zorder
+
+    @zorder.setter
+    def zorder(self, val):
+        val = imf._validate(imt._VALIDATE_DETAIL, "zorder", val)
+        self._zorder = val
 
     # kwargs
     @property
@@ -544,7 +565,8 @@ class DetailIndicator(matplotlib.artist.Artist):
                pax: imt._TYPE_EXTENT["pax"],
                iax: imt._TYPE_EXTENT["bax"],
                pcrs: imt._TYPE_EXTENT["pcrs"],
-               icrs: imt._TYPE_EXTENT["bcrs"], **kwargs):
+               icrs: imt._TYPE_EXTENT["bcrs"], 
+               **kwargs):
         
         # Can re-use the drawing function we already established, but return the object instead
         dti = indicate_detail(pax=pax, iax=iax, pcrs=pcrs, icrs=icrs,
@@ -554,6 +576,7 @@ class DetailIndicator(matplotlib.artist.Artist):
                               alpha=self._alpha, linewidth=self._linewidth,
                               connector_color=self._connector_color,
                               connector_width=self._connector_width,
+                              zorder=self._zorder,
                               **self._kwargs, **kwargs)
         
         # The indicator will be drawn automatically if plot is True
@@ -573,6 +596,7 @@ def inset_map(ax,
               pad: imt._TYPE_INSET["pad"]=None,
               coords: imt._TYPE_INSET["coords"]=None,
               transform=None,
+              zorder: int=99,
               **kwargs):
     
     ## VALIDATION ##
@@ -580,6 +604,7 @@ def inset_map(ax,
     size = imf._validate(imt._VALIDATE_INSET, "size", size)
     pad = imf._validate(imt._VALIDATE_INSET, "pad", pad)
     coords = imf._validate(imt._VALIDATE_INSET, "coords", coords)
+    zorder = imf._validate(imt._VALIDATE_INSET, "zorder", zorder)
 
     if size is None:
         size = _DEFAULT_INSET_MAP["size"]
@@ -671,7 +696,7 @@ def inset_map(ax,
     ## DRAWING ##
     # Creating the new inset map with the specified height, width, and location
     # by default, inset_axes requires everything to be in ax.transAxes coordinates
-    iax = ax.inset_axes([x, y, inset_width, inset_height], **kwargs)
+    iax = ax.inset_axes([x, y, inset_width, inset_height], zorder=zorder, **kwargs)
     
     # We also set the anchor here, such that it stays fixed when any resizing takes place
     loc_anchors = {
@@ -701,6 +726,7 @@ def indicate_extent(pax: imt._TYPE_EXTENT["pax"],
                     linecolor: imt._TYPE_EXTENT["linecolor"]="red",
                     alpha: imt._TYPE_EXTENT["alpha"]=0.5,
                     linewidth: imt._TYPE_EXTENT["linewidth"]=1,
+                    zorder: int=99,
                     **kwargs):
     
     ## VALIDATION ##
@@ -716,6 +742,7 @@ def indicate_extent(pax: imt._TYPE_EXTENT["pax"],
     linecolor = imf._validate(imt._VALIDATE_EXTENT, "linecolor", linecolor)
     alpha = imf._validate(imt._VALIDATE_EXTENT, "alpha", alpha)
     linewidth = imf._validate(imt._VALIDATE_EXTENT, "linewidth", linewidth)
+    zorder = imf._validate(imt._VALIDATE_EXTENT, "zorder", zorder)
     
     # Make sure the figure layout is calculated
     fig = pax.get_figure()
@@ -748,15 +775,13 @@ def indicate_extent(pax: imt._TYPE_EXTENT["pax"],
     # Straightening the points if desired
     if straighten == True:
         extent_shape = shapely.envelope(extent_shape)
-
-    # return extent_shape
-    
+  
     # Plotting, if desired
     if plot == True:
         # Note that the alpha ONLY applies to the facecolor!
         extent_patch = matplotlib.patches.Polygon(list(extent_shape.exterior.coords), transform=pax.transData,
                                                   facecolor=matplotlib.colors.to_rgba(facecolor, alpha=alpha), 
-                                                  edgecolor=linecolor, linewidth=linewidth, **kwargs)
+                                                  edgecolor=linecolor, linewidth=linewidth, zorder=zorder, **kwargs)
         pax.add_artist(extent_patch)
 
     # Deciding what we need to return
@@ -789,8 +814,7 @@ def indicate_detail(pax: imt._TYPE_EXTENT["pax"],
                     alpha: imt._TYPE_EXTENT["alpha"]=1,
                     linecolor: imt._TYPE_EXTENT["linecolor"]="black",
                     linewidth: imt._TYPE_EXTENT["linewidth"]=1,
-                    # connector_color: imt._TYPE_DETAIL["connector_color"]="black",
-                    # connector_width: imt._TYPE_DETAIL["connector_width"]=1,
+                    zorder: int=99,
                     **kwargs):
     
     fig = pax.get_figure()
@@ -809,8 +833,7 @@ def indicate_detail(pax: imt._TYPE_EXTENT["pax"],
     alpha = imf._validate(imt._VALIDATE_EXTENT, "alpha", alpha)
     linecolor = imf._validate(imt._VALIDATE_EXTENT, "linecolor", linecolor)
     linewidth = imf._validate(imt._VALIDATE_EXTENT, "linewidth", linewidth)
-    # connector_color = imf._validate(imt._VALIDATE_DETAIL, "connector_color", connector_color)
-    # connector_width = imf._validate(imt._VALIDATE_DETAIL, "connector_width", connector_width)
+    zorder = imf._validate(imt._VALIDATE_EXTENT, "zorder", zorder)
 
     # Drawing the extent indicator on the main map
     # Setting to_return="ax" gets us the corners of the patch in pax.transAxes coordinates
@@ -819,7 +842,7 @@ def indicate_detail(pax: imt._TYPE_EXTENT["pax"],
                                      straighten=straighten, pad=pad, plot=plot,
                                      facecolor=facecolor, linecolor=linecolor,
                                      alpha=alpha, linewidth=linewidth*1.25,
-                                     to_return="ax", **kwargs)[:4]
+                                     to_return="ax", zorder=zorder, **kwargs)[:4]
 
     # Getting the inset axis points and transforming them to the parent axis CRS
     corners_inset = _inset_corners_to_parent(pax, iax)
@@ -873,12 +896,13 @@ def indicate_detail(pax: imt._TYPE_EXTENT["pax"],
         for c in connections:
             # This is listed as [extent_x, inset_x], [extent_y, inset_y]
             pax.plot([c[0][0], c[1][0]], [c[0][1], c[1][1]], 
-                    color=linecolor, linewidth=linewidth, transform=pax.transAxes)
+                    color=linecolor, linewidth=linewidth, transform=pax.transAxes, zorder=zorder+1)
         
-        # Also updating the linewidth and color of the inset map itsef, to match
-        for a in ["top","bottom","left","right"]:
-            iax.spines[a].set_linewidth(linewidth*1.2) # making this slightly thicker
-            iax.spines[a].set_edgecolor(linecolor)
+        # Also updating the linewidth and color of the inset map itself, to match
+        iax.spines[:].set_linewidth(linewidth*1.2) # making this slightly thicker
+        iax.spines[:].set_edgecolor(linecolor)
+        iax.set_zorder(zorder+2)
+        iax.spines[:].set_zorder(zorder+2)
     
     # Returning as requested
     if to_return is None:
@@ -893,37 +917,37 @@ def indicate_detail(pax: imt._TYPE_EXTENT["pax"],
 # This is a top-level helping function
 # that will return an axis with inset maps drawn for Alaska, Hawaii, DC, and/or Puerto Rico
 # NOTE that as of this initial release, it assumes your map is in CRS 3857 for positioning
-def inset_usa(ax, alaska=True, hawaii=True, dc=True, puerto_rico=True, size=None, pad=None, **kwargs):
+def inset_usa(ax, alaska=True, hawaii=True, dc=True, puerto_rico=True, size=None, pad=None, zorder: int=99, **kwargs):
     # This will return all of the axes we create
     to_return = []
     
     # Alaska and Hawaii are positioned relative to each other
     if alaska == True and hawaii == True:
-        aax = inset_map(ax, "lower left", size, pad, **kwargs)
+        aax = inset_map(ax, "lower left", size, pad, zorder=zorder, **kwargs)
         to_return.append(aax)
         # Need to shift over the hawaii axis by the size of the alaska axis
         # Note that we add xmax and xmin together here, to account for the padding (xmin is the amount of padding)
         shift_right = float(aax.get_window_extent().transformed(ax.transAxes.inverted()).xmax) + float(aax.get_window_extent().transformed(ax.transAxes.inverted()).xmin)
         # also need to shift it up, by the amount of the padding (which we can crib from ymin)
         shift_up = float(aax.get_window_extent().transformed(ax.transAxes.inverted()).ymin)
-        hax = inset_map(ax, "lower left", size, pad, coords=(shift_right, shift_up), **kwargs)
+        hax = inset_map(ax, "lower left", size, pad, zorder=zorder, coords=(shift_right, shift_up), **kwargs)
         to_return.append(hax)
     else:
         if alaska == True:
-            aax = inset_map(ax, "lower_left", size, pad, **kwargs)
+            aax = inset_map(ax, "lower_left", size, pad, zorder=zorder, **kwargs)
             to_return.append(aax)
         if hawaii == True:
-            hax = inset_map(ax, "lower left", size, pad, **kwargs)
+            hax = inset_map(ax, "lower left", size, pad, zorder=zorder, **kwargs)
             to_return.append(hax)
 
     # Puerto Rico is positioned off the coast of Florida
     if puerto_rico == True:
-        pax = inset_map(ax, "lower right", size, pad, **kwargs)
+        pax = inset_map(ax, "lower right", size, pad, zorder=zorder, **kwargs)
         to_return.append(pax)
     
     # DC is off the coast of DC
     if dc == True:
-        dax = inset_map(ax, "center right", size, pad, **kwargs)
+        dax = inset_map(ax, "center right", size, pad, zorder=zorder, **kwargs)
         to_return.append(dax)
     
     # Finally, returning everything