Eomaps

A new major-release that comes with a lot of updates, performance improvements and some very nice new features!

> ❗ There are possibly breaking changes with respect to EOmaps v5.x ❗
> (... and a lot of old syntax from v3.x, v4.x and v5.x has been removed)
> - An overview of the most important changes is provided here: [⚙ From EOmaps v5.x to v6.x](https://eomaps.readthedocs.io/en/dev/FAQ.html#from-eomaps-v5-x-to-v6-x)

🌳 New

🌴 Performance improvements!
EOmaps v6.0 represents a major change in the internals for layer and data management.

◰ Data Management
🌟 Data is now dynamically pre-selected based on the visible extent prior to plotting, which provides a **huge speed-up** for:
- Zoom/pan on plots of very large datasets
- Initial startup of plots that show only a subset of the assigned datasets

> If you don't need to see the whole extent of the data, make sure to set the desired extent **before** calling `m.plot_map()` via
> - `m.set.extent()`
> - `m.set_extent_to_location()`

⧉ Composing layers
🌟 The interface to combine, stack or overlay layers has been greatly improved in terms of speed and usability.
- To overlay the layer `"B"` on top of the layer `"A"`, simply use `m.show_layer("A", "B")`
- To overlay a layer with a **global transparency**, provide a tuple of `(<layer-name>, <transparency>)`
e.g.: ``m.show_layer("A", ("B", 0.5))`` will overlay the layer `"B"` with 50% transparency
- Associated [🧰 Companion Widget](https://eomaps.readthedocs.io/en/latest/api.html#companion-widget) updates
- The order at which layers are selected in the `layer-dropdown` now determines the stacking order of the layers
- To change the stacking order, simply **re-arrange the (movable) layer-tabs** in the `Compare` and `Edit` views!).

🌲 new functionalities
- `m.set_extent()`: set the map extent
- `m.inherit_classification`: use the classification of a given Maps object (useful to avoid costly classifications for zoomed-in plots that show only a fraction of the data)
- `m.inherit_data()`: share the data between Maps objects
- `m.text()` add plain text
- `peek-layer` callbacks now support `"round"` peek-shapes in addition to rectangles!
- `m.cb.click.attach.peek_layer(shape="round")`
- checkout the new button in the "Peek Layer" section of the [🧰 Companion Widget](https://eomaps.readthedocs.io/en/latest/api.html#companion-widget)
- Control the behavior of WebMap services if the size of the axes or figure is changing
- `m.refetch_wms_on_size_change()`: toggle global behavior for WebMap services
- use `m.savefig(refetch_wms=False)` to avoid re-fetching WebMaps if you save figures at different dpi!


🔨 Fixes
- fix `val_color` for forwarded pick callbacks
- estimate shape radius for x- and y- direction separately when using 2D datasets
- fix transparency for cached background layers
- handle possible exceptions in companion-widget drawer tab
- make sure companion-widget dropdown does not close on layer-changes
- fix attaching pick callbacks prior to plotting datasets
- fix triggering re-draws of layers if artists are added to the "all" layer
- fix treatment of animated axes in layout editor
- fix cancelling save-file dialog
- fix compass behavior on figure size changes
- fix compass position and size on figure dpi changes
- fix handling of spines
- make sure inset-maps are always drawn above other maps
- avoid re-drawing the background when drawing shapes
- use `annotation_clip=True` for annotations by default
- adjust default zorders of shapes and webmaps

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