08_Raster_pygrass.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Raster"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The pygrass interface for raster maps is divided in 3 classes that represent different ways to interact with rasters. In order to give greater freedom of implementation to users and developers, each class\n",
    "uses a different C API, providing the tools to fit different needs. \n",
    "\n",
    "The **RasterRow** class reads the content of the raster row by row and writes it in a sequential mode: row after row.\n",
    "To read and write the same map at the same time is not supported by the RasterRow class.\n",
    "\n",
    "The **RasterRowIO** class implements a row cache that allows users to read and re-read raster rows randomly.\n",
    "\n",
    "The **RasterSegment** class divides the map into several tiles, each tile is saved into a file. With this class it is possible to read and write the pixel value randomly at the same time in the same map.\n",
    "\n",
    "All the Raster classes shared common methods to open, read and get raster information and write meta-data like: categories and history. Similarly to Vector class, the same syntax has been used to instantiate a raster object.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from __future__ import (nested_scopes, generators, division, absolute_import,\n",
    "                        with_statement, print_function, unicode_literals)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Read raster map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass.pygrass.raster import RasterRow"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "elev = RasterRow('elevation')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "elev.exist()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "elev.mapset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Open a raster map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "elev.open('r')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "elev[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "elev[0]/100."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "np.sin(elev[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query a raster using a Point object"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Return Region object in Bbox format"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass.pygrass.gis.region import Region\n",
    "reg = Region()\n",
    "reg_bbox = reg.get_bbox()\n",
    "print( reg_bbox)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create two point object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass.pygrass.vector import geometry\n",
    "poi1 = geometry.Point(643521.76, 223101.31)\n",
    "poi2 = geometry.Point(223101.31, 640000.76)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(elev.get_value(poi1))\n",
    "print(elev.get_value(poi2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check if contained in the region"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(reg_bbox.contains(poi1))\n",
    "print(reg_bbox.contains(poi2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Write a raster map"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Write a new raster map from existing one"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Read the *elevation* map and write new map with value divided by 10"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new = RasterRow('newele')\n",
    "new.open('w', overwrite=True)\n",
    "for row in elev:\n",
    "    # the row is a Buffer class to load it\n",
    "    # grass.pygrass.raster.buffer.Buffer\n",
    "    new.put_row(row/10)\n",
    "new.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check if the new raster map exists"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new.exist()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Write a new raster map starting from scratch"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To create a raster from scratch you have to create row using a **Buffer** istance, so you open new raster map in write mode"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass.pygrass.raster.buffer import Buffer\n",
    "\n",
    "# create the new raster and open it in write mode\n",
    "newscratch = RasterRow('newscratch')\n",
    "newscratch.open('w', overwrite=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "now you are going to write cell by cell for each row"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# create an empty row\n",
    "newrow = Buffer((reg.cols,), mtype='CELL')\n",
    "    \n",
    "# we create a raster to fill all the GRASS GIS region\n",
    "for r in range(reg.rows):\n",
    "    newrow[:] = np.random.random_integers(0, 1000, size=newrow.size)\n",
    "    # Add row to the raster\n",
    "    newscratch.put_row(newrow)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally you have to close the map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "newscratch.close()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from show import show"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "show(newscratch.name.encode())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check if the new map exist and the range of data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "newscratch = RasterRow('newscratch')\n",
    "newscratch.open('r')\n",
    "print(newscratch.exist())\n",
    "print(newscratch.info)\n",
    "newscratch.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Object contained in a Raster map"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Info"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The **Info** class contain all the information about a raster map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "elev.open('r')\n",
    "elev.info.mapset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "eleinfo = elev.info"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you can obtain several informations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(eleinfo.range)\n",
    "print(eleinfo.mapset)\n",
    "print(eleinfo.south)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "eleinfo."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## History"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The **History** class contain the information about history of a map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "elev.open()\n",
    "elehisto = elev.hist"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you can obtain several informations like creator, date of creation, keywords etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(elehisto.creator)\n",
    "#print(elehisto.date)\n",
    "print(elehisto.keyword)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Categories"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The **Category** class contain the information about categories of raster, if they are present"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "land = RasterRow('landuse')\n",
    "land.open()\n",
    "land.cats"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you can obtain more information about categories"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "landcats = land.cats\n",
    "print(landcats.labels())\n",
    "print(landcats.ncats())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You could also rewrite the cats using a rules files (for example newrules.txt) containg:"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "0:undefined\n",
    "1:developed\n",
    "2:agri\n",
    "3:herba\n",
    "4:shru\n",
    "5:fore\n",
    "6:water\n",
    "7:sedi"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "landcats.write_rules('newrules.txt')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Summary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We saw how:\n",
    "\n",
    "* **read** and query a Raster\n",
    "* **write** a raster: reading from existing one and from the scratch\n",
    "* the **Info** element for information of a raster\n",
    "* the **History** element for history of a raster\n",
    "* the **Category** element for categories if they exist"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exercise"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Write a function that do the same operation of:\n",
    "    \n",
    "    r.mapcalc expression=\"new = if(elevation>100, elevation, 0)\"\n",
    "\n",
    "not using Modules class"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Write a function that generate a random vector points map and query a raster map and add the value of the raster map to the attributes table of the vector map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}