notebook_5_using_the_tool.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using the New Tool"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%writefile viewscape.py\n",
    "#!/usr/bin/env python\n",
    "\n",
    "# %module\n",
    "# % description: Compute viewshed and compute statistics about visible parts of sample layers\n",
    "# % keyword: raster\n",
    "# % keyword: statistics\n",
    "# % keyword: viewshed\n",
    "# %end\n",
    "# %option G_OPT_R_ELEV\n",
    "# % description: Name of input elevation raster map\n",
    "# % guisection: Input\n",
    "# %end\n",
    "# %option G_OPT_M_COORDS\n",
    "# % guisection: Input\n",
    "# %end\n",
    "# %option G_OPT_R_INPUTS\n",
    "# % guisection: Input\n",
    "# %end\n",
    "# %option G_OPT_F_OUTPUT\n",
    "# % guisection: Output\n",
    "# %end\n",
    "# %option\n",
    "# % key: format\n",
    "# % type: string\n",
    "# % required: yes\n",
    "# % options: json,csv\n",
    "# % label: Output format\n",
    "# % descriptions: json;JSON (JavaScript Object Notation);csv;CSV (Comma Separated Values)\n",
    "# % answer: json\n",
    "# % guisection: Output\n",
    "# %end\n",
    "\n",
    "\n",
    "import atexit\n",
    "import subprocess\n",
    "import sys\n",
    "import csv\n",
    "import json\n",
    "import io\n",
    "\n",
    "import grass.script as gs\n",
    "\n",
    "\n",
    "def output_results(results, sample_rasters, file_name, file_format):\n",
    "    if file_format == \"json\":\n",
    "        with open(file_name, \"w\", encoding=\"utf-8\") as json_file:\n",
    "            json.dump(results, json_file, ensure_ascii=False, indent=4)\n",
    "    elif file_format == \"csv\":\n",
    "        with open(file_name, \"w\", newline=\"\", encoding=\"utf-8\") as csv_file:\n",
    "            header = [\"name\"]\n",
    "            header.extend(results[sample_rasters[0]].keys())\n",
    "            writer = csv.DictWriter(csv_file, fieldnames=header)\n",
    "            writer.writeheader()\n",
    "            for key, value in results.items():\n",
    "                row = {\"name\": key}\n",
    "                row.update(value)\n",
    "                writer.writerow(row)\n",
    "    else:\n",
    "        raise ValueError(f\"Unsupported or invalid format: {file_format}\")\n",
    "\n",
    "\n",
    "def clean(name):\n",
    "    gs.run_command(\"g.remove\", type=\"raster\", name=name, flags=\"f\", superquiet=True)\n",
    "\n",
    "\n",
    "def viewshed(\n",
    "    elevation,\n",
    "    coordinates,\n",
    "    sample_rasters,\n",
    "    output,\n",
    "    file_format,\n",
    "):\n",
    "    viewshed = gs.append_node_pid(\"tmp_viewshed\")\n",
    "    atexit.register(clean, viewshed)\n",
    "    gs.run_command(\n",
    "        \"r.viewshed\",\n",
    "        input=elevation,\n",
    "        output=viewshed,\n",
    "        coordinates=coordinates,\n",
    "        flags=\"cb\",\n",
    "    )\n",
    "    gs.run_command(\"r.null\", map=viewshed, setnull=0)\n",
    "    results = {}\n",
    "    for name in sample_rasters:\n",
    "        table_data = gs.read_command(\n",
    "            \"r.univar\",\n",
    "            map=name,\n",
    "            zones=viewshed,\n",
    "            quiet=True,\n",
    "            flags=\"t\",\n",
    "            separator=\"comma\",\n",
    "        )\n",
    "        reader = csv.DictReader(io.StringIO(table_data))\n",
    "        for row in reader:\n",
    "            del row[\"zone\"]\n",
    "            del row[\"label\"]\n",
    "            del row[\"non_null_cells\"]\n",
    "            del row[\"null_cells\"]\n",
    "            results[name] = row\n",
    "    output_results(\n",
    "        results=results,\n",
    "        sample_rasters=sample_rasters,\n",
    "        file_name=output,\n",
    "        file_format=file_format,\n",
    "    )\n",
    "\n",
    "\n",
    "def main():\n",
    "    options, flags = gs.parser()\n",
    "    coordinates = options[\"coordinates\"].split(\",\")\n",
    "    sample_rasters = options[\"input\"].split(\",\")\n",
    "    viewshed(\n",
    "        elevation=options[\"elevation\"],\n",
    "        coordinates=(float(coordinates[0]), float(coordinates[1])),\n",
    "        sample_rasters=sample_rasters,\n",
    "        output=options[\"output\"],\n",
    "        file_format=options[\"format\"],\n",
    "    )\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 viewscape.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Documentation\n",
    "\n",
    "The command line help now looks like this (`--help` or `--h`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_spm_08_grass7/foss4g --exec ./viewscape.py --help"
   ]
  },
  {
   "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_spm_08_grass7/foss4g --exec ./viewscape.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": [
    "## Desktop GUI\n",
    "\n",
    "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_spm_08_grass7/foss4g --exec ./viewscape.py --ui\n",
    "```\n",
    "\n",
    "The GUI window may look like this:\n",
    "\n",
    "![GUI with tabs](img/gui_example_sections.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Command Line Interface\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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_spm_08_grass7/foss4g --exec ./viewscape.py elevation=elevation coordinates=641583,226296 input=elevation,ndvi output=\"data.txt\""
   ]
  },
  {
   "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_spm_08_grass7/foss4g --exec ./viewscape.py elevation=elevation coordinates=641583,226296 input=elevation,ndvi output=\"data.txt\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With added `--overwrite` (or `--o`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_spm_08_grass7/foss4g --exec ./viewscape.py elevation=elevation coordinates=641583,226296 input=elevation,ndvi output=\"data.txt\" --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": [
    "!cat data.txt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other interfaces\n",
    "\n",
    "### WPS"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_spm_08_grass7/foss4g --exec ./viewscape.py --wps-process-description"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### JSON"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_spm_08_grass7/foss4g --exec ./viewscape.py elevation=elevation coordinates=641583,226296 input=elevation,ndvi output=\"data.txt\" --json"
   ]
  },
  {
   "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",
    "```"
   ]
  },
  {
   "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_spm_08_grass7/foss4g\") as session:\n",
    "        gs.run_command(\n",
    "            \"./viewscape.py\",\n",
    "            elevation=\"elevation\",\n",
    "            coordinates=(641_583,226_296),\n",
    "            input=[\"elevation\", \"ndvi\"],\n",
    "            output=\"data.json\",\n",
    "            overwrite=True,  # So that we can execute the notebook again.\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
}