Eomaps

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

Just a hotfix release
🔨 fixes
- fix `ImportError` for `TriMesh` when using `matpltolib >= 3.6`

Another bugfix release.

🌳 New
- Make sure to also have a look at the new features added in [EOmaps v4.4](https://github.com/raphaelquast/EOmaps/releases/tag/v4.4)!
- There is now an option to draw a an "outline" on top of the colorbar-histogram with:
- `m.add_colorbar(show_outline=True)` (for a black outline with linewidth 1)
- `m.add_colorbar(show_outline=dict(color="b", linewidth=2))` (for a custom outline)


🔨 Fixes
- fix using `m.cb.pick` callbacks with datasets assigned to the `"all"` layer
- raise error if undefined objects are passed to NetCDF and GeoTIFF readers
- fix using the LayoutEditor to move colorbars with "arrow-keys"
- fix default styles must be provided as list for wms and wmts services!

A quick bugfix release
🔨 Fixes
- fix providing kwargs to WebMap services (time, styles etc.)

----

A release that introduces 2 new functionalities: `m.add_line`, `m.cb.move` and the ability to use **keypress-modifiers** for callbacks!

🌳 New
🚲 A new method to quickly draw paths on a map!
- ⭐ `m.add_line()`: connect points via geodesic (or straight) lines!
- specify number of intermediate points per line-segment
- (alternatively) specify distance between intermediate points for each line-segment
- checkout the new [🚲 example](https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html#lines-and-annotations) and the corresponding section in the [📖 documentation!](https://eomaps.readthedocs.io/en/dev/api.html#lines)

<img src="https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/example_lines.png?raw=true" width=75%/>

🛸 New features for callbacks!

👾 Keypress-modifiers

It is now possible to assign multiple callbacks to **the same** mouse-button and use keyboard-shortcuts
to switch between the assigned callbacks!
(e.g. the callback will only be executed if the corresponding button is pressed on the keyboard)


- 🌟 simply provide the modifier of choice with the `modifier=...` argument!
- e.g.: `m.cb.click.attach.annotate(modifier="a")` : this callback will only be executed if the `"a"` key is pressed
- 🌟 You can make modifiers "sticky" (e.g. to keep them activated after the button is released) by using:
- `m.cb.click.set_sticky_modifiers("a", "b", "c")`
- "sticky modifiers" are assigned separately for `click`, `pick` and `move` callbacks
- to release a "sticky modifier" press `ctrl + <modifier key>` or `escape`

- checkout the corresponding section in the [📖 documentation!](https://eomaps.readthedocs.io/en/dev/api.html#using-modifiers-for-pick-click-and-move-callbacks)


⭐ `move` callbacks

There's now an explicit container to attach callbacks that are executed
**on mouse movement if NO button is clicked**

- NOTE: use `m.cb.click.attach...` to execute callbacks on mouse-movement if a button is clicked!
- and set `on_motion=False` to avoid executing the click-callback on mouse-movements

python
m = Maps()
m.add_feature.preset.coastline()
m.cb.move.attach.annotate()
m.cb.move.attach.mark(modifier=1, radius=2, radius_crs=4326, fc="none", ec="r")


🌦️ Changes
- ❗ `m.cb.click.attach.mark()` now uses `permanent=False` by default

- 🏞️ NaturalEarth features have been updated

<details>
<summary> click for a list of new features</summary>

python

{
10m_cultural: {'admin_0_countries_iso', 'parks_and_protected_lands', 'admin_0_countries_tlc'}
10m_physical: {'bathymetry_G_4000', 'graticules_20', 'bathymetry_K_200', 'bathymetry_E_6000', 'graticules_1', 'bathymetry_A_10000', 'bathymetry_F_5000', 'bathymetry_C_8000', 'bathymetry_B_9000', 'bathymetry_L_0', 'bathymetry_H_3000', 'bathymetry_I_2000', 'wgs84_bounding_box', 'bathymetry_J_1000', 'graticules_5', 'bathymetry_D_7000', 'graticules_30', 'graticules_10', 'graticules_15'}
110m_physical: {'graticules_15', 'graticules_20', 'graticules_1', 'wgs84_bounding_box', 'graticules_5', 'graticules_30', 'graticules_10'}
50m_physical: {'graticules_20', 'graticules_1', 'wgs84_bounding_box', 'graticules_5', 'graticules_30', 'graticules_10', 'graticules_15'}
}



</details>


🔨 Fixes
- fix sharing boundary and inset-marker properties for inset-maps
- fix issues with invalid clipping shapes
- fix issues with geometries that cannot be exploded
- make sure temporary artists are cleared prior to executing callbacks
- fix issues with dynamically updated legends and temporary artists
- fix error when trying to update colorbar-arrows without a colorbar
- avoid re-fetching WebMap tiles if extent remains the same
- fix unnecessary re-draws of artists after overlay-actions

A new release that brings some nice updates and an awesome new **Layout-Editor**!

🌦️ Changes
- 🍃 utility-widgets now **auto-update** themselves if new layers are added to the map!
- to show only a subset of the available layers, use `m.util.layer_selector(layers=["layer1", ...])`
- 🍃 coastlines are no longer added by default when creating new layers from files (e.g. NetCDF, GeoTIFF etc.)
- (use `coastlines=True` or explicitly call `m.add_feature.preset.coastline()` to add coastlines!)
- 🍃 `m.add_gdf` now allows using a `path` to a file that can be read with `geopandas.read_file` instead of providing the `geopandas.GeoDataFrame` directly
- ❗ keyword-arguments for `m.new_inset_map` have changed!
- `edgecolor` and `linewidth` are depreciated and will be removed in next major versions!
- to set the properties of the boundary-polygon, use `m.new_inset_map(boundary=dict(fc="r", lw=1)` instead
- ❗ `m.cb.dynamic` has been removed
🌳 New

⭐ New accessor for classification schemes
The new classification-schemes accessor 🌟 `m.set_classify` provides **autocompletion** and proper **docstrings**!
(you can use it just as you would use `m.set_classify_specs`)

Just select the scheme you want to use and call it with the relevant parameters:
python
m = Maps()
m.set_data(...)
m.set_classify.Quantiles(k=5)
m.plot_map(...)

alternative (old) way to set the classification:
m.set_classify_specs(scheme="Quantiles", k=5)



⭐ There's a new [🏗️ Layout Editor](https://eomaps.readthedocs.io/en/latest/api.html#layout-editor) to quickly re-arrange the subplots of a figure!
<img src=https://user-images.githubusercontent.com/22773387/176476897-119658ca-0882-4880-a906-7af787887a3d.gif width=65%>

The **Layout Editor** can be used to quickly re-arrange the position of all axes in the figure.
(works for maps, colorbars, inset-maps, ordinary matplotlib plots etc.)
- You can save and re-apply a layout with:
- 🌟`m.get_layout()`: get the current layout (or dump the layout as a json-file)
- 🌟`m.apply_layout()`: apply a given layout (or load and apply the layout from a json-file)
- 🌟`m.edit_layout(filepath=...)`: enter LayoutEditor and (optionally) save layout as a json-file on exit

To quickly enter/exit Layout Editor, simply use the assigned keyboard-shortcuts:
- press `ALT + L` to enter the **LayoutEditor** mode
- press `ALT + L` again or `escape` to exit the **LayoutEditor**

Have a look at the new section in the [📖 documentation](https://eomaps.readthedocs.io/en/latest/api.html#layout-editor) for more details!

🔨 Fixes
- fix recognizing the parent layer when initializing utility-widgets from the parent Maps object
- fix layer-selectors should indicate no active layer if the active layer is not part of the widget
- updates for inset-maps
- add fix for reprojection issues with certain projections
- fix reprojection sometimes masks certain shapes