notebook_5_c.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# GRASS Tool in C\n",
    "\n",
    "For some tools, C (or C++) is a good choice of language because an algorithm or model requires fine work with the data. For example, a loop in Python over all vector points or raster cells may be prohibitively slow. When this cannot be compensated by available Python libraries or use of GRASS C libraries through the ctypes API or grass.pygrass wrappers, writing a tool directly in C is the most common approach.\n",
    "\n",
    "GRASS tools written in C (and C++) can be distributed in exactly the same way as tools in Python. For Windows, they are compiled on project servers. For other systems, they are compiled on the user machine. Python, C, and C++ tools can be and are being published in the grass-addons repository with users noticing the difference only in case of bugs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Structure of a C Tool\n",
    "\n",
    "There is no difference for small tools comparing to Python tools except that the file with the source code is called main. There are still three files: source code, documentation, and a Makefile.\n",
    "\n",
    "Explore the directory with example tool called _r.example.twice_ which multiplies values in a raster map by two:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!ls r.example.twice/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Open _r.example.twice/main.c_ (using File Browser in JupyterLab).\n",
    "\n",
    "The file with the _main_ function should be called `main.c`. There can be multiple `.c` and `.h` files."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Compile and Install\n",
    "\n",
    "Here, we will compile and install the tool in the same way as a Python tool using _g.extension_: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass --tmp-location XY --exec g.extension r.example.twice url=r.example.twice"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In case of C, compilation is necessary to execute the program, so typically, the low-level command _make_ is used to do the compilation. The specific use may differ based on the development environment, but often you may want to compile whole GRASS GIS yourself and simply add the compiled tool to that build instead of installing it as an addon (which is what happens with _g.extension_). In that case, _make_ is used with `MODULE_TOPDIR` variable which is set to where the GRASS source code is, e.g.:\n",
    "\n",
    "```bash\n",
    "make MODULE_TOPDIR=~/Projects/grass/\n",
    "```\n",
    "\n",
    "If you are calling `make install` to install GRASS GIS after compilation, you need to do the same with your code:\n",
    "\n",
    "```bash\n",
    "make install MODULE_TOPDIR=~/Projects/grass/\n",
    "```\n",
    "\n",
    "This assumes you are developing a tool for grass-addons. If you are developing a tool for the main repository, `MODULE_TOPDIR=...` is not needed.\n",
    "\n",
    "Although this is most useful for developing tools in C, the same applies for Python tools as well.\n",
    "\n",
    "Using _g.extension_ with the `-d` flag, gives suggestion of a setup for complex cases in case _g.extension_ or the usage of _make_ above are not enough."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Test of the Interface\n",
    "\n",
    "The resulting interface is the same as for Python tools, for example `--help` works:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass --tmp-location XY --exec r.example.twice --help"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Test of the Computation\n",
    "\n",
    "Let's test the tool with raster _elevation_. First, check its metadata and then set the computational region to it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec r.info map=elevation\n",
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec g.region raster=elevation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now run the _r.example.twice_ tool (we use `--o` in the example as shorthand for `--overwrite`, so we can re-run the example multiple times):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec r.example.twice input=elevation output=test_twice --o"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Minimum and maximum in metadata of the new raster should be double the original value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass ~/grassdata/nc_basic_spm_grass7/foss4g --exec r.info map=test_twice"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will use a subprocess to render the result as a PNG image (without modifying our current environment):"
   ]
  },
  {
   "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=\"test_twice\")\n",
    "    # Save the image (in a standard notebook, we would just display the image now).\n",
    "    ortho_map.save(\"test_twice.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Display the image in the notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import Image\n",
    "\n",
    "Image(\"test_twice.png\")"
   ]
  }
 ],
 "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
}