Changes between Version 19 and Version 20 of GSoC/2021/JupyterAndGRASS
- Timestamp:
- 08/21/21 19:43:10 (4 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
GSoC/2021/JupyterAndGRASS
v19 v20 432 432 433 433 **Abstract:**\\ 434 Check back later...434 This project introduces a new subpackage for GRASS GIS, `grass.jupyter` that improves the integration of GRASS GIS with Jupyter Notebooks. Previously, using GRASS in Jupyter Notebooks required a cumbersome environment variable setup after launching GRASS from within the notebook. It also only allowed for simple, non-interactive map displays. The `grass.jupyter` subpackage for addresses both these issues by introducing a new startup function, `init()`, and two display classes, `GrassRenderer` and `InteractiveMap`. `GrassRenderer` renders GRASS displays as PNG images. `InteractiveMap` displays rasters and vectors in [https://python-visualization.github.io/folium/index.html folium], a leaflet library for Python. 435 435 436 436 **The state of integration BEFORE the start of GSoC:**\\ 437 Check back later...437 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, the previous integration allowed for maps to rendered as PNG images uses a unintuitive sequence of calling `d.erase`, then modules from the display family and finally rendering the image with IPython.display `Image()`. 438 438 439 439 **The state of integration AFTER GSoC:**\\ 440 Check back later... 440 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. Users create an instance of `GrassRenderer` then add elements to the rendering with GRASS display modules. The GRASS modules are called by using the name of module as a class method and replacing "." with "_" in the name. For example, to add a raster, one would call `GrassRenderer.d_rast(map="raster_name")`. 441 442 `InteractiveMap`, the other display-related class in `grass.jupyter`, allows users to view GRASS vectors and rasters in [https://python-visualization.github.io/folium/index.html 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()`. Folium only supports EPSG 4326 (for raster overlay) and EPSG 3857 (for vectors and coordinates) so `InteractiveMap` creates a temporary location, reprojects data then saves it to a temporary directory where it is imported by folium. 441 443 442 444 **Conclusion:**\\ 443 Check back later... 445 In this project, I was successful in accomplishing the three goals stated at the beginning (thanks to my mentors!): 446 447 1. creating new initiation functions for the launch of GRASS GIS in Jupyter Notebooks (`init()`) 448 449 2. creating functions for more intuitive map display (`GrassRenderer()`) 450 451 3. introducing an interactive map display function (`InteractiveMap()`) 452 453 The work I accomplished this summer paves the way for many future improvements, listed below in the Future Work section. In addition to some smaller modifications to `init()` and 'GrassRenderer', there remains a lot of work to be done on `InteractiveMap` or with other folium-GRASS classes/functions to fully access folium. 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`. 444 454 445 455 **Future Work:**\\ 446 456 * Height and width defaults in `GrassRenderer` should be derived from computational region 457 * `init()` should fail and report an appropriate error if a mapset that doesn't exist is provided 447 458 * Add folium Tooltip method to `InteractiveMap`, allowing users to access vector attribute data by clicking on feature 448 459 * Add simpleCRS option to `add_raster` method in `InteractiveMap` … … 463 474 || Jupyter: Non-interactive display || https://github.com/OSGeo/grass/pull/1668 || 464 475 || Interactive vector maps for Jupyter Notebooks || https://github.com/OSGeo/grass/pull/1710 || 465 || __getattr__shortcut for calling GRASS display modules || https://github.com/OSGeo/grass/pull/1723 ||476 || `__getattr__` shortcut for calling GRASS display modules || https://github.com/OSGeo/grass/pull/1723 || 466 477 || Add temporary files for Non-Interactive Display || https://github.com/OSGeo/grass/pull/1727 || 467 478 || Raster Support for Interactive Jupyter maps with folium || https://github.com/OSGeo/grass/pull/1769 || 468 479 || Test Module for Non-interactive display in Jupyter Notebooks || https://github.com/OSGeo/grass/pull/1739 || 469 ... two more PRs coming! 480 || Docstring improvements || https://github.com/OSGeo/grass/pull/1800 || 481 || Example notebooks || https://github.com/OSGeo/grass/pull/1787 || 470 482 471 483 … … 479 491 https://github.com/chaedri/grass/tree/master/python/grass/jupyter 480 492 481 **Binder Examples:**\\493 Binder Examples: \\ 482 494 [https://mybinder.org/v2/gh/OSGeo/grass/5e2fd30?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fjupyter_integration.ipynb grass.jupyter tutorial] 483 495 [more links coming...]
