Eomaps

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`

... another bugfix release

🌦️ changes
- an AssertionError is now raised if data- and coordinate dimensions do not match
(to avoid treating datasets with equal size but different shape as valid 1D inputs)

🔨 fixes
- fix re-projection of data provided with 1D coordinates and 2D data-values (e.g. raster-data)
- fix treatment of nan-values for datashader plots
- update docs for NaturalEarth features and GeoDataFrames

... some more quick fixes
🔨 fixes
- fix rotation angle of ellipses
- remove unnecessary print command
- fix treatment of plot_specs kwargs (vmin, vmax, cmap etc...) in Maps.from_file
- fix defaultargs in add_gdf

A minor bugfix release

🌦️ changes
- 🚀 major speedup and reduced memory consumption for very large datasets
- new way for indexing picked pixels (uses much less ram with similar performance)
- the `pick_distance` argument of `Maps()` now specifies the search-rectangle for identifying picked pixels
- a rectangle of `radius * pick_distance` x `radius * pick_distance` around the center of the clicked pixel is used

🔨 fixes
- fix deleting callbacks from within a callback
- fix automatic identification of Equi7Grid crs
- fix treatment of numerical wms-layer names
- fix intersection of gdf with crs domain
- fix Maps.read_file should be a classmethod
- fix deleting data_specs when figure is closed

🌳 New

⭐ New bindings for the awesome [datashader](https://datashader.org/) library!
- Particularly useful to speed up plotting of **extremely large datasets** (>10M datapoints)
- Requires `datashader` to be installed (e.g. `conda install -c conda-forge datashader`)
- To use "datashader" for rendering the map, set the `plot-shape` to:
- `m.set_shape.shade_points(...)` :
use datashader to "shade" the data with infinitesimal points
- `m.set_shape.shade_raster(...)` :
(only for rectangular datasets with data_crs=plot_crs)
use datashader to "shade" the data as a dynamically updated QuadMesh

⭐ It is now possible to add a **Compass** (or a **North-Arrow**) to the map!
- simply use `c = m.add_compass(...)`
- the compass is dynamically updated on zoom events and can be dragged around with the mouse!

⭐ EOmaps now has some basic readers for common data-types (NetCDF, GeoTIFF, CSV)
- Requires `xarray`, `rioxarray` and `pandas`
- Use `gdf = m.read_file.NetCDF(...)` to read all relevant data
- Use `m = Maps.from_file.NetCDF(...)` to directly initialize a ``Maps``-object from a file
- Use `m2 = m.new_layer_from_file.NetCDF(...)` to add a new layer to an existing ``Maps`` object from a file

⭐ Support for Equi7Grid projection
- EOmaps now provides a cartopy-compatible crs for [Equi7Grid](https://github.com/TUW-GEO/Equi7Grid) projections!
- Requires `equi7grid` to be installed (e.g. `pip install equi7grid`)
python
from eomaps.projections import Equi7Grid_projection
m = Maps(Equi7Grid_projection("EU")


⭐ New clipping & re-projection methods for GeoDataFrames
- `m.add_gdf()` and `m.add_feature()` now have 2 new arguments: `reproject` and `clip`
(useful to avoid re-projection issues):
- `reproject` lets you select between geopandas (="gpd") and "cartopy" for re-projecting the geometries
- `clip` lets you select multiple ways for clipping the data prior to plotting
- "crs", "crs_bounds", "extent", "gdal_SymmetricDifference", "gdal_Intersection" and "gdal_Difference"

🌦️ changes
- The pixel-radius is now estimated using a more robust method if no explicit radius is provided.
- it's based on the median of the nearest-neighbour distances for the first 100k datapoints
- the number of datapoints used to estimate the radius can be adjusted by setting
`m.set_shape.radius_estimation_range `
- The `title` argument of `m.set_plot_specs` is now depreciated... use `m.ax.set_title()` instead!

⚙️ fixes
- fix `MapsGrid` crs-specifications with pyproj and `numpy`-dtypes
- fix skipping re-projection if "in-crs" == "plot_crs"
- fix `MapsGrid` has no attribute `preferred_wms_service`
- fix 'radius' estimation for shapes that do not explicitly require a radius
- fix background-layers need to be re-fetched if the figure canvas is resized
- clear data from memory if the figure is closed
- fix masking of nan-values prior to plotting
- `m.add_colorbar()` now supports setting the number of bins used to draw the histogram via the `histbins` kwarg
- make sure that zoom and close callbacks are only attached once to the figure
- fix delayed fetching of RestAPI services