Eomaps

A minor release with some awesome new features!

🌦️ changes
- ❗ `m.plot_map(pick_distance=...)` is depreciated, use `m.cb.pick.set_props(search_radius=...)` instead ❗


🌳 New
🌲 Improvements for PICK callbacks
The internals for pick-callbacks have been re-worked to improve performance and incorporate some new features.
- you can now use `m.cb.pick.set_props(...)` to set the picking behavior for each Maps-object

🌱 Pick N nearest neighbors
- Starting with EOmaps v5.4 it is possible to pick N nearest neighbors instead of a single point!
- Checkout the docs for more details: [🍭Picking N nearest neighbours](https://eomaps.readthedocs.io/en/latest/api.html#picking-n-nearest-neighbours)
python
m = Maps()
m.set_data([1,2,3,4,5], [1,2,3,4,5], [1,2,3,4,5])
m.plot_map()
m.cb.pick.set_props(n=3, pick_relative_to_closest=True, consecutive_pick=False)
m.cb.pick.attach.mark(fc="none", ec="r")


🌲 Improvements for shapes
🌱 There is a new plot-shape: `m.set_shape.scatter_points`
- basically the same as using `plt.scatter()` but supercharged so that EOmaps functionalities work as expected
- use it to draw datapoints with dimensions defined in (figure-points)² (rather than actual physical dimensions)
python
m = Maps()
m.add_feature.preset.coastline()
m.set_data([1, 2, 3], [-45, 20, 52], [-10, 20, 30])
m.set_shape.scatter_points(size=[200, 50, 500], marker="*")
m.plot_map(cmap="tab10")


🌱 The shape-radius can now be defined for each datapoint individually!
- The `radius` argument of the shapes `ellipses`, `rectangles` and `geod_circles` now properly
broadcasts multiple values (e.g. you can assign an individual radius for each datapoint)
python
m = Maps()
m.add_feature.preset.coastline()
m.set_data([1, 2, 3], [-45, 20, 52], [-10, 20, 30])
m.set_shape.ellipses(radius=[1, 2, 3], radius_crs=4326)
m.plot_map()


🔨 fixes
- fix parsing `n=None` as shape-argument in the companion-widget
- allow using the companion-widget with matplotlibs `"QtAgg"` backend
- fix performance issues with `m.get_crs`
- fix using `m.BM.blit_artist` if the renderer is not yet cached
- make evaluation of scalebar background patch size more robust
- ensure that scalebar is correctly updated if properties change
- switch to mambaforge to avoid installation-issues in github-actions
- lazily initialize pick-search tree only if a pick callback is attached
(provides a nice speedup for large datasets if no pick callbacks are assigned)
- allow passing None to `m._decode_values`
- fix picking GeoDataFrames if no value-column was assigned (e.g. when using `m.add_gdf(column=None)`)
- remove obsolete dependencies and unused requirements.txt from the docs

A minor release with a lot of bugfixes and some nice improvements

❗ Changes
Classifications of NaturalEarth features into scale-categories have been depreciated to simplify the interface.
(the old syntax is still functional but will be removed in future releases)
- `m.add_feature.cultural_10m.urban_areas()` $\rightarrow$ `m.add_feature.cultural.urban_areas(scale=10)`
- `m.add_feature.physical_50m.coastline()` $\rightarrow$ `m.add_feature.physical.coastline(scale=50)`
- `m.add_feature.physical_110m.coastline()` $\rightarrow$ `m.add_feature.physical.coastline(scale=110)`

🌳 New
- using `m.plot_map(vmin=..., vmax=...)` now respects the encoding of the data (if applicable)
(e.g. values are provided as **actual data values** and internally converted to respect the data-encoding)
- ✏️ [drawing-capabilities](https://eomaps.readthedocs.io/en/latest/api.html#draw-shapes-on-the-map) have been re-worked to get rid of performance issues.
- 🧭 The [compass (or North-arrow)](https://eomaps.readthedocs.io/en/latest/api.html#compass-or-north-arrow) implementation has been re-worked
- The last known valid angle is used if compass is placed at a position where the angle could not be determined
- Use `c.set_ignore_invalid_angles(True)` to ignore warnings if angle could not be determined
- It is now possible to add a compass to a specific layer with `m.add_compass(layer=...)`
- If you pick the compass with the mouse, it can be resized by simultaneously turning the mouse-wheel
- The interface for [🌵 NaturalEarth features](https://eomaps.readthedocs.io/en/latest/api.html#geodataframes-and-naturalearth-features) has been improved and simplified
- Features are now only grouped by category and the scale is provided as argument
`m.add_feature.physical_10m.coastline` $\rightarrow$ `m.add_feature.physcial.coastline(scale=10)`
- If the provided scale is not available, the next available scale is used!
- By default, all features determine the appropriate scale automatically and are added via cartopy's feature-interface.
- To get a `geopandas.GeoDataFrame` containing all geometries and metadata of a feature, use `m.add_feature.physcial.coastline.get_gdf(scale=10)`
- `Maps`-objects can now be used as context-managers to free memory when the object is no longer needed.
(particularly useful to render video-frames etc.)

python
Maps-objects can be used as context-managers to free memory after usage
with Maps(...) as m:
...
this also works for new layers on existing maps!
m = Maps()
with m.new_layer("my_layer") as m2:
...


minor (non-breaking) changes
- annotations now use the picked color as edgecolor by default. (use `m.cb.click.attach.annotate(bbox=dict(ec="k"))` to get the initial behaviour, e.g. a black edgecolor)
- if a picker is used with `m.add_gdf`, the picked value is obtained from the column assigned via `column=...` by default. You can override this by using `val_key=...`

🔨 Fixes
- Fix dragging the companion-widget on Linux
- Avoid re-drawing on savefig if dpi settings did not change
- Improve cleanup methods
- Fix activating the Layout-manager if no artists are present
- Fix finishing draw-events if multiple drawers are present
- Fix performance issues with the drawer
- Avoid updating the figure on move-events without move callbacks
- Don't use defaultdicts for callback-containers
- Fix setting vmin and vmax with encoded data
- Fix caching of wms-layers in the companion-widget
- Avoid using defaultdicts
- Indicate if the compass rotation-angle is invalid
- Fix "cartopy" based GeoDataFrame reprojections
- Fix clearing outdated cached layers
- Avoid setting map-extent when adding markers
- Fix setting the clip-path for WebMap services on non-rectangular axes
- Use preset-styles in Companion-widget when adding preset-features
- fix lazy import of mapclassify
- fix re-positioning of webmap legends
- fix fetching values from geo-data-frames

A quick bugfix release for v5.2 to address issues with the companion-widget.
❗ Make sure to check the updates for [EOmaps v5.2](https://github.com/raphaelquast/EOmaps/releases/tag/v5.2) as well ❗

🌳 New
- `Austria` WebMap services are now accessible via the companion-widget

🔨 Fixes
- fix populating WebMap layer sub-menus in the companion-widget
- use a file-cache for WebMap layer names

A new minor releases with a lot of bugfixes and some awesome usability upgrades.

🌳 New
Some internals of EOmaps have been re-structured to make it easier to add Maps-objects to existing matplotlib-figures!
Check the docs for more details: [🍱 Adding Maps to existing figures](https://eomaps.readthedocs.io/en/dev/api.html#adding-maps-to-existing-figures)
python
f = plt.figure()
ax = f.add_subplot(211)
m = Maps(f=f, ax=212)


🌦️ Changes
💧 General
- When using `m.savefig(dpi=...)` with the plot-shapes `"shade_points"` or `"shade_raster"` the shading-pipeline is now automatically adjusted to reflect the dpi of the saved figure (e.g. exporting higher dpi figures will also result in more detailed shading of the data).

- The [🧰 Companion-Widget](https://eomaps.readthedocs.io/en/latest/api.html#companion-widget) has some new functionalities! (e.g. basic **click/pick** callbacks)

💧 Syntax
- `Maps(gs_ax=...)` has been re-named to `Maps(ax=...)`
- ❗ Usage of the `m.figure.<...>` accessor is depreciated!
- Objects are now directly accessible via `m.f`, `m.ax`, `m.coll` and `m.colorbar.ax_cb` `m.colorbar.ax_cb_plot`

💧 Updates for keypress callbacks
- `keypress` callbacks are now triggered irrespective of the mouse-position (as long as the figure is active)
- It is now also possible to create callbacks that trigger on **any** key by using `key=None`.
(the actually used key is passed to the callback via the `key` kwarg)

💧 Updates for layer sliders
- There's a new function `slider.set_layers()` to updates the layers targeted by an existing slider
- The slider-label now shows the currently visible layer-name in **red** if the active layer is not targeted by the slider

💧 Updates for logos
- It is now possible to fix the logo-position relative to the map with `m.add_logo(fix_position=True)`
(the default is False so that logos can be re-positioned with the layout-editor!)
- Checkout the new [👽 logos](https://eomaps.readthedocs.io/en/dev/api.html#logos) section in the docs for more details!


🔨 Fixes
- fix issues when adding Maps-objects to existing figures
- fix issues when setting the map-extent to the data-extent
- speed up opening datasets with the companion widget (avoid scaling to retrieve info)
- allow adding MapsGrid objects to existing figures
- make "switch_layer" keypress callbacks accept only strings as layer-names
- update github actions to address depreciation warnings
- fix registering of transparent colormaps
- fix issues with boundary-pixels for "raster" shape
- fix using layer-names that contain double-underscores
- make sure the figure is closed if Maps is used as context-manager
- fix handling of long layer-names in companion-widget
- assign n for shapes based on dataset-size (if not specified explicitly)
- remove cached background layers of deleted layers
- adjust shading pipeline on figure resize
- adjust shading pipeline on m.savefig if dpi is changed
- fix re-fetching of xyz webmap services if axis size changed
- fix issues when adding new webmap layers via the companion widget
- avoid keeping companion-widget "always-on-top"
- fix logos reset position at next draw event

A first minor release for EOmaps v5.x with a lot of bugfixes, some improvements for speed and memory-management and new functionalities for the colorbar!

> Make sure to check the new features introduced in [EOmaps v5.0](https://github.com/raphaelquast/EOmaps/releases/tag/v5.0) as well!

🌳 New
- new WebMap service: `m.add_wms.DLR_basemaps`
- improved speed and memory-management for very large datasets

🌈 Updates for the colorbar
New convenience function `m.colorbar.set_bin_labels()` to simplify labeling individual bins of the colorbar with custom names.

> Check the [📖 documentation](https://eomaps.readthedocs.io/en/dev/api.html#set-colorbar-tick-labels-based-on-bins) for more details!

- ... ordinary colorbar (for classified data):
<img src=https://user-images.githubusercontent.com/22773387/200864560-377a864d-2fa7-4663-b91a-482361515abe.png width=70%>
- ... the colorbar after using `m.colorbar.set_bin_labels()` to set custom labels at the center of the specified bins
<img src=https://user-images.githubusercontent.com/22773387/200865175-0a1df4d9-b1c2-4aef-ac65-882961e72576.png width=70%>


🔨 Fixes
- allow using (equal-length) 1D datasets for `m.set_shape.raster`
- fix close button callback for companion-widget popups
- fix utility widgets for multiple maps in one figure
- fix layer assignment for WebMap legends
- fix providing custom colorbar ticks for classified data
- fix issues with colorbar tick formatter
- avoid memory-intense index-creations for very large datasets
- avoid re-shaping for very large 2D datasets with 1D coordinates
- add some basic unittests for plotting from files
- fix colormap usage for classified datasets

A new major release that brings a lot of very nice features and updates 🥳

❗ (possibly) breaking changes to v4.x ❗
New `layer-name` convention:
- All layer-names are now parsed as `string`!
(any non-string object passed as layer-name will be converted to string and a warning is shown)

- The `"|"` character is used as a **separator for multi-layers** (see new **⧉ Multi Layers** feature below)
(a layer-name such as `"first|second"` now represents the combined artists for the layers `"first"` and `"second"`)

Changes for the `colorbar`
The implementation of the colorbar has been re-worked and several changes have been introduced:

- Colorbars are now accessible via `m.colorbar`
- Some arguments of `m.add_colorbar(...)` have changed! Check the docstring for details!
- The individual colorbar-axes are accessible via `m.colorbar.ax_cb` and `m.colorbar.ax_cb_plot`
- To set the size of the colorbar, use `m.colorbar.set_position(...)`
- To remove a colorbar, use `m.colorbar.remove()`


🌳 New
🧰 Companion widget
Starting with v5.0, EOmaps provides an awesome companion-widget to speed up data-comparisons and analysis.

> NOTE: Using the widget is **only** possible if you use matplotlibs `"PyQt5"` backend!

- To open the widget, simply press `w` on the keyboard while the mouse-pointer is hoovering the map.
- The `?` button on the top left can be used to activate showing help-tooltips if you hoover over the controls explain their functionalities.

<img width=30% src=https://user-images.githubusercontent.com/22773387/196920135-71da93dc-77c9-4bdd-b72d-4c63a5e6d841.png> <img width=30% src=https://user-images.githubusercontent.com/22773387/196920247-8093ff0e-a65a-4a79-9c38-104d405178f6.png> <img width=30% src=https://user-images.githubusercontent.com/22773387/196920331-6a7a3395-e57f-4850-9a27-9352a12d3268.png>

📖 Checkout the corresponding section in the docs for more details! [🧰 Companion Widget](https://eomaps.readthedocs.io/en/latest/api.html#companion-widget)

✏️ Draw shapes on the map
There is a new functionality to draw simple (geo-coded) shapes on the map!

<img src=https://user-images.githubusercontent.com/22773387/173678067-1c4b49ca-f049-43d3-8c89-7e6be88f27fa.gif width=50%>

📖 Checkout the corresponding section in the docs for more details! [✏️ Draw shapes on the map](https://eomaps.readthedocs.io/en/latest/api.html#draw-shapes-on-the-map)

⧉ Multi Layers
It is now possible to create "multi-layers" which inherit their artists from existing layers.
The layer-name hereby consists of existing layer-names separated by `"|"`.

To show the layers `"first"` and `"second"` at the same time, use:

python
m.show_layer("first|second")


- If you view a multi-layer, ALL artists from the constituting layers will be shown!
- E.g.: `"first|second|third"` will show all artists of the layers `"first"`, `"second"` and `"third"`
- The "vertical stacking order" for plotting is still exclusively determined by the `zorder` property of the artists!
- (artists at the same zorder are ordered with respect to the creation-time)
- It is possible (however rarely useful) to create a `Maps` object representing multi-layers
- Its artists will then only be shown if all constituting layers are visible

📖 Checkout the corresponding section in the docs for more details! [🚀 Basics/Layers](https://eomaps.readthedocs.io/en/latest/api.html#layers)

🏗️ Updates for the **Layout Editor**
- Select (and edit) **multiple axes** by holding `shift` while clicking on the axes
- Scaling the axes-size (with the scroll-wheel or the `+/-` buttons) now preserves the **center** of the axis
- If you hold down `control` while a colorbar is selected, the scroll wheel (or the `+/-` buttons) will adjust
the relative size between the colorbar and the histogram
- If you hold down `h` (or `v`) the scroll-wheel adjusts only the horizontal (or vertical) size of the axes

📖 Checkout the corresponding section in the docs for more details! [🏗️ Layout Editor](https://eomaps.readthedocs.io/en/latest/api.html#layout-editor)

🗺️ Set map-extent via OpenStreetMap Nominatim query
- There is now a method to set the extent of the map via a OSM query.
python
m = Maps()
m.set_extent_to_location("Austria")
m.add_wms.OpenStreetMap.add_layer.default()

📷 Snapshots for JupyterNotebooks
- The new `m.shapshot()` functionality allows you to plot static snapshots of a map
in Jupyter Notebooks (or in the IPython console) irrespective of the used backend.

👓 Updates for peek-layer callbacks:
- It is now possible to use **transparency** when peeking on a layer!
`m.cb.click.attach.peek_layer(layer="some layer", alpha=.5)`
- There's a new option `how="full"` to overlay another layer on the whole axis
- The size of the square used for peeking (e.g. `how=0.5`) is now always with respect to the smallest axis-dimension

... additional new features ...
- Equi7Grid projections can now be accessed via explicit names (e.g.: `Equi7_EU`, `Equi7_AF`...)
- Any colormap created by EOmaps during runtime is now always registered as a matplotlib colormap
- It is now possible to add logos to specific layers by using: `m.add_logo(layer=...)`
- 🛰️ New WebMap services
- `m.add_wms.OpenStreetMap.OSM_wms`
- `m.add_wms.OpenStreetMap.OSM_landuse`

Dynamic artists are now layer-sensitive!
- annotations and markers can now be added to specific layers:
`m.add_annotation(layer=...)` and `m.add_marker(layer=...)`
- To add dynamic artists on specific layers, simply use `m.BM.add_artist(<artist>, layer=...)`
(to make the artist visible on all layers, simply use `layer="all"`)

🌦️ (non-breaking) Changes
- obsolete arguments `radius` and `radius_crs` have been removed from `m.set_shape.raster()`
- the default radius for `m.set_shape.geod_circles` has been set to 1km

🔨 Fixes
- fix default style kwarg for wms layers
- remove obsolete shape arguments
- fix custom args for feature presets
- fix _on_layer_change actions
- fix fetching wmts services
- fix passing kwargs to wms and wmts services added to the active layer
- fix updating background layers on add/remove of artists
- fix handling of encoded NetCDF data