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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matplotlib-map-utils
-Version: 2.1.0
+Version: 3.0.1
 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,12 +203,16 @@ 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:
 
 ```python
 # Setting up a plot
+# NOTE: you MUST set the desired DPI here, when the subplots are created
+# so that the scale_bar's DPI matches!
 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, this scale bar will have the "boxes" style
@@ -198,10 +223,12 @@ An object-oriented approach is also supported:
 
 ```python
 # Setting up a plot
+# NOTE: you MUST set the desired DPI here, when the subplots are created
+# so that the scale_bar's DPI matches!
 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 +264,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 +370,33 @@ 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.
+
+- `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).
+
 #### 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 +406,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 +422,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.1.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=wku3KZEaTzmB0MBHVTj6orXH0Q36X0CJHvIzkCeC6s0,62996
+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.1.dist-info/licenses/LICENSE,sha256=aFLFZg6LEJFpTlNQ8su3__jw4GfV-xWBmC1cePkKZVw,35802
+matplotlib_map_utils-3.0.1.dist-info/METADATA,sha256=9Rc1YXQ0bc3rY8jfi5DHGdJaGLsMBnVyMGOC8oVKCQI,16825
+matplotlib_map_utils-3.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+matplotlib_map_utils-3.0.1.dist-info/top_level.txt,sha256=6UyDpxsnMhSOd9a-abQe0lLJveybJyYtUHMdX7zXgKA,21
+matplotlib_map_utils-3.0.1.dist-info/RECORD,,

{matplotlib_map_utils-2.1.0.dist-info → matplotlib_map_utils-3.0.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.1.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

matplotlib_map_utils-2.1.0.dist-info/RECORD

@@ -1,21 +0,0 @@
-matplotlib_map_utils/__init__.py,sha256=X6lN1yfP4ckb6l-ej20YqFvIHUNLZQxRWnvvyWBlJEY,305
-matplotlib_map_utils/core/__init__.py,sha256=G4fxPpfE77EhZr7yGZCjppP7zvwRthl8yHM0b2KgrFs,184
-matplotlib_map_utils/core/north_arrow.py,sha256=vikwYtSP2-sPRF_SQBALezB3uEY_PHA9dglm503hkvU,22531
-matplotlib_map_utils/core/scale_bar.py,sha256=l2tS35xa_pv40lag4Y00hT6FEGhQ-wOb07ipxDUYCNw,62248
-matplotlib_map_utils/defaults/__init__.py,sha256=_pegE5kv_sb0ansSF4XpWBRwboaP4zUjWY1KIGbK-TE,119
-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=QpOHs-GQ1NUMXO0HxAtEZvAcrXwsIE2ekqUhYm-IKGg,11783
-matplotlib_map_utils/validation/north_arrow.py,sha256=dlWbcKit7dq93PJVrv1efE_865irT6zwBuqD6NYLYPg,10349
-matplotlib_map_utils/validation/scale_bar.py,sha256=7rYs7ei0rQ5iJfapcBWkn7s4P-CnSh9B441GpsGpFO4,17628
-matplotlib_map_utils-2.1.0.dist-info/licenses/LICENSE,sha256=aFLFZg6LEJFpTlNQ8su3__jw4GfV-xWBmC1cePkKZVw,35802
-matplotlib_map_utils-2.1.0.dist-info/METADATA,sha256=KaD3ZBhrkgi25DYJV2xJXx0wjcTM9MgmNcNr58Z6UcE,12839
-matplotlib_map_utils-2.1.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-matplotlib_map_utils-2.1.0.dist-info/top_level.txt,sha256=6UyDpxsnMhSOd9a-abQe0lLJveybJyYtUHMdX7zXgKA,21
-matplotlib_map_utils-2.1.0.dist-info/RECORD,,