Eomaps

A release that brings a lot of updates on speed and memory management and some very nice (but possibly breaking) changes compared previous versions of EOmaps.

❗ IMPORTANT CHANGES ❗

⭐ Starting with EOmaps v3.4 all callbacks and colorbars are layer-specific !
This means that callbacks only trigger if the layer of the associated `Maps` object is visible!
(...and colorbars are only visible if the associated layer is visible)

- To trigger callbacks or add features & datasets independent of the visible layer, use `m.all.cb. ...`
(or attach them to a `Maps` object on the `"all"` layer)
- **Note:** `pick` callbacks now always react to the visible collection!
(except for the ones on the `"all"` layer)

python
m = Maps(layer=0)
m.cb.click.attach.annotate() this callback is ONLY executed if the layer 0 is visible

m1 = m.new_layer(layer=1)
m1.cb.click.attach.mark() this callback is ONLY executed if the layer 1 is visible

m.all.cb.click.attach.annotate() this callback is executed independent of the visible layer!


🍃 removed arguments
- the obsolete `"orientation"` argument has been removed from `Maps(...)`
(it set the colorbar-orientation which is now specified via `m.add_colorbar(orientation=...)`
---

🌳 NEW
- ⭐ `m.show()` can be used to make the associated layer visible. (a shortcut for `m.show_layer(m.layer)`
- ⭐ `m.BM.on_layer(...)` can be used to trigger functions if the visible layer changes.
- 🌟 WebMap layers are now lazily evaluated and only added to the map if the corresponding layer is actually visible.
- 🌟 [experimental feature] memory-mapping can now be used to avoid using up a lot of ram for very large datasets
- Intermediate datasets are stored as memory-mapped files in a temp-folder on disk to release memory
- By default memory-mapping is disabled! (to activate it, use: `m.plot_map(memmap=False)` )

🌦️ changes
- Adding data from files (e.g. `m.from_file` or `m.new_layer_from_file`) now **always** uses `"shade_raster"` as the default plot-shape (since EOmaps v3.3.2, raster-shading works perfectly fine with re-projected rasters as well)
- If a file with >2M data-points is plotted, only "shade" shapes are attempted by default to avoid overloading memory.
- only one colorbar is allowed for ``Maps`` objects (use multiple objects for multiple colorbars)

🔨 fixes
- Fix several issues with memory-leaks and garbage-collection of objects
- Fix autoscale_fraction not recognized when using `preset="bw"` in `m.add_scalebar`
- Maps objects are now properly garbage-collected
- Fix auto-scaling of scalebars for very small scales
- `Maps.from_file` now properly handles `pathlib.Path` objects
- Fix utility widget start-layer should be the currently visible layer
- Fix pick-events should only identify points on visible layers
- Fix `m.add_colorbar(log=True)` for horizontal colorbars
- Fix colorbar limit autoscaling
- Fix logo size changes on zoom
- Remove obsolete `layer` kwarg from `m.add_logo`
- Fix incorrect color-normalization for `shade_raster` or `shade_points` if `vmin/vmax` outside the data-range are used
(thanks to maxhollmann)

A minor bugfix release that brings some nice updates for raster-shading!

🌳 NEW
- ⭐ Raster-shading with `m.set_shape.shade_raster()` can now finally be used with re-projected datasets as well!
- The previous limitation `plot_crs == data_crs` is now gone for good 🥳

🔨 fixes
- fix issues for `m.util.layer_slider` when switching between xyz-WebMap layers if axis-extent changed
- fix glitches of dynamic artists during pan/zoom
- fix image parsing in github-pages jekyll parser

A minor bugfix release (that also brings some miscellaneous convenience functions)

🌳 NEW
(⭐: new feature, 🍃: new functionality for existing feature)
- ⭐ there's a new function `m.subplots_adjust()` for `Maps` and `MapsGrid` objects to quickly set the margins of the plots as well as the horizontal and vertical spacing between subplots:
python
m = Maps()
m.subplots_adjust(left=0.2, right=0.8, top=0.9, bottom=0.1)

python
mg = MapsGrid()
mg.subplots_adjust(left=0.2, right=0.8, top=0.9, bottom=0.1, hspace=0.05, wspace=0.15)

(these are just shortcuts for `m.figure.gridspec.update()` + `m.redraw()`)
- 🍃 `m.add_colorbar` now has an additional kwarg `log=True/False` to make the y-axis of the histogram logarithmic.
- 🍃 `m.add_scalebar` now provides style-presets via `preset="<preset-name>"`
- at the moment there's only 1 preset... more to come in future releases!
- `"bw"`: a simple black-and-white style without a background

🔨 fixes
- fix `m.savefig` with different dpi-settings requres a re-draw
- fix `m.plot_map` with `dynamic=True` does not require a update
- incorporated some updates to ensure that layers are only re-drawn if necessary
- make sure cached backgrounds are always re-drawn if new artists are added
- fix annotation in example 9 (still used old syntax)

A release with some nice new features and a lot of usability updates and fixes.
❗ note that there is a breaking change compared to <v3.2 (only affecting the ambiguous "layer" kwarg of dynamic artists (see 🌦️ changes below for details) )

🌳 NEW
(⭐: new feature, 🍃: new functionalities for existing features)
- ⭐ There's a new pre-defined WebMap service: `m.add_wms.GEBCO` that provides nice underwater topography (https://www.gebco.net/)
- ⭐ Theres a new function `m.redraw()` that can be used to force a re-draw of the entire figure
- ⭐ shortcuts for `mg.redraw` and `mg.util` have been added to `MapsGrid`
- 🍃 `m.add_wms. ... <layer>.set_extent_to_bbox()` now supports a new kwarg `shrink` which can be used to set the extent to a "shrinked" bbox (useful to avoid request-errors for tiles outside the bbox)
- 🍃 `m.add_colorbar` can now be used to add **individual colorbars for different plot-layers**
(the colorbars will always reflect the currently displayed layer)
- 🍃the `peek_layer` callback can now be used to either view one (or more) layers or to **overlay** one (or more) layers on top of the current background layer.
- 🍃 some major improvements have been implemented for fetching WebTiles from xyz-TileServer links.
- `m.add_wms.get_service` now supports using custom `wms`, `wmts`, `restAPI` or `xyz` services

🌦️ changes
- the ambiguous (and misleading) `layer` kwarg has finally been removed from dynamic artists.
(note this "layer" was NOT referring to the actual plot-layer but to the stacking of dynamic artists!)
- `layer` now always refers to the background layer name and not to the stack-order of dynamic artists!
- ❗ the plot-order of multiple artists on the same layer is now determined by matplotlib's `zorder` property.
- ❕ old: `m.cb.click.attach.mark(layer=5)` ➡️ new: `m.cb.click.attach.mark(zorder=5)`
- ❕ old: `m.cb.click.attach.annotate(layer=5)` ➡️ new: `m.cb.click.attach.annotate(zorder=5)`
- ❕ old: `m.BM.add_artist(art, layer=5)` ➡️ new: `m.BM.add_artist(art)` + `art.set_zorder(5)`
- all examples have been updated accordingly

🔨 fixes
- fix _onrelease() missing 1 required positional argument
- fix issues with `nbagg` and `ipympl` backends (e.g. jupyter notebooks)
- fix `plt.show` should only be called if we're in an interactive backend!
- fix some issues with the scalebar and colorbar
- re-work of `draggable_axes`
- fix maxzoom for stamen_watercolor layer

A release with some nice new features and a lot of fixes & improvements.
... Note: many parts of the [📚 documentation](https://eomaps.readthedocs.io/en/latest/) have been updated with small code-examples and images!

🌳 New

- ⭐ `m.add_annotation` and `m.add_marker` now support adding multiple objects in one go!
- ⭐ raster-shading with datashader now supports 2D arrays for values and coordinates (e.g. curvilinear QuadMeshes)
- ⭐ there's a new function `m.show_layer(name)` that provides a shortcut for switching the currently displayed layer
- ⭐ layer-names can now be arbitrary strings! (e.g. `Maps(layer=...)` or `m.plot_map(layer=...)`)
- ❗ The layer-name `"all"`, has a special meaning: all features on this layer will be visible in ALL other layers!

---

⭐ 🦜 Utility widgets !
EOmaps now has a slot for **utility widgets** that provides some nice tools to simplify common tasks.
- Utilities are accessible via `m.util.<...>`

At the moment, there are 2 utilities that simplify switching between layers:
- ⭐ `m.util.layer_selector()` : get a "legend-like" object with buttons that can be used to switch between layers
- ⭐ `m.util.layer_slider()` : get a slider that can be used to switch between layers

Checkout the [🦜 Utility widgets](https://eomaps.readthedocs.io/en/latest/api.html#utility-widgets) section in the docs and the updated example: [🛰 WebMap services and layer-switching](https://eomaps.readthedocs.io/en/latest/EOmaps_examples.html#webmap-services-and-layer-switching)

---

⭐🌈 Updates for the scalebar
The scalebar has been re-worked for a much improved "out-of-the-box" usability.
- By default, the scalebar is **now automatically re-scaled on pan/zoom events** based on the current extent of the map.
- the new `autoscale_fraction` argument can be used to set the relative size of the (autoscaled) scalebar
- the new `auto_position` argument can be used to set the position targeted for automatic re-positioning on pan/zoom events.
- The background patch is now automatically scaled to enclose the labels.
- When dragging the scalebar with the mouse, it is now immediately released if you release the mouse-button.

python
m.add_scalebar() get a scalebar that autoscales itself on pan/zoom events
m.add_scaleblar(scale=10000) get a scalebar with a fixed segment-separation of 10km


---


🌦️ changes
- some changes to `m.new_layer` :
- It now supports the additional `layer` kwarg
- ❗ By default ONLY the "plot-shape" is now copied to the new layer.
- this avoids side-effects from unintentional copying of plot-specs (`vmin` `vmax` etc.)
- you can still copy plot-specs by using `m.new_layer(copy_plot_specs=True)`
- `Maps.from_file` and `Maps.read_file` and `m.new_layer_from_file` now support using already opened NetCDF and GeoTIFF files

⚙️ fixes
- fix treatment of colorbar orientation in `m.figure.set_colorbar_position`
- fix reprojection of wms-layers with a native crs specified as "EPSG:3857"
- fix sorting of layer-names
- avoid identification of pixel-ID if no pick-callback is attached
- fix label-axis should not respond to navigation events
- fix adding multiple markers in one go
- fallback to WSG84 boundary in `wms_layer.set_bbox_to_extent()`

a minor bugfix release that introduces a new (optional) kwarg for `m.plot_map()`

🌳 New
- Checkout the new example! [🧮 Select 1D slices of 2D datasets](https://eomaps.readthedocs.io/en/latest/EOmaps_examples.html#select-1d-slices-of-a-2d-dataset)
(as suggested in 54)
- ⭐ There is a new (optional) kwarg `set_extent` for `m.plot_map(set_extent=True)`
- `set_extent=True` : set the plot-extent to the data extent
- `set_extent=False` : keep the plot-extent as it was before


🔨 fixes
- fix `m.new_layer()` when parent layer uses `shade_raster` or `shade_points`
(fixes `__call__() got an unexpected keyword argument 'glyph'`)
- allow overriding the permanent kwarg in `m.add_annotation`n `m.add_annotation`