{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Improved Integration of GRASS and Jupyter\n",
    "\n",
    "As part of Google Summer of Code 2021, we've been working to shorten and simplify the launch of GRASS in Jupyter and imporve the map displays. It is experimentally included in version 8.0 as a preview and will be officially available in version 8.2. You can find out more about the project and follow the progress on the [GRASS wiki page](https://trac.osgeo.org/grass/wiki/GSoC/2021/JupyterAndGRASS).\n",
    "\n",
    "In addition to simplifying the launch of *GRASS GIS* with `init()`, `grass.jupyter` has two main dislay classes, `GrassRenderer` and `InteractiveMap`. Using the *GRASS* rendering engine in the background, `GrassRenderer` creates maps as PNG images. `InteractiveMap` displays *GRASS GIS* rasters and vectors with [*folium*](http://python-visualization.github.io/folium/), a [*leaflet*](https://leafletjs.com/) library for *Python*.\n",
    "\n",
    "This interactive notebook is available online thanks to the [https://mybinder.org](Binder) service. To run the select part (called a *cell*), hit `Shift + Enter`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Start GRASS GIS"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import subprocess\n",
    "import sys\n",
    "\n",
    "# Ask GRASS GIS where its Python packages are.\n",
    "sys.path.append(\n",
    "    subprocess.check_output([\"grass\", \"--config\", \"python_path\"], text=True).strip()\n",
    ")\n",
    "\n",
    "# Import GRASS packages\n",
    "import grass.script as gs\n",
    "import grass.jupyter as gj\n",
    "\n",
    "# Start GRASS Session\n",
    "session = gj.init(\"../../data/grassdata\", \"nc_basic_spm_grass7\", \"user1\")\n",
    "\n",
    "# Set computational region to the elevation raster.\n",
    "gs.run_command(\"g.region\", raster=\"elevation\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## GRASS Renderer\n",
    "\n",
    "The `GrassRenderer` class creates and displays GRASS maps as PNG images. There are two ways to add elements to the display. First, the name of the *GRASS* display module can be called as an attribute by replacing the \".\" with \"\\_\" in the module name. For example:\n",
    "````\n",
    "m = GrassRenderer()\n",
    "m.d_rast(map=\"elevation\")\n",
    "````\n",
    "\n",
    "Alternatively, *GRASS* display modules can be called with the `run()` method:\n",
    "````\n",
    "m = GrassRenderer()\n",
    "m.run(\"d.rast\", map=\"elevation\")\n",
    "````\n",
    "\n",
    "To display the image, call `show()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create GrassRenderer instance\n",
    "img = gj.GrassRenderer()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Add a raster, vector and legend to the map\n",
    "img.d_rast(map=\"elevation\")\n",
    "img.d_vect(map=\"streams\")\n",
    "img.d_legend(raster=\"elevation\", at=(55, 95, 80, 84), flags=\"b\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Display map\n",
    "img.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also have multiple instances of `GrassRenderer`. Here, we create another map then go back and modify the first map."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Make a second instance.\n",
    "# Just for variety, we'll make this one a different size\n",
    "img2 = gj.GrassRenderer(height=200, width=220)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Add a some layers\n",
    "# We can also add layers with the run() methods\n",
    "img2.run(\"d.rast\", map=\"elevation_shade\")\n",
    "img2.run(\"d.vect\", map=\"roadsmajor\")\n",
    "\n",
    "# Display second map\n",
    "img2.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Then, we return to the first instance and continue to modify and display it\n",
    "# Notice that layers a drawn in the order they are added\n",
    "img.run(\"d.vect\", map = \"zipcodes\", color=\"red\", fill_color=\"none\")\n",
    "img.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default the display extent (and resolution if applicable) is derived from the first raster or vector layer:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "img3 = gj.GrassRenderer()\n",
    "img3.d_vect(map=\"boundary_state\")\n",
    "img3.d_rast(map=\"geology\")\n",
    "img3.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To respect computational region, set `use_region=True`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "img4 = gj.GrassRenderer(use_region=True)\n",
    "img4.d_vect(map=\"boundary_state\")\n",
    "img4.d_rast(map=\"geology\")\n",
    "img4.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also use a saved region:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gs.run_command(\"g.region\", save=\"myregion\", n=224000, s=222000, w=633500, e=637300)\n",
    "img5 = gj.GrassRenderer(saved_region=\"myregion\")\n",
    "img5.d_rast(map=\"elevation\")\n",
    "img5.d_rast(map=\"lakes\")\n",
    "img5.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interactive Map Display\n",
    "\n",
    "The `InteractiveMap` class displays *GRASS GIS* rasters and vectors with [*folium*](http://python-visualization.github.io/folium/), a [*leaflet*](https://leafletjs.com/) library for *Python*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create Interactive Map\n",
    "fig = gj.InteractiveMap(width = 600)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Add raster, vector and layer control to map\n",
    "fig.add_raster(\"elevation\")\n",
    "fig.add_vector(\"roadsmajor\")\n",
    "fig.add_layer_control(position = \"bottomright\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Display map\n",
    "fig.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Save InteractiveMap as HTML\n",
    "\n",
    "To share or embed the map in a website, we can export it has an HTML file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig.save(filename=\"test_map.html\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## GRASS 3D Renderer\n",
    "\n",
    "The `Grass3dRenderer` class creates 3D visualizations as PNG images. The *m.nviz.image* module is used in the background and the function `render()` accepts parameters of this module.\n",
    "The `Grass3dRenderer` objects have `overlay` attribute which can be used in the same way as `GrassRenderer` and 2D images on top of the 3D visualization.\n",
    "To display the image, call `show()`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, let's create the object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "img = gj.Grass3dRenderer()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, render a 3D visualization of an elevation raster as a surface colored using, again, the elevation raster:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "img.render(elevation_map=\"elevation\", color_map=\"elevation\", perspective=20)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To add a raster legend on the image as an overlay using the 2D rendering capabilities accessible with `overlay.d_legend`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "img.overlay.d_legend(raster=\"elevation\", at=(60, 97, 87, 92))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we show "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "img.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, let's color the elevation surface using a landuse raster (note that the call to `render` removes the result of the previous `render` as well as the current overlays):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "img.render(elevation_map=\"elevation\", color_map=\"landuse\", perspective=20)\n",
    "img.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Switching Mapsets and Session Management\n",
    "\n",
    "The `init` function returns a reference to a session object which can be used to manipulate the current session. The session is global, i.e., the global state of the environment is changed. The session object is a handle for accessing this global session. When the kernel for the notebooks shuts down or is restarted, the session ends automatically. The session can be explicitly ended using `session.finish()`, but that's usually not needed in notebooks.\n",
    "\n",
    "Additionally, the session object can be used to change the current mapset. Here, we will switch to mapset called *PERMANENT*:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "session.switch_mapset(\"PERMANENT\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we could add more data to the PERMANENT mapset or modify the existing data there. We don't need to do anything there, so we switch back to the mapset we were in before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "session.switch_mapset(\"user1\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}