Source code for grass.jupyter.interactivemap

#
# AUTHOR(S): Caitlin Haedrich <caitlin DOT haedrich AT gmail>
#            Anna Petrasova <kratochanna AT gmail>
#
# PURPOSE:   This module contains functions for interactive visualizations
#            in Jupyter Notebooks.
#
# COPYRIGHT: (C) 2021-2024 Caitlin Haedrich, and by the GRASS Development Team
#
#            This program is free software under the GNU General Public
#            License (>=v2). Read the file COPYING that comes with GRASS
#            for details.

"""Interactive visualizations map with folium or ipyleaflet"""

import base64
import json
from .reprojection_renderer import ReprojectionRenderer


[docs]def get_backend(interactive_map): """Identifies if interactive_map is of type folium.Map or ipyleaflet.Map. Returns "folium" or "ipyleaflet". """ try: import folium # pylint: disable=import-outside-toplevel except ImportError: return "ipyleaflet" isfolium = isinstance(interactive_map, folium.Map) if isfolium: return "folium" return "ipyleaflet"
[docs]class Layer: # pylint: disable=too-few-public-methods """Base class for overlaing raster or vector layer on a folium or ipyleaflet map. """ def __init__( self, name, title=None, use_region=False, saved_region=None, renderer=None, **kwargs, ): """Reproject GRASS raster, export to PNG, and compute bounding box. param str name: layer name param str title: title of layer to display in layer control legend param bool use_region: use computational region of current mapset param str saved_region: name of saved computation region param renderer: instance of ReprojectionRenderer **kwargs: keyword arguments passed to folium/ipyleaflet layer instance """ self._name = name self._layer_kwargs = kwargs self._title = title if not self._title: self._title = self._name if not renderer: self._renderer = ReprojectionRenderer( use_region=use_region, saved_region=saved_region ) else: self._renderer = renderer
[docs]class Raster(Layer): """Overlays rasters on a folium or ipyleaflet map. Basic Usage: >>> m = folium.Map() >>> gj.Raster("elevation", opacity=0.5).add_to(m) >>> m >>> m = ipyleaflet.Map() >>> gj.Raster("elevation", opacity=0.5).add_to(m) >>> m """ def __init__( self, name, title=None, use_region=False, saved_region=None, renderer=None, **kwargs, ): """Reproject GRASS raster, export to PNG, and compute bounding box.""" super().__init__(name, title, use_region, saved_region, renderer, **kwargs) # Render overlay # By doing this here instead of in add_to, we avoid rendering # twice if added to multiple maps. This mimics the behavior # folium.raster_layers.ImageOverlay() self._filename, self._bounds = self._renderer.render_raster(name)
[docs] def add_to(self, interactive_map): """Add raster to map object which is an instance of either folium.Map or ipyleaflet.Map""" if get_backend(interactive_map) == "folium": import folium # pylint: disable=import-outside-toplevel # Overlay image on folium map image = folium.raster_layers.ImageOverlay( image=self._filename, bounds=self._bounds, name=self._title, **self._layer_kwargs, ) image.add_to(interactive_map) else: import ipyleaflet # pylint: disable=import-outside-toplevel # ImageOverlays don't work well with local files, # they need relative address and behavior differs # for notebooks and jupyterlab with open(self._filename, "rb") as file: data = base64.b64encode(file.read()).decode("ascii") url = "data:image/png;base64," + data image = ipyleaflet.ImageOverlay( url=url, bounds=self._bounds, name=self._title, **self._layer_kwargs ) interactive_map.add(image)
[docs]class Vector(Layer): """Adds vectors to a folium or ipyleaflet map. Basic Usage: >>> m = folium.Map() >>> gj.Vector("roadsmajor").add_to(m) >>> m >>> m = ipyleaflet.Map() >>> gj.Vector("roadsmajor").add_to(m) >>> m """ def __init__( self, name, title=None, use_region=False, saved_region=None, renderer=None, **kwargs, ): """Reproject GRASS vector and export to GeoJSON.""" super().__init__(name, title, use_region, saved_region, renderer, **kwargs) self._filename = self._renderer.render_vector(name)
[docs] def add_to(self, interactive_map): """Add vector to map""" if get_backend(interactive_map) == "folium": import folium # pylint: disable=import-outside-toplevel folium.GeoJson( str(self._filename), name=self._title, **self._layer_kwargs ).add_to(interactive_map) else: import ipyleaflet # pylint: disable=import-outside-toplevel with open(self._filename, "r", encoding="utf-8") as file: data = json.load(file) # allow using opacity directly to keep interface # consistent for both backends if "opacity" in self._layer_kwargs: opacity = self._layer_kwargs.pop("opacity") if "style" in self._layer_kwargs: self._layer_kwargs["style"]["opacity"] = opacity else: self._layer_kwargs["style"] = {"opacity": opacity} geo_json = ipyleaflet.GeoJSON( data=data, name=self._title, **self._layer_kwargs ) interactive_map.add(geo_json)
[docs]class InteractiveMap: """This class creates interactive GRASS maps with folium or ipyleaflet. Basic Usage: >>> m = InteractiveMap() >>> m.add_vector("streams") >>> m.add_raster("elevation") >>> m.add_layer_control() >>> m.show() """ def __init__( self, width=400, height=400, tiles="CartoDB positron", API_key=None, # pylint: disable=invalid-name use_region=False, saved_region=None, map_backend=None, ): """Creates a blank folium/ipyleaflet map centered on g.region. If map_backend is not specified, InteractiveMap tries to import ipyleaflet first, then folium if it fails. The backend can be specified explicitely with valid values "folium" and "ipyleaflet" . In case of folium backend, tiles parameter is passed directly to folium.Map() which supports several built-in tilesets (including "OpenStreetMap", "Stamen Toner", "Stamen Terrain", "Stamen Watercolor", "Mapbox Bright", "Mapbox Control Room", "CartoDB positron", "CartoDB dark_matter") as well as custom tileset URL (i.e. "http://{s}.yourtiles.com/{z}/{x}/{y}.png"). For more information, visit folium documentation: https://python-visualization.github.io/folium/modules.html In case of ipyleaflet, only the tileset name and not the URL is currently supported. Raster and vector data are always reprojected to Pseudo-Mercator. With use_region=True or saved_region=myregion, the region extent is reprojected and the number of rows and columns of that region is kept the same. This region is then used for reprojection. By default, use_region is False, which results in the reprojection of the entire raster in its native resolution. The reprojected resolution is estimated with r.proj. Vector data are always reprojected without any clipping, i.e., region options don't do anything. :param int height: height in pixels of figure (default 400) :param int width: width in pixels of figure (default 400) :param str tiles: map tileset to use :param str API_key: API key for Mapbox or Cloudmade tiles :param bool use_region: use computational region of current mapset :param str saved_region: name of saved computation region :param str map_backend: "ipyleaflet" or "folium" or None """ self._ipyleaflet = None self._folium = None def _import_folium(error): try: import folium # pylint: disable=import-outside-toplevel return folium except ImportError as err: if error: raise err return None def _import_ipyleaflet(error): try: import ipyleaflet # pylint: disable=import-outside-toplevel return ipyleaflet except ImportError as err: if error: raise err return None if not map_backend: self._ipyleaflet = _import_ipyleaflet(error=False) if not self._ipyleaflet: self._folium = _import_folium(error=False) if not (self._ipyleaflet or self._folium): raise ImportError(_("Neither ipyleaflet nor folium found.")) elif map_backend == "folium": self._folium = _import_folium(error=True) elif map_backend == "ipyleaflet": self._ipyleaflet = _import_ipyleaflet(error=True) else: raise ValueError(_("Invalid map backend, use 'folium' or 'ipyleaflet'")) if self._ipyleaflet: import ipywidgets as widgets # pylint: disable=import-outside-toplevel import xyzservices # pylint: disable=import-outside-toplevel # Store height and width self.width = width self.height = height if self._ipyleaflet: basemap = xyzservices.providers.query_name(tiles) if API_key and basemap.get("accessToken"): basemap["accessToken"] = API_key layout = widgets.Layout(width=f"{width}px", height=f"{height}px") self.map = self._ipyleaflet.Map( basemap=basemap, layout=layout, scroll_wheel_zoom=True ) else: self.map = self._folium.Map( width=self.width, height=self.height, tiles=tiles, API_key=API_key, # pylint: disable=invalid-name ) # Set LayerControl default self.layer_control = False self.layer_control_object = None self._renderer = ReprojectionRenderer( use_region=use_region, saved_region=saved_region )
[docs] def add_vector(self, name, title=None, **kwargs): """Imports vector into temporary WGS84 location, re-formats to a GeoJSON and adds to map. :param str name: name of vector to be added to map; positional-only parameter :param str title: vector name for layer control :**kwargs: keyword arguments passed to GeoJSON overlay """ Vector(name, title=title, renderer=self._renderer, **kwargs).add_to(self.map)
[docs] def add_raster(self, name, title=None, **kwargs): """Imports raster into temporary WGS84 location, exports as png and overlays on a map. Color table for the raster can be modified with `r.colors` before calling this function. .. note:: This will only work if the raster is located in the current mapset. To change the color table of a raster located outside the current mapset, switch to that mapset with `g.mapset`, modify the color table with `r.color` then switch back to the initial mapset and run this function. :param str name: name of raster to add to display; positional-only parameter :param str title: raster name for layer control :**kwargs: keyword arguments passed to image overlay """ Raster(name, title=title, renderer=self._renderer, **kwargs).add_to(self.map)
[docs] def add_layer_control(self, **kwargs): """Add layer control to display" Accepts keyword arguments to be passed to layer control object""" self.layer_control = True if self._folium: self.layer_control_object = self._folium.LayerControl(**kwargs) else: self.layer_control_object = self._ipyleaflet.LayersControl(**kwargs)
[docs] def show(self): """This function returns a folium figure or ipyleaflet map object with a GRASS raster and/or vector overlaid on a basemap. If map has layer control enabled, additional layers cannot be added after calling show().""" self.map.fit_bounds(self._renderer.get_bbox()) if self._folium: if self.layer_control: self.map.add_child(self.layer_control_object) fig = self._folium.Figure(width=self.width, height=self.height) fig.add_child(self.map) return fig # ipyleaflet if self.layer_control: self.map.add(self.layer_control_object) return self.map
[docs] def save(self, filename): """Save map as an html map. :param str filename: name of html file """ self.map.save(filename)