{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Try GRASS GIS in Jupyter Notebook with Python and grass.jupyter\n",
    "\n",
    "[<img src=\"../../man/grass_logo.png\" alt=\"GRASS GIS\" style=\"width:200px;\"/>](https://grass.osgeo.org/)\n",
    "\n",
    "This is a quick introduction to *GRASS GIS* in a *Jupyter Notebook* using the `grass.jupyter` package and the *Python* scripting language. The `grass.jupyter` package shortens the launch of *GRASS GIS* in *Jupyter Notebook* and provides several useful classes for creating, displaying and saving *GRASS GIS* maps. This notebook can be directly compared with [basic_example.ipynb](basic_example.ipynb) to see how the package improves the integration of *GRASS GIS* and *Jupyter Notebooks*.\n",
    "\n",
    "\n",
    "The `grass.jupyter` package was written as part of Google Summer of Code in 2021. For more information, visit the [wiki page](https://trac.osgeo.org/grass/wiki/GSoC/2021/JupyterAndGRASS).\n",
    "\n",
    "\n",
    "Examples here are using a sample GRASS GIS dataset for North Carolina, USA. The dataset is included in this environment.\n",
    "\n",
    "## Usage\n",
    "\n",
    "To run the selected part which is called a cell, hit `Shift + Enter`.\n",
    "\n",
    "## Start\n",
    "\n",
    "There are several ways to use GRASS GIS. When using Python in a notebook, we usually find GRASS GIS Python packages first, import them, initialize GRASS GIS session, and set several variables useful for using GRASS GIS in a notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import Python standard library and IPython packages we need.\n",
    "import os\n",
    "import subprocess\n",
    "import sys\n",
    "\n",
    "# Ask GRASS GIS where its Python packages are.\n",
    "gisbase = subprocess.check_output([\"grass\", \"--config\", \"path\"], text=True).strip()\n",
    "os.environ[\"GISBASE\"] = gisbase\n",
    "sys.path.append(os.path.join(gisbase, \"etc\", \"python\"))\n",
    "\n",
    "# Import the GRASS GIS packages we need.\n",
    "import grass.script as gs\n",
    "import grass.jupyter as gj\n",
    "\n",
    "# Start GRASS Session\n",
    "gj.init(\"../../data/grassdata\", \"nc_basic_spm_grass7\", \"user1\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Raster buffer\n",
    "\n",
    "Set computational region and create multiple buffers in given distances\n",
    "around lakes represented as raster:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gs.parse_command(\"g.region\", raster=\"lakes\", flags=\"pg\")\n",
    "gs.run_command(\"r.buffer\", input=\"lakes\", output=\"lakes_buff\", distances=[60, 120, 240, 500])\n",
    "\n",
    "# Start a GrassRenderer\n",
    "img = gj.GrassRenderer()\n",
    "\n",
    "# Add a raster and vector to the map\n",
    "img.d_rast(map=\"lakes_buff\")\n",
    "img.d_legend(raster=\"lakes_buff\", range=(2, 5), at=(80, 100, 2, 10))\n",
    "\n",
    "# Display map\n",
    "img.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Vector buffer\n",
    "\n",
    "Create a negative buffer around state boundary represented as a vector.\n",
    "Vector modules typically don't follow computational region,\n",
    "but we set it to inform display modules about our area of interest."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gs.run_command(\"v.buffer\", input=\"boundary_state\", output=\"buffer\", distance=-10000)\n",
    "gs.parse_command(\"g.region\", vector=\"boundary_state\", flags=\"pg\")\n",
    "\n",
    "# Start another GrassRenderer\n",
    "img2 = gj.GrassRenderer()\n",
    "\n",
    "# Add vector layers and legend\n",
    "img2.d_vect(map=\"boundary_state\", fill_color=\"#5A91ED\", legend_label=\"State boundary\")\n",
    "img2.d_vect(map=\"buffer\", fill_color=\"#F8766D\", legend_label=\"Inner portion\")\n",
    "img2.d_legend_vect(at=(10, 35))\n",
    "\n",
    "# Display map\n",
    "img2.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Additional GRASS Information and Tutorials\n",
    "\n",
    "To find more information on what one can do with GRASS GIS APIs, check out:\n",
    "    \n",
    " - [GRASS GIS Manual](https://grass.osgeo.org/grass-stable/manuals)\n",
    "    \n",
    " - [GRASS Python API Manual](https://grass.osgeo.org/grass-stable/manuals/libpython)\n",
    "\n",
    "For more Jupyter Notebook GRASS GIS tutorials, visit:\n",
    " - [Try GRASS GIS online](https://grass.osgeo.org/learn/tryonline/)\n",
    "\n",
    "## What else is in the sample North Carolina dataset?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(gs.read_command(\"g.list\", type=\"all\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What other GRASS modules can I try in this notebooks?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(gs.read_command(\"g.search.modules\", flags=\"g\"))"
   ]
  }
 ],
 "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
}