Added plotting backend comparison #83

docs/get-started.md

@@ -4,7 +4,11 @@ This Get Started guide is intended as a quick way to start programming with **le
 
 ## Important Note
 
-`leafmap` has three plotting backends: [folium](https://github.com/python-visualization/folium), [ipyleaflet](https://github.com/jupyter-widgets/ipyleaflet), and [here-map-widget-for-jupyter](https://github.com/heremaps/here-map-widget-for-jupyter). If you are using `leafmap` with Jupyter installed locally, `import leafmap` will use the `ipyleaflet` plotting backend by default. If you are using `leafmap` with [Google Colab](https://githubtocolab.com/giswqs/leafmap/blob/master/examples/notebooks/01_leafmap_intro.ipynb), `import leafmap` will use the `folium` plotting backend by default. Note that Google Colab does not yet support `ipyleaflet` ([source](https://github.com/googlecolab/colabtools/issues/498#issuecomment-695335421)). Therefore, you won't be able to access the `leafmap` toolbar in Colab. Note that the backends do not offer equal functionality. Some interactive functionality in `ipyleaflet` might not be available in `folium` or `heremap`. To use a specific plotting backend, use one of the following:
+The `leafmap` package has three plotting backends, including [folium](https://github.com/python-visualization/folium), [ipyleaflet](https://github.com/jupyter-widgets/ipyleaflet), and [heremap](https://github.com/heremaps/here-map-widget-for-jupyter). An interactive map created using one of the plotting backends can be displayed in a Jupyter environment, such as Google Colab, Jupyter Notebook, and JupyterLab. By default, `import leafmap` in [Jupyter Notebook](https://gishub.org/leafmap-pangeo) and [JupyterLab](https://gishub.org/leafmap-binder) will use the `ipyleaflet` plotting backend, whereas `import leafmap` in [Google Colab](https://gishub.org/leafmap-colab) will use the `folium` plotting backend. Note that Google Colab does not yet support custom widgets, such as `ipyleaflet` and `heremap` ([source](https://github.com/googlecolab/colabtools/issues/498#issuecomment-695335421)). Therefore, interactive maps created using the `ipyleaflet` and `heremap` backends won't show up in Google Colab, even though the code might run successfully without any errors.
+
+The three plotting backends do not offer equal functionality. The `ipyleaflet` plotting backend provides the richest interactive functionality, including the custom toolbox for loading, analyzing, and visualizing geospatial data interactively without coding. For example, users can add vector data (e.g., GeoJSON, Shapefile, KML, GeoDataFrame) and raster data (e.g., GeoTIFF, Cloud Optimized GeoTIFF) to the map with a few clicks. Users can also perform geospatial analysis using the WhiteboxTools GUI with 470+ geoprocessing tools directly within the map interface. Other interactive functionality (e.g., split-panel map, linked map, time slider, time-series inspector) can also be useful for visualizing geospatial data. The `ipyleaflet` package is built upon `ipywidgets` and allows bidirectional communication between the front-end and the backend enabling the use of the map to capture user input ([source](https://blog.jupyter.org/interactive-gis-in-jupyter-with-ipyleaflet-52f9657fa7a)). In contrast, `folium` has relatively limited interactive functionality. It is meant for displaying static data only. The `folium` plotting backend is included in this package to support using `leafmap` in Google Colab. Note that the aforementioned custom toolbox and interactive functionality are not available for the `folium` plotting backend. Compared with `ipyleaflet` and `folium`, the `heremap` plotting backend provides some unique [3D functionality](https://github.com/heremaps/here-map-widget-for-jupyter#use-ipywidgets-controls-to-build-an-interactive-gui) for visualizing geospatial data. An [API key](https://developer.here.com/documentation/identity-access-management/dev_guide/topics/dev-apikey.html) from the [Here Developer Portal](https://developer.here.com/) is required to use `heremap`.
+
+To use a specific plotting backend, use one of the following:
 
 -   `import leafmap.leafmap as leafmap`
 -   `import leafmap.foliumap as leafmap`
@@ -13,7 +17,7 @@ This Get Started guide is intended as a quick way to start programming with **le
 ## Launch Jupyter notebook
 
 ```bash
-conda activate geo
+conda activate env_name
 jupyter notebook
 ```
 
@@ -54,6 +58,7 @@ export HEREMAPS_API_KEY=YOUR-ACTUAL-API-KEY
 ```python
 import os
 import leafmap.heremap as leafmap
+os.environ["HEREMAPS_API_KEY"] = "YOUR_HEREMAPS_API_KEY"
 api_key = os.environ.get("HEREMAPS_API_KEY") # read api_key from environment variable.
 m = leafmap.Map(api_key=api_key, center=(40, -100), zoom=4)
 m

docs/index.md

@@ -24,7 +24,7 @@
 
 ## Introduction
 
-**Leafmap** is a Python package for interactive mapping and geospatial analysis with minimal coding in a Jupyter environment. It is a spin-off project of the [geemap](https://geemap.org) Python package, which was designed specifically to work with [Google Earth Engine](https://earthengine.google.com) (GEE). However, not everyone in the geospatial community has access to the GEE cloud computing platform. Leafmap is designed to fill this gap for non-GEE users. It is a free and open-source Python package that enables users to analyze and visualize geospatial data with minimal coding in a Jupyter environment, such as Google Colab, Jupyter notebook, and JupyterLab. Leafmap is built upon a number of open-source packages, such as [folium](https://github.com/python-visualization/folium), [ipyleaflet](https://github.com/jupyter-widgets/ipyleaflet), and [here-map-widget-for-jupyter](https://github.com/heremaps/here-map-widget-for-jupyter) (for creating interactive maps), [WhiteboxTools](https://github.com/jblindsay/whitebox-tools) and [whiteboxgui](https://github.com/giswqs/whiteboxgui) (for analyzing geospatial data), and [ipywidgets](https://github.com/jupyter-widgets/ipywidgets) (for designing interactive graphical user interface [GUI]). The WhiteboxTools library currently contains **470+** tools for advanced geospatial analysis, which are each grouped based on their main function into one of the following categories. Users can access these tools via whiteboxgui directly within the leafmap user interface without writing a single line of code.
+**Leafmap** is a Python package for interactive mapping and geospatial analysis with minimal coding in a Jupyter environment. It is a spin-off project of the [geemap](https://geemap.org) Python package, which was designed specifically to work with [Google Earth Engine](https://earthengine.google.com) (GEE). However, not everyone in the geospatial community has access to the GEE cloud computing platform. Leafmap is designed to fill this gap for non-GEE users. It is a free and open-source Python package that enables users to analyze and visualize geospatial data with minimal coding in a Jupyter environment, such as Google Colab, Jupyter notebook, and JupyterLab. Leafmap is built upon a number of open-source packages, such as [folium](https://github.com/python-visualization/folium), [ipyleaflet](https://github.com/jupyter-widgets/ipyleaflet), and [heremap](https://github.com/heremaps/here-map-widget-for-jupyter) (for creating interactive maps), [WhiteboxTools](https://github.com/jblindsay/whitebox-tools) and [whiteboxgui](https://github.com/giswqs/whiteboxgui) (for analyzing geospatial data), and [ipywidgets](https://github.com/jupyter-widgets/ipywidgets) (for designing interactive graphical user interface [GUI]). The WhiteboxTools library currently contains **470+** tools for advanced geospatial analysis, which are each grouped based on their main function into one of the following categories. Users can access these tools via whiteboxgui directly within the leafmap user interface without writing a single line of code.
 
 -   [Data Tools](https://jblindsay.github.io/wbt_book/available_tools/data_tools.html)
 -   [Geomorphometric Analysis](https://jblindsay.github.io/wbt_book/available_tools/geomorphometric_analysis.html)

docs/notebooks/00_key_features.ipynb

@@ -550,7 +550,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# os.environ[\"PLANET_API_KEY\"] = \"12345\""
+    "# os.environ[\"HEREMAPS_API_KEY\"] = \"12345\""
    ]
   },
   {

examples/notebooks/00_key_features.ipynb

@@ -550,7 +550,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# os.environ[\"PLANET_API_KEY\"] = \"12345\""
+    "# os.environ[\"HEREMAPS_API_KEY\"] = \"12345\""
    ]
   },
   {