notebook_2_grass_tools.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# GRASS Tool with Parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interface Definition for Scripts\n",
    "\n",
    "Since GRASS tools are executable scripts (or generally programs), the interface of a GRASS tool is the command line interface of a Python script. A dedicated function _grass.script.parser_ takes care of processing the command line arguments based on the interface description specified in a Python comment with a key-value syntax defined by GRASS GIS.\n",
    "\n",
    "The following is an example of a script which takes two parameters: name of a vector map and name of a raster map:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%writefile vector_to_raster.py\n",
    "#!/usr/bin/env python\n",
    "\n",
    "# %module\n",
    "# % description: Converts vector data to raster data\n",
    "# %end\n",
    "# %option G_OPT_V_INPUT\n",
    "# %end\n",
    "# %option G_OPT_R_OUTPUT\n",
    "# %end\n",
    "\n",
    "import subprocess\n",
    "import sys\n",
    "\n",
    "import grass.script as gs\n",
    "\n",
    "\n",
    "def main():\n",
    "    gs.parser()\n",
    "\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    main()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As before, we will make the script executable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!chmod u+x vector_to_raster.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Running the script with `--help` gives its interface described for command line use:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec ./vector_to_raster.py --help"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Running the script with `--interface-description` gives its interface described using XML which is useful for building other interfaces, e.g., GUI:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec ./vector_to_raster.py --interface-description"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Running the script with `--html-description` gives the command line interface described in HTML which later becomes a part of the tool's HTML documentation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec ./vector_to_raster.py --html-description > test.html"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import IFrame\n",
    "\n",
    "IFrame(\"test.html\", width=700, height=600)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Open the generated HTML file called _test.html_ from the File Browser (on the left in JupyterLab)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "On desktop, a graphical user interface for the tool would be available, too, accessible, e.g., through `--ui`:\n",
    "\n",
    "```bash\n",
    "grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec ./vector_to_raster.py --ui\n",
    "```\n",
    "\n",
    "The GUI window may look like this:\n",
    "\n",
    "![GUI with vector and raster parameters](img/vector_raster_gui.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using the Parameters\n",
    "\n",
    "The values parsed from the command line are stored in a dictionary returned by the _parse_ function. They can be accessed using `dictionary[\"name\"]` syntax where _name_ is the name of the parameter. We are using the predefined standard options for vector input and raster output which are named _input_ and _output_. Here, we add an additional parameter named _layer_ also referred to as _field_ which can be used to specify a layer or a subset in the input vector dataset (more on that later).\n",
    "\n",
    "We will store the three values in Python variables and pass them to _v.to.rast_ which will do the actual processing for us."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%writefile vector_to_raster.py\n",
    "#!/usr/bin/env python\n",
    "\n",
    "# %module\n",
    "# % description: Converts vector data to raster data\n",
    "# %end\n",
    "# %option G_OPT_V_INPUT\n",
    "# %end\n",
    "# %option G_OPT_V_FIELD\n",
    "# %end\n",
    "# %option G_OPT_R_OUTPUT\n",
    "# %end\n",
    "\n",
    "import subprocess\n",
    "import sys\n",
    "\n",
    "import grass.script as gs\n",
    "\n",
    "\n",
    "def main():\n",
    "    options, flags = gs.parser()\n",
    "    vector_input = options[\"input\"]\n",
    "    vector_layer = options[\"layer\"]\n",
    "    raster_output = options[\"output\"]\n",
    "\n",
    "    gs.run_command(\n",
    "        \"v.to.rast\",\n",
    "        input=vector_input,\n",
    "        layer=vector_layer,\n",
    "        output=raster_output,\n",
    "        use=\"val\",\n",
    "    )\n",
    "\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    main()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now execute the tool. There is no need to make it executable again because we are using the same name as before and the execute permissions are preserved even when the file contents change.\n",
    "\n",
    "The command line parameters in GRASS GIS are key-value pairs which are using syntax `key=value`. In the CLI world, this is sometimes called _named arguments_ and it is similar to Python keyword arguments.\n",
    "\n",
    "The dataset we are using here has vector points called _firestations_ and we will create new raster called _stations_. Before running the processing, we will set the computation region to the extent of _firestations_ and will use resolution 30 meters (this is set and preserved for the mapset between the individual runs of `grass ... --exec`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec g.region vector=firestations res=100\n",
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec ./vector_to_raster.py input=firestations output=stations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Try running the above again. The raster named _stations_ now exists, so GRASS GIS will automatically detect that and ask you to use `--overwrite` if you want to replace the existing data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec ./vector_to_raster.py input=firestations output=stations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With added `--overwrite`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec ./vector_to_raster.py input=firestations output=stations --overwrite"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's view data range of the newly created raster:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec r.info map=stations -r"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To view the data in the notebook we will render the raster using _grass.jupyter.Map_. Usually, we would just create a GRASS session or already have one. However, to keep our development environment as is, we will avoid creating a session in the notebook process, but using a subprocess to do the rendering into a PNG image. The following uses the `%%python` magic to execute Python code in a subprocess:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%python\n",
    "import subprocess\n",
    "import sys\n",
    "\n",
    "sys.path.append(\n",
    "    subprocess.check_output([\"grass\", \"--config\", \"python_path\"], text=True).strip()\n",
    ")\n",
    "\n",
    "import grass.script as gs\n",
    "import grass.jupyter as gj\n",
    "import grass.script.setup  # Needed only in 8.2 and older.\n",
    "\n",
    "with grass.script.setup.init(\"~/grassdata/nc_basic_spm_grass7/foss4g\") as session:\n",
    "    ortho_map = gj.Map()\n",
    "    ortho_map.d_rast(map=\"stations\")\n",
    "    # Save the image (in a standard notebook, we would just display the image now).\n",
    "    ortho_map.save(\"stations.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, use _Image_ from _IPython.display_ to display the PNG:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import Image\n",
    "\n",
    "Image(\"stations.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## General Parameter Definition\n",
    "\n",
    "To add general parameters such as text and numbers, we can use the following key-value syntax enclosed in `%option` and `%end`:\n",
    "\n",
    "```python\n",
    "# %option\n",
    "# % key1: value1\n",
    "# % key2: value2\n",
    "# % key3: value3\n",
    "# %end\n",
    "```\n",
    "\n",
    "Let's say we want to allow users of our tool to specify the raster value which is used where vector features are present. We will name it _value_ (`key: value`) and make it required (`required: yes`). The data type we will use is _double_ (`type: double`) which we can use as _float_ in Python. The following puts all these together:\n",
    "\n",
    "```python\n",
    "# %option\n",
    "# % key: value\n",
    "# % type: double\n",
    "# % required: yes\n",
    "# % description: Raster cell value where features are\n",
    "# %end\n",
    "```\n",
    "\n",
    "Here is the full script. The values come as strings, so for raster value, we convert the string to float (`float(options[\"value\"])`), although in this case we don't have to because we just pass it to the _v.to.rast_ subprocess and a string would work in that context too."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%writefile vector_to_raster.py\n",
    "#!/usr/bin/env python\n",
    "\n",
    "# %module\n",
    "# % description: Converts vector data to raster data\n",
    "# %end\n",
    "# %option G_OPT_V_INPUT\n",
    "# %end\n",
    "# %option G_OPT_V_FIELD\n",
    "# %end\n",
    "# %option G_OPT_R_OUTPUT\n",
    "# %end\n",
    "# %option\n",
    "# % key: value\n",
    "# % type: double\n",
    "# % required: yes\n",
    "# % description: Raster cell value where features are\n",
    "# %end\n",
    "\n",
    "import subprocess\n",
    "import sys\n",
    "\n",
    "import grass.script as gs\n",
    "\n",
    "\n",
    "def main():\n",
    "    options, flags = gs.parser()\n",
    "    vector_input = options[\"input\"]\n",
    "    vector_layer = options[\"layer\"]\n",
    "    raster_output = options[\"output\"]\n",
    "    value = float(options[\"value\"])\n",
    "\n",
    "    gs.run_command(\n",
    "        \"v.to.rast\",\n",
    "        input=vector_input,\n",
    "        layer=vector_layer,\n",
    "        output=raster_output,\n",
    "        use=\"val\",\n",
    "        value=value,\n",
    "    )\n",
    "\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    main()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, let's add the new parameter `value=5`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec ./vector_to_raster.py input=firestations output=stations_value value=5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The data range the raster is now 5-5, i.e., all values are 5:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec r.info map=stations_value -r"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using the New Tool from Python\n",
    "\n",
    "The tool can be used from Python just like the other GRASS tools.\n",
    "\n",
    "Here is a Python script which creates a GRASS session and calls our new tool:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%python\n",
    "import subprocess\n",
    "import sys\n",
    "\n",
    "sys.path.append(\n",
    "    subprocess.check_output([\"grass\", \"--config\", \"python_path\"], text=True).strip()\n",
    ")\n",
    "\n",
    "import grass.script as gs\n",
    "import grass.script.setup\n",
    "\n",
    "\n",
    "def main():\n",
    "    with grass.script.setup.init(\"~/grassdata/nc_basic_spm_grass7/foss4g\") as session:\n",
    "        gs.run_command(\n",
    "            \"vector_to_raster.py\",\n",
    "            input=\"firestations\",\n",
    "            output=\"stations_python\",\n",
    "            value=5,\n",
    "        )\n",
    "\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    main()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Existing Interfaces for Generating Wrappers and Boilerplates\n",
    "\n",
    "Often, a new tool is somehow wrapping or extending an existing tool or is similar to one. To quickly generate a boilerplate code in such cases, we can run any GRASS tool with `--script`. Unfortunately, `--script` does not currently output standard options, so the generated definitions are unnecessarily complicated.\n",
    "\n",
    "Given that the same structure is needed every time, it is a good idea to use `--script` or copy-paste code from existing tools or examples. In the GRASS GIS source code, the Python scripts are under _[scripts](https://github.com/OSGeo/grass/tree/releasebranch_8_2/scripts)_ and _[temporal](https://github.com/OSGeo/grass/tree/releasebranch_8_2/temporal)_. Tools in the grass-addons repository are not organized by language, but many of the tools are in Python.\n",
    "\n",
    "Here is how to get a Python script boilerplate from _v.to.rast_ (which itself is in written C):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass --tmp-location XY --exec v.to.rast --script"
   ]
  }
 ],
 "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
}