The GRASS plugin provides access to GRASS GIS (see GRASS-PROJECT Literature and Web References) databases and functionalities. This includes visualization of GRASS raster and vector layers, digitizing vector layers, editing vector attributes, creating new vector layers and analysing GRASS 2D and 3D data with more than 400 GRASS modules.
In this Section we’ll introduce the plugin functionalities and give some examples on managing and working with GRASS data. Following main features are provided with the toolbar menu, when you start the GRASS plugin, as described in section sec_starting_grass :
To use GRASS functionalities and/or visualize GRASS vector and raster layers in QGIS, you must select and load the GRASS plugin with the Plugin Manager. Therefore go to the menu Plugins ‣ Manage Plugins, select GRASS and click [OK].
You can now start loading raster and vector layers from an existing GRASS LOCATION (see section sec_load_grassdata). Or you create a new GRASS LOCATION with QGIS (see section Creating a new GRASS LOCATION) and import some raster and vector data (see Section Importing data into a GRASS LOCATION) for further analysis with the GRASS Toolbox (see section The GRASS toolbox).
With the GRASS plugin, you can load vector or raster layers using the appropriate button on the toolbar menu. As an example we use the QGIS alaska dataset (see Section Sample Data). It includes a small sample GRASS LOCATION with 3 vector layers and 1 raster elevation map.
As you see, it is very simple to load GRASS raster and vector layers in QGIS. See following sections for editing GRASS data and creating a new LOCATION. More sample GRASS LOCATIONs are available at the GRASS website at http://grass.osgeo.org/download/sample-data/.
GRASS Data Loading
If you have problems loading data or QGIS terminates abnormally, check to make sure you have loaded the GRASS plugin properly as described in section sec_starting_grass.
GRASS data are stored in a directory referred to as GISDBASE. This directory often called grassdata, must be created before you start working with the GRASS plugin in QGIS. Within this directory, the GRASS GIS data are organized by projects stored in subdirectories called LOCATION. Each LOCATION is defined by its coordinate system, map projection and geographical boundaries. Each LOCATION can have several MAPSETs (subdirectories of the LOCATION) that are used to subdivide the project into different topics, subregions, or as workspaces for individual team members (Neteler & Mitasova 2008 Literature and Web References). In order to analyze vector and raster layers with GRASS modules, you must import them into a GRASS LOCATION (This is not strictly true - with the GRASS modules r.external and v.external you can create read-only links to external GDAL/OGR-supported data sets without importing them. But because this is not the usual way for beginners to work with GRASS, this functionality will not be described here.).
Figure GRASS location 1:
As an example here is how the sample GRASS LOCATION alaska, which is projected in Albers Equal Area projection with unit feet was created for the QGIS sample dataset. This sample GRASS LOCATION alaska will be used for all examples and exercises in the following GRASS GIS related chapters. It is useful to download and install the dataset on your computer Sample Data).
Figure GRASS location 2:
If that seemed like a lot of steps, it’s really not all that bad and a very quick way to create a LOCATION. The LOCATION ‘alaska` is now ready for data import (see section Importing data into a GRASS LOCATION). You can also use the already existing vector and raster data in the sample GRASS LOCATION ‘alaska’ included in the QGIS ‘Alaska’ dataset Sample Data and move on to Section The GRASS vector data model.
A user has only write access to a GRASS MAPSET he created. This means that besides access to his own MAPSET, each user can read maps in other user’s MAPSETs, but he can modify or remove only the maps in his own MAPSET.
All MAPSETs include a WIND file that stores the current boundary coordinate values and the currently selected raster resolution (Neteler & Mitasova 2008 Literature and Web References, see Section The GRASS region tool).
This Section gives an example how to import raster and vector data into the ‘alaska’ GRASS LOCATION provided by the QGIS ‘Alaska’ dataset. Therefore we use a landcover raster map landcover.img and a vector GML file lakes.gml from the QGIS ‘Alaska’ dataset Sample Data.
It is important to understand the GRASS vector data model prior to digitizing.
In general, GRASS uses a topological vector model.
This means that areas are not represented as closed polygons, but by one or more boundaries. A boundary between two adjacent areas is digitized only once, and it is shared by both areas. Boundaries must be connected and closed without gaps. An area is identified (and labeled) by the centroid of the area.
Besides boundaries and centroids, a vector map can also contain points and lines. All these geometry elements can be mixed in one vector and will be represented in different so called ‘layers’ inside one GRASS vector map. So in GRASS a layer is not a vector or raster map but a level inside a vector layer. This is important to distinguish carefully (Although it is possible to mix geometry elements, it is unusual and even in GRASS only used in special cases such as vector network analysis. Normally you should prefere to store different geometry elements in different layers.).
It is possible to store several ‘layers’ in one vector dataset. For example, fields, forests and lakes can be stored in one vector. Adjacent forest and lake can share the same boundary, but they have separate attribute tables. It is also possible to attach attributes to boundaries. For example, the boundary between lake and forest is a road, so it can have a different attribute table.
The ‘layer’ of the feature is defined by ‘layer’ inside GRASS. ‘Layer’ is the number which defines if there are more than one layer inside the dataset, e.g. if the geometry is forest or lake. For now, it can be only a number, in the future GRASS will also support names as fields in the user interface.
Attributes can be stored inside the GRASS LOCATION as DBase or SQLITE3 or in external database tables, for example PostgreSQL, MySQL, Oracle, etc.
Attributes in database tables are linked to geometry elements using a ‘category’ value.
‘Category’ (key, ID) is an integer attached to geometry primitives, and it is used as the link to one key column in the database table.
Learning the GRASS Vector Model
The best way to learn the GRASS vector model and its capabilities is to download one of the many GRASS tutorials where the vector model is described more deeply. See http://grass.osgeo.org/documentation/manuals/ for more information, books and tutorials in several languages.
To create a new GRASS vector layer with the GRASS plugin click the Create new GRASS vector toolbar icon. Enter a name in the text box and you can start digitizing point, line or polygon geometries, following the procedure described in Section Digitizing and editing a GRASS vector layer.
In GRASS it is possible to organize all sort of geometry types (point, line and area) in one layer, because GRASS uses a topological vector model, so you don’t need to select the geometry type when creating a new GRASS vector. This is different from Shapefile creation with QGIS, because Shapefiles use the Simple Feature vector model (see Section Creating new Vector layers).
Creating an attribute table for a new GRASS vector layer
If you want to assign attributes to your digitized geometry features, make sure to create an attribute table with columns before you start digitizing (see figure_grass_digitizing_5).
The digitizing tools for GRASS vector layers are accessed using the Edit GRASS vector layer icon on the toolbar. Make sure you have loaded a GRASS vector and it is the selected layer in the legend before clicking on the edit tool. Figure figure_grass_digitizing_2 shows the GRASS edit dialog that is displayed when you click on the edit tool. The tools and settings are discussed in the following sections.
Digitizing polygons in GRASS
If you want to create a polygon in GRASS, you first digitize the boundary of the polygon, setting the mode to ‘No category’. Then you add a centroid (label point) into the closed boundary, setting the mode to ‘Next not used’. The reason is, that a topological vector model links attribute information of a polygon always to the centroid and not to the boundary.
Figure GRASS digitizing 1:
|New Point||Digitize new point|
|New Line||Digitize new line|
|New Boundary||Digitize new boundary (finish by selecting new tool)|
|New Centroid||Digitize new centroid (label existing area)|
|Move vertex||Move one vertex of existing line or boundary and identify new position|
|Add vertex||Add a new vertex to existing line|
|Delete vertex||Delete vertex from existing line (confirm selected vertex by another click)|
|Move element||Move selected boundary, line, point or centroid and click on new position|
|Split line||Split an existing line to 2 parts|
|Delete element||Delete existing boundary, line, point or centroid (confirm selected element by another click)|
|Edit attributes||Edit attributes of selected element (note that one element can represent more features, see above)|
|Close||Close session and save current status (rebuilds topology afterwards)|
Table GRASS Digitizing 1: GRASS Digitizing Tools
The Category tab allows you to define the way in which the category values will be assigned to a new geometry element.
Figure GRASS digitizing 2:
Creating an additional GRASS ‘layer’ with QGIS
If you would like to add more layers to your dataset, just add a new number in the ‘Field (layer)’ entry box and press return. In the Table tab you can create your new table connected to your new layer.
The Settings tab allows you to set the snapping in screen pixels. The threshold defines at what distance new points or line ends are snapped to existing nodes. This helps to prevent gaps or dangles between boundaries. The default is set to 10 pixels.
Figure GRASS digitizing 3:
The Symbology tab allows you to view and set symbology and color settings for various geometry types and their topological status (e.g. closed / opened boundary).
Figure GRASS digitizing 4:
The Table tab provides information about the database table for a given ‘layer’. Here you can add new columns to an existing attribute table, or create a new database table for a new GRASS vector layer (see Section Creating a new GRASS vector layer).
Figure GRASS digitizing 5:
GRASS Edit Permissions
You must be the owner of the GRASS MAPSET you want to edit. It is impossible to edit data layers in a MAPSET that is not yours, even if you have write permissions.
The region definition (setting a spatial working window) in GRASS is important for working with raster layers. Vector analysis is by default not limited to any defined region definitions. But all newly-created rasters will have the spatial extension and resolution of the currently defined GRASS region, regardless of their original extension and resolution. The current GRASS region is stored in the $LOCATION/$MAPSET/WIND file, and it defines north, south, east and west bounds, number of columns and rows, horizontal and vertical spatial resolution.
With the Edit current GRASS region icon you can open a dialog to change the current region and the symbology of the GRASS region rectangle in the QGIS canvas. Type in the new region bounds and resolution and click [OK]. It also allows to select a new region interactively with your mouse on the QGIS canvas. Therefore click with the left mouse button in the QGIS canvas, open a rectangle, close it using the left mouse button again and click [OK].
The GRASS module g.region provide a lot more parameters to define an appropriate region extend and resolution for your raster analysis. You can use these parameters with the GRASS Toolbox, described in Section The GRASS toolbox.
The Open GRASS Tools box provides GRASS module functionalities to work with data inside a selected GRASS LOCATION and MAPSET. To use the GRASS toolbox you need to open a LOCATION and MAPSET where you have write-permission (usually granted, if you created the MAPSET). This is necessary, because new raster or vector layers created during analysis need to be written to the currently selected LOCATION and MAPSET.
Figure GRASS toolbox 1:
The GRASS Shell inside the GRASS Toolbox provides access to almost all (more than 330) GRASS modules through a command line interface. To offer a more user friendly working environment, about 200 of the available GRASS modules and functionalities are also provided by graphical dialogs within the GRASS plugin Toolbox.
The GRASS Shell inside the GRASS Toolbox provides access to almost all (more than 300) GRASS modules in a command line interface. To offer a more user friendly working environment, about 200 of the available GRASS modules and functionalities are also provided by graphical dialogs.
A complete list of GRASS modules available in the graphical Toolbox in QGIS version 2.0 is available in the GRASS wiki (http://grass.osgeo.org/wiki/GRASS-QGIS_relevant_module_list).
It is also possible to customize the GRASS Toolbox content. This procedure is described in Section Customizing the GRASS Toolbox.
As shown in figure_grass_toolbox_1 , you can look for the appropriate GRASS module using the thematically grouped Modules Tree or the searchable Modules List tab.
Clicking on a graphical module icon a new tab will be added to the toolbox dialog providing three new sub-tabs Options, Output and Manual.
The Options tab provides a simplified module dialog where you can usually select a raster or vector layer visualized in the QGIS canvas and enter further module specific parameters to run the module.
Figure GRASS module 1:
The provided module parameters are often not complete to keep the dialog clear. If you want to use further module parameters and flags, you need to start the GRASS Shell and run the module in the command line.
A new feature since QGIS 1.8 is the support for a show advanced options button below the simplified module dialog in the Options tab. At the moment it is only added to the module v.in.ascii as an example use, but will probably be part of more / all modules in the GRASS toolbox in future versions of QGIS. This allows to use the complete GRASS module options without the need to switch to the GRASS Shell.
Figure GRASS module 2:
The Output tab provides information about the output status of the module. When you click the [Run] button, the module switches to the Output tab and you see information about the analysis process. If all works well, you will finally see a Successfully finished message.
Figure GRASS module 3:
The Manual tab shows the HTML help page of the GRASS module. You can use it to check further module parameters and flags or to get a deeper knowledge about the purpose of the module. At the end of each module manual page you see further links to the Main Help index, the Thematic index and the Full index. These links provide the same information as if you use the module g.manual.
Display results immediately
If you want to display your calculation results immediately in your map canvas, you can use the ‘View Output’ button at the bottom of the module tab.
The following examples will demonstrate the power of some of the GRASS modules.
The first example creates a vector contour map from an elevation raster (DEM). Assuming you have the Alaska LOCATION set up as explained in Section Importing data into a GRASS LOCATION.
Since this is a large region, it will take a while to display. After it finishes rendering, you can open the layer properties window to change the line color so that the contours appear clearly over the elevation raster, as in The Vector Properties Dialog.
Next zoom in to a small mountainous area in the center of Alaska. Zooming in close you will notice that the contours have sharp corners. GRASS offers the v.generalize tool to slightly alter vector maps while keeping their overall shape. The tool uses several different algorithms with different purposes. Some of the algorithms (i.e. Douglas Peuker and Vertex reduction) simplify the line by removing some of the vertices. The resulting vector will load faster. This process will be used when you have a highly detailed vector, but you are creating a very small scale map, so the detail is unnecessary.
The simplify tool
Note that the QGIS fTools plugin has a Simplify geometries ‣ tool that works just like the GRASS v.generalize Douglas-Peuker algorithm.
However, the purpose of this example is different. The contour lines created by r.contour have sharp angles that should be smoothed. Among the v.generalize algorithms there is Chaikens which does just that (also Hermite splines). Be aware that these algorithms can add additional vertices to the vector, causing it to load even more slowly.
Figure GRASS module 4:
Other uses for r.contour
The procedure described above can be used in other equivalent situations. If you have a raster map of precipitation data, for example, then the same method will be used to create a vector map of isohyetal (constant rainfall) lines.
Several methods are used to display elevation layers and give a 3D effect to maps. The use of contour lines as shown above is one popular method often chosen to produce topographic maps. Another way to display a 3D effect is by hillshading. The hillshade effect is created from a DEM (elevation) raster by first calculating the slope and aspect of each cell, then simulating the sun’s position in the sky and giving a reflectance value to each cell. Thus you get sun facing slopes lighted and the slopes facing away from the sun (in shadow) are darkened.
You should now have the gtopo30 elevation with its colormap and transparency setting displayed above the grayscale hillshade map. In order to see the visual effects of the hillshading, turn off the gtopo30_shade map, then turn it back on.
Using the GRASS shell
The GRASS plugin in QGIS is designed for users who are new to GRASS, and not familiar with all the modules and options. As such, some modules in the toolbox do not show all the options available, and some modules do not appear at all. The GRASS shell (or console) gives the user access to those additional GRASS modules that do not appear in the toolbox tree, and also to some additional options to the modules that are in the toolbox with the simplest default parameters. This example demonstrates the use of an additional option in the r.shaded.relief module that was shown above.
Figure GRASS module 5:
The module r.shaded.relief can take a parameter zmult which multiplies the elevation values relative to the X-Y coordinate units so that the hillshade effect is even more pronounced.
Figure GRASS module 6:
The next example shows how a GRASS module can aggregate raster data and add columns of statistics for each polygon in a vector map.
Another useful feature inside the GRASS Toolbox is the GRASS LOCATION browser. In figure_grass_module_7 you can see the current working LOCATION with its MAPSETs.
In the left browser windows you can browse through all MAPSETs inside the current LOCATION. The right browser window shows some meta information for selected raster or vector layers, e.g. resolution, bounding box, data source, connected attribute table for vector data and a command history.
Figure GRASS module 7:
The toolbar inside the Browser tab offers following tools to manage the selected LOCATION:
Nearly all GRASS modules can be added to the GRASS toolbox. A XML interface is provided to parse the pretty simple XML files which configures the modules appearance and parameters inside the toolbox.
A sample XML file for generating the module v.buffer (v.buffer.qgm) looks like this:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE qgisgrassmodule SYSTEM "http://mrcc.com/qgisgrassmodule.dtd"> <qgisgrassmodule label="Vector buffer" module="v.buffer"> <option key="input" typeoption="type" layeroption="layer" /> <option key="buffer"/> <option key="output" /> </qgisgrassmodule>
The parser reads this definition and creates a new tab inside the toolbox when you select the module. A more detailed description for adding new modules, changing the modules group, etc. can be found on the QGIS wiki at http://hub.qgis.org/projects/quantum-gis/wiki/Adding_New_Tools_to_the_GRASS_Toolbox