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

{matplotlib_map_utils-3.0.1.dist-info → matplotlib_map_utils-3.1.1.dist-info}/RECORD

@@ -1,24 +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/core/inset_map.py,sha256=iJISV0gZ3OmhO-DzC5z5kH5qL8fpdqmHn5OkdhdtzAY,41561
+matplotlib_map_utils/core/north_arrow.py,sha256=UDn0TBnLuhuONbibb_XT8C2HNSY6ONLCQgadR19WpmI,22846
+matplotlib_map_utils/core/scale_bar.py,sha256=kM9WMwdpKJuShl8BkzsRcFhc0y-Kxu8wJpriz8iVYzk,67064
 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/defaults/scale_bar.py,sha256=422U5hBtLpXrWZuj7vOnZNmIWI_KnOgDIwRX__m4GCY,8345
 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/validation/functions.py,sha256=IIT9DiPKVv_ZHUTC8FwXJPt2pzdQI-8zhx6SHqto65E,13020
+matplotlib_map_utils/validation/inset_map.py,sha256=C5e_zOBKHqVNgufhwoIxu1OhlvXoaj70WxreW4BSfnA,6019
+matplotlib_map_utils/validation/north_arrow.py,sha256=6D-uLiMmre0E9JwjR0BTWNZJyCqPuL0b3HGZ91UHoXw,10442
+matplotlib_map_utils/validation/scale_bar.py,sha256=dYhiuqBV8wkMmFsR8p4RMbfBmN1DU--5cWU-Om9m7UY,18162
+matplotlib_map_utils-3.1.1.dist-info/licenses/LICENSE,sha256=aFLFZg6LEJFpTlNQ8su3__jw4GfV-xWBmC1cePkKZVw,35802
+matplotlib_map_utils-3.1.1.dist-info/METADATA,sha256=AZQKlt58icL88wIRhSJwyEdU6XhEDwcr-zpiwBBsoQQ,63423
+matplotlib_map_utils-3.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+matplotlib_map_utils-3.1.1.dist-info/top_level.txt,sha256=6UyDpxsnMhSOd9a-abQe0lLJveybJyYtUHMdX7zXgKA,21
+matplotlib_map_utils-3.1.1.dist-info/RECORD,,

matplotlib_map_utils-3.0.1.dist-info/METADATA

