03_GIS_objects_pygrass.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this notebook we will see and use some of the GRASS GIS structure object. You can read more about GRASSDATA, LOCATION and MAPSET in the <a href=\"http://grass.osgeo.org/grass71/manuals/helptext.html\" target=\"_blank\">GRASS GIS introduction</a>."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# GISDBASE"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The GISDBASE, also called *GRASSDATA* is a directory with the structure used by GRASS GIS to store the data, it contain at least a LOCATION.\n",
    "\n",
    "More info about <a href=\"http://grass.osgeo.org/grass71/manuals/libpython/pygrass.gis.html#pygrass.gis.Gisdbase\" target=\"_blank\">Gisdbase class</a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass.pygrass.gis import Gisdbase\n",
    "loc_name = 'nc_basic_spm_grass7'\n",
    "#loc_name = 'loc_ncarolina_spm_base0.3.1'\n",
    "mapset_name = 'user1'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gisdb = Gisdbase()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gisdb.name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gisdb.locations()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# LOCATION"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The LOCATION is some geographic extent of interest that contains data sets that [should] all be in the **same coordinate system**.\n",
    "\n",
    "More info about <a href=\"http://grass.osgeo.org/grass71/manuals/libpython/pygrass.gis.html#pygrass.gis.Location\" target=\"_blank\">Location class</a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass.pygrass.gis import Location\n",
    "\n",
    "Location()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gisdb[loc_name]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "northc = gisdb[loc_name]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "northc.gisdbase"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "northc.name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "northc.mapsets()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# MAPSET"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a MAPSET you can **organize GIS maps thematically or geographically or by project or whatever**. Every GRASS session runs under the name of a MAPSET. A MAPSET may be a geographical subset or as large as the parent LOCATION.\n",
    "\n",
    "More info about <a href=\"http://grass.osgeo.org/grass71/manuals/libpython/pygrass.gis.html#pygrass.gis.Mapset\" target=\"_blank\">Mapset class</a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass.pygrass.gis import Mapset\n",
    "\n",
    "Mapset()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "northc[mapset_name]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "user1 = northc['user1']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "user1.gisdbase"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "user1.location"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "user1.name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "user1.glist('raster')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%timeit Mapset('user1').glist('raster')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass.script import core as gcore"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gcore.list_grouped('raster')['PERMANENT']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%timeit gcore.list_grouped('raster')['PERMANENT']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "Mapset('PERMANENT').glist('raster', pattern='el*')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Region"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The REGION may be the entire area or subset of the chosen LOCATION. **It is defined by northern, southern, eastern, and western bounds, as well as the raster grid resolution**. It is controlled by the <a href=\"http://grass.osgeo.org/grass70/manuals/g.region.html\">g.region</a> module and is of **primary importance for raster operations**\n",
    "\n",
    "More info about <a href=\"http://grass.osgeo.org/grass71/manuals/libpython/pygrass.gis.html#module-pygrass.gis.region\" target=\"_blank\">Region class</a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass.pygrass.gis.region import Region"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "reg = Region()\n",
    "reg"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "reg.items()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "reg.north"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "reg.ewres"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "reg.get_bbox()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Bbox"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Is a element of pygrass to create a Bounding Box, it use the <a href=\"http://grass.osgeo.org/programming7/structbound__box.html\" target=\"_blank\">bound_box GRASS GIS C structure</a>.\n",
    "\n",
    "More info about <a href=\"http://grass.osgeo.org/grass71/manuals/libpython/pygrass.vector.html#pygrass.vector.basic.Bbox\" target=\"_blank\">Bbox class</a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from grass.pygrass.vector.basic import Bbox\n",
    "from grass.pygrass.vector.geometry import Point"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bbox = Bbox()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bbox"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bbox.north = 10\n",
    "bbox.east = 10"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "point = Point(5, 5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bbox.contains(point)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Summary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have seen:\n",
    "\n",
    "* <a href=\"http://grass.osgeo.org/grass71/manuals/libpython/pygrass.gis.html#pygrass.gis.Gisdbase\" target=\"_blank\">GISDBASE</a>, <a href=\"http://grass.osgeo.org/grass71/manuals/libpython/pygrass.gis.html#pygrass.gis.Location\" target=\"_blank\">LOCATION</a> and <a href=\"http://grass.osgeo.org/grass71/manuals/libpython/pygrass.gis.html#pygrass.gis.Mapset\" target=\"_blank\">MAPSET</a> classes to work with the GRASS GIS file structure\n",
    "* <a href=\"http://grass.osgeo.org/grass71/manuals/libpython/pygrass.gis.html#module-pygrass.gis.region\" target=\"_blank\">REGION</a> element to obtain informations about GRASS GIS Region and work with it\n",
    "* <a href=\"http://grass.osgeo.org/grass71/manuals/libpython/pygrass.vector.html#pygrass.vector.basic.Bbox\" target=\"_blank\">BBOX</a> class to work with bounding box"
   ]
  }
 ],
 "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
}