[SoC] GSoC Final Report: Improved Integration of GRASS GIS and Jupyter Notebooks

[Caitlin Haedrich]

Hello all,

Here is my final report on my GSoC project, Improved Integration of GRASS
GIS and Jupyter Notebooks. Thank you to all who provided comments, feedback
and tested my work in Binder. Also, a *huge* thank you to my mentors Vaclav
Petras, Helena Mitasova and Stefan Blumentrath.

You can find a more detailed version of this report on the wiki page:
https://trac.osgeo.org/grass/wiki/GSoC/2021/JupyterAndGRASS

You can also test out grass.jupyter, the subpackage I wrote this summer,
from your browser in Binder here:
https://mybinder.org/v2/gh/OSGeo/grass/c173461?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fgrass_jupyter.ipynb

Best,
Caitlin

*Improved Integration of GRASS GIS and Jupyter Notebooks*

*Abstract:*
This project introduces a new subpackage for GRASS GIS, grass.jupyter that
improves the integration of GRASS GIS with Jupyter Notebooks. The
grass.jupyter subpackage introduces a new startup function, init(), and two
display classes, GrassRenderer and InteractiveMap, specifically for making
the usage of GRASS in Jupyter more simple and intuitive. GrassRenderer
renders GRASS maps as PNG images and InteractiveMap displays rasters and
vectors interactively with folium [1], a leaflet library for Python.

*The state of integration BEFORE GSoC:*
The previous integration of GRASS GIS and Jupyter Notebooks required a
cumbersome environment variable setup after launching GRASS from within the
notebook. There is an external python library grass_session that can be
installed to shorten this launch substantially but, as an external library,
it is not included in a typical GRASS install. Additionally, maps were
rendered as PNG images using a relatively unintuitive sequence: calling
d.erase, then modules from the display family and finally rendering the
image with IPython.display.Image(). There was also no simple way to zoom or
toggle between layers.

*The state of integration AFTER GSoC:*
With the help of my mentors, I introduced a new package grass.jupyter that
contains a new init() function to shorten the launch and two
display-related classes, GrassRenderer and InteractiveMap. GrassRenderer
wraps the previous approach, rendering PNG images but with a more intuitive
syntax. InteractiveMap, the other display-related class in `grass.jupyter`,
allows users to view GRASS vectors and rasters in folium, a leaflet library
for Python. After creating an instance of InteractiveMap, users can add
vectors and rasters with add_vector() and add_raster(). Users can also add
a layer control element with add_layer_control().

*Conclusion:*
In this project, I was successful in accomplishing the three goals stated
at the beginning (thanks to my mentors!):

   1. creating new initiation functions for the launch of GRASS GIS in
   Jupyter Notebooks (init())
   2. creating functions for more intuitive map display (GrassRenderer)
   3. introducing an interactive map display function (InteractiveMap)

I am grateful for the support I've received this summer and for the
opportunity to contribute to GRASS GIS. I'm looking forward to continuing
to improve `grass.jupyter`.

*Future Work:*

   - Height and width defaults in `GrassRenderer` should be derived from
   computational region
   - init() should fail and report an appropriate error if a mapset that
   doesn't exist is provided
   - Add folium Tooltip method to InteractiveMap, allowing users to access
   vector attribute data by clicking on feature
   - Add simpleCRS option to add_raster method in InteractiveMap
   - Improve color options in InteractiveMap
   - Add option to display rasters as vectors (pixels -> polygon) in
   InteractiveMap
   - Clip vectors to computational region in InteractiveMap (currently the
   whole vector dataset is displayed)
   - Add more interactive functions such as a timeline slider for temporal
   datasets
   - InteractiveMap doesn't allow users to fully access folium. In the
   future, a new interface that allows users direct access to folium should be
   added. For example, it could look like:
   gj.Raster("elevation").add_to(folium_map)

*Permanent Links:*
*OSGeo Wiki Page:*
https://trac.osgeo.org/grass/wiki/GSoC/2021/JupyterAndGRASS
*OSGeo-GRASS github project page:* https://github.com/OSGeo/grass/projects/7
*Github repo*:
https://github.com/chaedri/grass/tree/master/python/grass/jupyter

*Binder Examples:*
https://mybinder.org/v2/gh/OSGeo/grass/c173461?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fgrass_jupyter.ipynb
https://mybinder.org/v2/gh/OSGeo/grass/c173461?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fbasic_example_grass_jupyter.ipynb
https://mybinder.org/v2/gh/OSGeo/grass/c173461?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fhydrology.ipynb
https://mybinder.org/v2/gh/OSGeo/grass/c173461?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fviewshed_analysis.ipynb
https://mybinder.org/v2/gh/OSGeo/grass/c173461?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fsolar_potential.ipynb

*References:*
[1]  https://python-visualization.github.io/folium/index.html
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/soc/attachments/20210822/5c3cce5c/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: GrassRenderer.PNG
Type: image/png
Size: 348575 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/soc/attachments/20210822/5c3cce5c/attachment-0002.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: InteractiveMap.PNG
Type: image/png
Size: 298940 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/soc/attachments/20210822/5c3cce5c/attachment-0003.png>