Merge pull request #267 from raphaelquast/dev

Merge for v8.4

Author: raphaelquast

.github/workflows/testMaps.yml

@@ -13,7 +13,7 @@ jobs:
         # set operating systems to test
         os: [ubuntu-latest]
         # set python versions to test
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     name: test_Maps ${{ matrix.os }}  ${{ matrix.python-version }}
     steps:

docs/source/_static/example_images/example_inset_maps.png

@@ -8,6 +8,10 @@
     "version": "dev",
     "url": "https://eomaps.readthedocs.io/en/dev/"
   },
+  {
+    "version": "v8.4",
+    "url": "https://eomaps.readthedocs.io/en/v8.4/"
+  },
   {
     "version": "v8.3.3",
     "url": "https://eomaps.readthedocs.io/en/v8.3.3/"

docs/source/_static/example_images/example_location_indicator.gif

@@ -46,6 +46,7 @@ Layers and Maps
 
     Maps.new_map
     Maps.new_inset_map
+    Maps.new_subplot
 
 
 .. autosummary::

docs/source/_static/version_switcher.json

@@ -72,6 +72,7 @@ In addition, you can use the following dependency-groups to activate only select
 - ``pip install eomaps[io]`` Add support for ``pandas``, ``xarray``, ``geopandas`` and ``rioxarray``
 - ``pip install eomaps[shade]`` Add capabilities to visualize extremely large datasets (via ``datashader``)
 - ``pip install eomaps[classify]`` Add support for ``mapclassify`` to classify datasets
+- ``pip install eomaps[docs]`` Install all required dependencies to build the docs
 
 It is also possible to combine dependency-groups, e.g.: ``pip install eomaps[wms, gui]``.
 

docs/source/api/eomaps.eomaps.Maps.rst

@@ -510,7 +510,7 @@ def cb(*args, **kwargs):
         if _log.getEffectiveLevel() <= 10:
             logmsg = (
                 f"Adding {'persistent' if persistent else 'single-shot'} "
-                f"layer change action for: '{layer}'"
+                f"layer change action for: '{layer if layer else 'all layers'}': {getattr(func, '__qualname__', func)}"
             )
             _log.debug(logmsg)
 
@@ -903,14 +903,14 @@ def _on_draw_cb(self, event):
             if loglevel <= 5:
                 _log.log(5, "There was an error during draw!", exc_info=True)
 
-    def add_artist(self, art, layer=None):
+    def add_artist(self, *artists, layer=None):
         """
         Add a dynamic-artist to be managed.
         (Dynamic artists are re-drawn on every update!)
 
         Parameters
         ----------
-        art : Artist
+        artists : Artist
 
             The artist to be added.  Will be set to 'animated' (just
             to be safe).  *art* must be in the figure associated with
@@ -922,38 +922,38 @@ def add_artist(self, art, layer=None):
 
             The default is None in which case the layer of the base-Maps object is used.
         """
-
-        if art.figure != self.figure:
-            raise RuntimeError(
-                "EOmaps: The artist does not belong to the figure"
-                "of this Maps-object!"
-            )
-
         if layer is None:
             layer = self._m.layer
 
         # make sure all layers are converted to string
         layer = str(layer)
 
-        self._artists.setdefault(layer, list())
+        for art in artists:
+            if art.figure != self.figure:
+                raise RuntimeError(
+                    "EOmaps: The artist does not belong to the figure"
+                    "of this Maps-object!"
+                )
 
-        if art in self._artists[layer]:
-            return
-        else:
-            art.set_animated(True)
-            self._artists[layer].append(art)
+            self._artists.setdefault(layer, list())
 
-            if isinstance(art, plt.Axes):
-                self._managed_axes.add(art)
+            if art in self._artists[layer]:
+                continue
+            else:
+                art.set_animated(True)
+                self._artists[layer].append(art)
 
-    def add_bg_artist(self, art, layer=None, draw=True):
+                if isinstance(art, plt.Axes):
+                    self._managed_axes.add(art)
+
+    def add_bg_artist(self, *artists, layer=None, draw=True):
         """
         Add a background-artist to be managed.
         (Background artists are only updated on zoom-events... they are NOT animated!)
 
         Parameters
         ----------
-        art : Artist
+        artists : Artist
             The artist to be added.  Will be set to 'animated' (just
             to be safe).  *art* must be in the figure associated with
             the canvas this class is managing.
@@ -974,31 +974,32 @@ def add_bg_artist(self, art, layer=None, draw=True):
         # make sure all layer names are converted to string
         layer = str(layer)
 
-        if art.figure != self.figure:
-            raise RuntimeError
+        for art in artists:
+            if art.figure != self.figure:
+                raise RuntimeError
 
-        # put all artist of inset-maps on dedicated layers
-        if (
-            getattr(art, "axes", None) is not None
-            and art.axes.get_label() == "inset_map"
-            and not layer.startswith("__inset_")
-        ):
-            layer = "__inset_" + str(layer)
+            # put all artist of inset-maps on dedicated layers
+            if (
+                getattr(art, "axes", None) is not None
+                and art.axes.get_label() == "inset_map"
+                and not layer.startswith("__inset_")
+            ):
+                layer = "__inset_" + str(layer)
 
-        if layer in self._bg_artists and art in self._bg_artists[layer]:
-            _log.info(
-                f"EOmaps: Background-artist '{art}' already added on layer '{layer}'"
-            )
-            return
+            if layer in self._bg_artists and art in self._bg_artists[layer]:
+                _log.info(
+                    f"EOmaps: Background-artist '{art}' already added on layer '{layer}'"
+                )
+                continue
 
-        art.set_animated(True)
-        self._bg_artists.setdefault(layer, []).append(art)
+            art.set_animated(True)
+            self._bg_artists.setdefault(layer, []).append(art)
 
-        if isinstance(art, plt.Axes):
-            self._managed_axes.add(art)
+            if isinstance(art, plt.Axes):
+                self._managed_axes.add(art)
 
-        # tag all relevant layers for refetch
-        self._refetch_layer(layer)
+            # tag all relevant layers for refetch
+            self._refetch_layer(layer)
 
         for f in self._on_add_bg_artist:
             f()

docs/source/installation.rst

@@ -916,9 +916,9 @@ def on_fetch_bg(self, layer=None, bbox=None, check_redraw=True):
                 self.m.ax.add_collection(coll, autolim=False)
 
             if self.m._coll_dynamic:
-                self.m.BM.add_artist(coll, self.layer)
+                self.m.BM.add_artist(coll, layer=self.layer)
             else:
-                self.m.BM.add_bg_artist(coll, self.layer)
+                self.m.BM.add_bg_artist(coll, layer=self.layer)
 
             self.m._coll = coll
 

eomaps/_blit_manager.py

@@ -990,7 +990,15 @@ def edit_layout(self, filepath=None):
     @wraps(GridSpec.update)
     def subplots_adjust(self, **kwargs):
         """Adjust the margins of subplots."""
-        self.parent._gridspec.update(**kwargs)
+        with self.delay_draw():
+            for m in (self.parent, *self.parent._children):
+                try:
+                    m.ax.get_gridspec().update(**kwargs)
+                except AttributeError:
+                    # TODO fix this properly
+                    # ignore gridspecs that don't provide an update method
+                    # (like GridSpecFromSubplotSpec)
+                    pass
         # after changing margins etc. a redraw is required
         # to fetch the updated background!
 
@@ -1220,6 +1228,38 @@ def _transf_lonlat_to_plot(self):
             self.crs_plot,
         )
 
+    def transform_plot_to_lonlat(self, x, y):
+        """
+        Transform plot-coordinates to longitude and latitude values.
+
+        Parameters
+        ----------
+        x, y : float or array-like
+            The coordinates values in the coordinate-system of the plot.
+
+        Returns
+        -------
+        lon, lat : The coordinates transformed to longitude and latitude values.
+
+        """
+        return self._transf_plot_to_lonlat.transform(x, y)
+
+    def transform_lonlat_to_plot(self, lon, lat):
+        """
+        Transform longitude and latitude values to plot coordinates.
+
+        Parameters
+        ----------
+        lon, lat : float or array-like
+            The longitude and latitude values to transform.
+
+        Returns
+        -------
+        x, y : The coordinates transformed to the plot-coordinate system.
+
+        """
+        return self._transf_lonlat_to_plot.transform(lon, lat)
+
     def on_layer_activation(self, func, layer=None, persistent=False, **kwargs):
         """
         Attach a callback that is executed if the associated layer is activated.

eomaps/_data_manager.py

@@ -13,6 +13,7 @@
 from urllib3.exceptions import InsecureRequestWarning
 from io import BytesIO
 from pprint import PrettyPrinter
+from textwrap import dedent
 
 from packaging import version
 
@@ -171,7 +172,7 @@ def add_legend(self, style=None, img=None):
             if not self._m.BM._layer_visible(self._layer):
                 legax.set_visible(False)
 
-            self._m.BM.add_artist(legax, self._layer)
+            self._m.BM.add_artist(legax, layer=self._layer)
 
             def cb_move(event):
                 if not self._legend_picked:
@@ -336,6 +337,17 @@ def _set_style(self, style=None):
 
         return style
 
+    def _get_layer_info_text(self):
+        """Get layer-specific info text of a given layer"""
+        t = ""
+        abstract = getattr(self.wms_layer, "abstract", None)
+        if abstract:
+            t += f"**Abstract**: <i>{abstract}</i>\n  \n----  \n  "
+
+        t += f"{dedent(getattr(self, '_EOmaps_info', ''))}"
+
+        return t
+
 
 class _WMTSLayer(_WebMapLayer):
     def __init__(self, *args, **kwargs):
@@ -440,7 +452,7 @@ def _do_add_layer(self, m, layer, **kwargs):
 
         # attach the info to the artist so it can be identified by the companion widget
         if hasattr(self, "_EOmaps_info"):
-            art._EOmaps_info = self._EOmaps_info
+            art._EOmaps_info = self._get_layer_info_text()
         if hasattr(self, "_EOmaps_source_code"):
             art._EOmaps_source_code = self._EOmaps_source_code
 
@@ -581,12 +593,10 @@ def _do_add_layer(self, m, layer, **kwargs):
         art = self._add_wms(
             m.ax, self._wms, self.name, interpolation="spline36", **kwargs
         )
-
         art.set_label(f"WebMap service: {self.name}")
-
         # attach the info to the artist so it can be identified by the companion widget
         if hasattr(self, "_EOmaps_info"):
-            art._EOmaps_info = self._EOmaps_info
+            art._EOmaps_info = self._get_layer_info_text()
         if hasattr(self, "_EOmaps_source_code"):
             art._EOmaps_source_code = self._EOmaps_source_code
 
@@ -1396,7 +1406,7 @@ def draw(self, renderer, *args, **kwargs):
                 # only re-fetch tiles if the extent has changed
                 located_images = self.raster_source.fetch_raster(
                     ax.projection,
-                    extent=[x1, x2, y1, y2],
+                    extent=list(map(float, [x1, x2, y1, y2])),
                     target_resolution=(window_extent.width, window_extent.height),
                 )
                 self.cache = located_images
@@ -1410,6 +1420,12 @@ def draw(self, renderer, *args, **kwargs):
                     # (otherwise the path might still correspond to a previous extent)
                     clippath._adjust_location()
 
+                    if clippath.get_path().vertices.size == 0:
+                        # in case the clip-path is an empty-path don't draw.
+                        # This is used to allow clipped-webmaps outside the
+                        # current field-of-view
+                        return
+
                     self.set_clip_path(
                         clippath.get_path(),
                         transform=self.axes.projection._as_mpl_transform(self.axes),