@@ -1,437 +0,0 @@
-Metadata-Version: 2.4
-Name: matplotlib-map-utils
-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/
-Project-URL: Bug Tracker, https://github.com/moss-xyz/matplotlib-map-utils/issues
-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
-Requires-Dist: matplotlib>=3.9.0
-Requires-Dist: cartopy>=0.23.0
-Requires-Dist: great-circle-calculator>=1.3.1
-Dynamic: license-file
-
-![matplotlib_map_utils logo](matplotlib_map_utils/docs/assets/mmu_logo_w_elements.png)
- 
----
-
-**Documentation:** See `docs` folder
-
-**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.
-
----
-
-### 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/).
-
-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. 
-
-The three elements listed above are all intended to be high-resolution, easily modifiable, and context-aware, relative to your specific 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.
-
-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)
-
----
-
-### Installation
-
-This package is available on PyPi, and can be installed like so:
-
-```bash
-pip install matplotlib-map-utils
-```
-
-The requirements for this package are:
-
-* `python >= 3.10` (due to the use of the pipe operator to concatenate dictionaries and types)
-
-* `matplotlib >= 3.9` (might work with lower versions but not guaranteed)
-
-* `cartopy >= 0.23` (due to earlier bug with calling `copy()` on `CRS` objects)
-
----
-
-### Package Structure
-
-<details>
-<summary><i>The package is arrayed in the following way:</i></summary>
-
-```bash
-package_name/
-├── __init__.py
-│
-├── 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
-│   └── usa.json
-```
-
-Where:
-
-* `core` contains the main functions and classes for each object
-
-* `validation` contains type hints for each variable and functions to validate inputs
-
-* `defaults` contains default settings for each object at different paper sizes
-
-* `utils` contains utility functions and objects
-
-</details>
-
----
-
-### 🧭 North Arrow
-
-<details>
-<summary><i>Expand instructions</i></summary>
-
-#### Quick Start
-
-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:
-
-```python
-# Setting up a plot
-fig, ax = matplotlib.pyplot.subplots(1,1, figsize=(5,5), dpi=150)
-# Adding a north arrow to the upper-right corner of the axis, without any rotation (see Rotation under Formatting Components for details)
-north_arrow.north_arrow(ax=ax, location="upper right", rotation={"degrees":0})
-```
-
-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 a north arrow for the upper-right corner of the axis, without any rotation (see Rotation under Formatting Components for details)
-na = north_arrow.NorthArrow(location="upper right", rotation={"degrees":0})
-# Adding the artist to the plot
-ax.add_artist(na)
-```
-
-Both of these will create an output like the following:
-
-![Example north arrow](matplotlib_map_utils/docs/assets/readme_northarrow.png)
-
-#### Customization
-
-Both the object-oriented and functional approaches can be customized to allow for fine-grained control over formatting:
-
-```python
-north_arrow(
-    ax,
-    location = "upper right", # accepts a valid string from the list of locations
-    scale = 0.5, # accepts a valid positive float or integer
-    # each of the follow accepts arguments from a customized style dictionary
-    base = {"facecolor":"green"},
-    fancy = False,
-    label = {"text":"North"},
-    shadow = {"alpha":0.8},
-    pack = {"sep":6},
-    aob = {"pad":2},
-    rotation = {"degrees": 35}
-)
-```
-
-This will create an output like the following:
-
-![Customized north arrow](matplotlib_map_utils/docs/assets/readme_northarrow_customization.png)
-
-Refer to `docs\howto_north_arrow` for details on how to customize each facet of the north arrow.
-
-#### Rotation
-
-The north arrow object is also capable of pointing towards "true north", given a CRS and reference point:
-
-![Example north arrow rotation](matplotlib_map_utils/docs/assets/readme_northarrow_rotation.png)
-
-Instructions for how to do so can be found in `docs\howto_north_arrow`.
-</details>
-
----
-
-### 📏 Scale Bar
-
-<details>
-<summary><i>Expand instructions</i></summary>
-
-#### Quick Start
-
-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
-scale_bar(ax=ax, location="upper right", style="boxes", bar={"projection":3857})
-```
-
-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="ticks", bar={"projection":3857})
-# Adding the artist to the plot
-ax.add_artist(sb)
-```
-
-Both of these will create an output like the following (function is left, class is right):
-
-![Example scale bar](matplotlib_map_utils/docs/assets/readme_scalebar.png)
-
-#### Customization
-
-Both the object-oriented and functional approaches can be customized to allow for fine-grained control over formatting:
-
-```python
-scale_bar(
-    ax,
-    location = "upper right", # accepts a valid string from the list of locations
-    style = "boxes", # accepts a valid positive float or integer
-    # each of the follow accepts arguments from a customized style dictionary
-    bar = {"unit":"mi", "length":2}, # converting the units to miles, and changing the length of the bar (in inches)
-    labels = {"style":"major", "loc":"below"}, # placing a label on each major division, and moving them below the bar
-    units = {"loc":"text"}, # changing the location of the units text to the major division labels
-    text = {"fontfamily":"monospace"}, # changing the font family of all the text to monospace
-)
-```
-
-This will create an output like the following:
-
-![Customized scale bar](matplotlib_map_utils/docs/assets/readme_scalebar_customization.png)
-
-Refer to `docs\howto_scale_bar` for details on how to customize each facet of the scale bar.
-
-</details>
-
----
-
-### 🗺️ 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>
-
-#### Quick Start
-
-Importing the bundled utility functions and classes can be done like so:
-
-```py
-from matplotlib_map_utils.utils import USA
-```
-
-As of `v2.1.0`, there is only one utility class available: `USA`, an object to help quickly filter for subsets of US states and territories. This utility class is still in beta, and might change.
-
-An example:
-
-```python
-# Loading the object
-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")
-```
-
-Refer to `docs\howto_utils` for details on how to use this class, including with `pandas.apply()`.
-
-</details>
-
----
-
-### Development Notes
-
-#### Inspiration and Thanks
-
-This project was heavily inspired by [`matplotlib-scalebar`](https://github.com/ppinard/matplotlib-scalebar/), and much of the code is either directly copied or a derivative of that project, since it uses the same "artist"-based approach.
-
-Two more projects assisted with the creation of this script:
-
-* [`EOmaps`](https://github.com/raphaelquast/EOmaps/discussions/231) provided code for calculating the rotation required to point to "true north" for an arbitrary point and CRS for the north arrow.
-
-* [`Cartopy`](https://github.com/SciTools/cartopy/issues/2361) fixed an issue inherent to calling `.copy()` on `CRS` objects.
-
-#### Releases
-
-- `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 `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, potentially including a compass rose and a line-only arrow
-
-* **Scale Bar:**
-
-  * Allow for custom unit definitions (instead of just metres/feet/miles/kilometres/etc.), so that the scale bar can be used on arbitrary plots (such as inches/cm/mm, mathmatical plots, and the like)
-
-  * Fix/improve the `dual_bars()` function, which currently doesn't work great with rotations
-
-  * Clean up the variable naming scheme (consistency on `loc` vs `position`, `style` vs `type`, etc.)
-
-  * 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:**
-
-  * (USA): Stronger fuzzy search mechanics, so that it will accept flexible inputs for FIPS/abbr/name
-
-  * (USA): More integrated class types to allow for a more fully-formed object model (USA being a `Country`, with subclasses related to `State` and `Territory` that have their own classes of attributes, etc.)
-
-  * (USA): Stronger typing options, so you don't have to recall which `region` or `division` types are available, etc.
-
-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
-
-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.
-
----
-
-### 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.